ACK の使用を開始するリソースのライフサイクルと調整ステータス条件削除ポリシーリソースの採用クロスアカウントおよびクロスリージョンのリソースエラー処理と再試行動作 kro によるリソース構成次のステップ

ACK の概念

ACK は、AWS の実際の状態に照らしてマニフェストの目的の状態を継続的に調整することで、Kubernetes API を利用して AWS リソースを管理します。Kubernetes カスタムリソースを作成または更新すると、ACK は対応する AWS リソースを作成または変更するために必要な AWS API コールを実行し、ドリフトがないかモニタリングして、現在の状態を反映するように Kubernetes ステータスを更新します。このアプローチにより、クラスターと AWS との一貫性を維持しながら、使い慣れた Kubernetes ツールとワークフローを使用してインフラストラクチャを管理できます。

このトピックでは、ACK が Kubernetes API を利用して AWS リソースを管理する際の土台となる概念について説明します。

ACK の使用を開始する

ACK 機能を作成したら (「ACK 機能を作成する」を参照)、クラスターで Kubernetes マニフェストを使用して AWS リソースの管理を開始できます。

例えば、bucket.yaml でこの S3 バケットマニフェストを作成して、独自のバケット名を選択します。


apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: my-test-bucket
  namespace: default
spec:
  name: my-unique-bucket-name-12345

マニフェストを適用します。


kubectl apply -f bucket.yaml

ステータスを確認します。


kubectl get bucket my-test-bucket
kubectl describe bucket my-test-bucket

AWS にバケットが作成されたことを確認します。


aws s3 ls | grep my-unique-bucket-name-12345

Kubernetes リソースを削除します。


kubectl delete bucket my-test-bucket

AWS からバケットが削除されたことを確認します。


aws s3 ls | grep my-unique-bucket-name-12345

バケットがリストに表示されなくなるはずです。つまり、ACK で AWS リソースのライフサイクル全体を管理できていることになります。

ACK の使用を開始する方法の詳細については、「ACK の使用を開始する」を参照してください。

リソースのライフサイクルと調整

ACK は、継続的な調整ループを使用して、AWS リソースが Kubernetes マニフェストに定義された目的の状態と一致するようにします。

調整の仕組み:

ユーザーが Kubernetes カスタムリソース (S3 バケットなど) を作成または更新します。
ACK がその変更を検出し、目的の状態を AWS の実際の状態と比較します。
両者が異なる場合、ACK は AWS API コールを実行して差分を調整します。
ACK が現在の状態を反映するように Kubernetes のリソースステータスを更新します。
このループが通常数時間ごとに継続的に繰り返されます。

調整がトリガーされるのは、Kubernetes リソースを新規に作成したとき、既存のリソースの spec を更新したとき、または ACK 外での手動変更によって AWS でドリフトが発生したことを ACK が検出したときです。また、ACK は 10 時間という再同期期間で定期的に調整を行います。Kubernetes リソースを変更した場合は即時調整がトリガーされるのに対して、アップストリームの AWS リソースを変更した場合はパッシブなドリフト検出が定期的な再同期で行われます。

上記のように使用を開始すると、ACK は次のステップを実行します。

バケットが AWS に存在するかどうかを確認します。
存在しない場合は、s3:CreateBucket を呼び出します。
バケットの ARN と状態で Kubernetes ステータスを更新します。
ドリフトがないか継続的にモニタリングします。

ACK の仕組みの詳細については、「ACK 調整」を参照してください。

ステータス条件

ACK リソースは、ステータス条件を使用してリソースの状態を伝えます。ステータス条件を理解すると、問題のトラブルシューティングとリソース状態の把握に役立ちます。

Ready: リソースを消費する準備ができていることを示します (標準化された Kubernetes 条件)。
ACK.ResourceSynced: リソース仕様が AWS リソースの状態と一致することを示します。
ACK.Terminal: 回復不能なエラーが発生したことを示します。
ACK.Adopted: リソースが新規に作成されたのではなく既存の AWS リソースから採用されたことを示します。
ACK.Recoverable: 回復可能なエラーであるものの、仕様を更新することなく解決可能であることを示します。
ACK.Advisory: リソースのアドバイザリ情報を提供します。
ACK.LateInitialized: フィールドの遅延初期化が完了しているかどうかを示します。
ACK.ReferencesResolved: すべての AWSResourceReference フィールドが解決されたかどうかを示します。
ACK.IAMRoleSelected: このリソースを管理するために IAMRoleSelector が選択されたかどうかを示します。

リソースのステータスを確認する:


# Check if resource is ready
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'

# Check for terminal errors
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="ACK.Terminal")]}'

ステータスの例:


status:
  conditions:
  - type: Ready
    status: "True"
    lastTransitionTime: "2024-01-15T10:30:00Z"
  - type: ACK.ResourceSynced
    status: "True"
    lastTransitionTime: "2024-01-15T10:30:00Z"
  - type: ACK.Terminal
    status: "True"
  ackResourceMetadata:
    arn: arn:aws:s3:::my-unique-bucket-name
    ownerAccountID: "111122223333"
    region: us-west-2

ACK のステータスと条件の詳細については、「ACK の条件」を参照してください。

削除ポリシー

ACK の削除ポリシーは、Kubernetes AWS リソースを削除したときにリソースがどうなるかを制御します。

削除する (デフォルト)

Kubernetes リソースを削除すると、AWS リソースも削除されます。これがデフォルトの動作です。


# No annotation needed - this is the default
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: temp-bucket
spec:
  name: temporary-bucket

このリソースを削除すると、AWS の S3 バケットも削除されます。

Retain:

AWS リソースは、Kubernetes リソースを削除しても保持されます。


apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: important-bucket
  annotations:
    services.k8s.aws/deletion-policy: "retain"
spec:
  name: production-data-bucket

このリソースを削除すると、Kubernetes から削除されますが、S3 バケットは AWS に残ります。

本番稼働用データベースでは、Kubernetes リソース、複数のアプリケーションで使用される共有リソース、誤って削除されてはならない重要なデータがあるリソースを長く維持する必要があります。また、リソースを採用して設定した後、手動管理に戻すという一時的な ACK 管理も必要です。retain ポリシーは、こうした用途に有益です。

ACK 削除ポリシーの詳細については、「ACK 削除ポリシー」を参照してください。

リソースの採用

リソースを採用すると、既存の AWS リソースを再作成することなく ACK の管理下に置くことができます。

どのような場合に採用するか:

既存のインフラストラクチャを ACK 管理に移行する場合
Kubernetes で AWS リソースを誤って削除したときに孤立したリソースを復旧する場合
他のツール (CloudFormation や Terraform) で作成されたリソースをインポートする場合

採用の仕組み:


apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: existing-bucket
  annotations:
    services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
  name: my-existing-bucket-name

このリソースを作成すると、次のようになります。

ACK が、その名前のバケットが AWS に存在するかどうかを確認します。
存在すれば、ACK はそのバケットを採用します (API コールは作成されません)。
ACK が AWS から現在の設定を読み取ります。
ACK が実際の状態を反映するように Kubernetes ステータスを更新します。
今後の更新でリソースを正常に調整します。

採用されたら、リソースは他の ACK リソースと同様に管理され、retain 削除ポリシーを使用しない限り、Kubernetes リソースを削除すると、AWS リソースも削除されます。

リソースを採用するときに、AWS リソースは既に存在している必要があり、それを検出するためには ACK に読み取りアクセス許可が必要です。adopt-or-create ポリシーは、リソースが存在すれば採用し、存在しなければ作成します。これは、リソースが存在するかどうかにかかわらず宣言型ワークフローを機能させるときに便利です。

ACK リソースの採用の詳細については、「ACK リソースの採用」を参照してください。

クロスアカウントおよびクロスリージョンのリソース

ACK は、1 つのクラスターからさまざまな AWS アカウントとリージョンのリソースを管理できます。

クロスリージョンリソースの注釈

注釈を使用すると、AWS リソースのリージョンを指定できます。


apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: eu-bucket
  annotations:
    services.k8s.aws/region: eu-west-1
spec:
  name: my-eu-bucket

特定の名前空間に作成されたすべての AWS リソースのリージョンを指定することもできます。

名前空間の注釈

名前空間内のすべてのリソースに対してデフォルトのリージョンを設定します。


apiVersion: v1
kind: Namespace
metadata:
  name: production
  annotations:
    services.k8s.aws/default-region: us-west-2

この名前空間に作成されたリソースは、リソースレベルの注釈で上書きされない限り、このリージョンを使用します。

クロスアカウント

IAM ロールセレクターを使用すると、特定の IAM ロールを名前空間にマッピングできます。


apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
  name: target-account-config
spec:
  arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
  namespaceSelector:
    names:
      - production

マッピングされた名前空間に作成されたリソースは、指定されたロールを自動的に使用します。

IAM ロールセレクターの詳細については、「ACK クロスアカウントリソース管理」を参照してください。クロスアカウント設定の詳細については、「ACK アクセス許可を設定する」を参照してください。

エラー処理と再試行動作

ACK は、一時的なエラーを自動的に処理し、失敗したオペレーションを再試行します。

再試行戦略:

一時的なエラー (レート制限、サービスの一時的な問題、不十分なアクセス許可) が発生したら、自動再試行をトリガーします。
エクスポネンシャルバックオフにより、AWS API が過剰になるのを防ぎます。
エラータイプに応じて最大再試行回数を変えます。
永続的なエラー (無効なパラメータ、リソース名の競合) は再試行されません。

kubectl describe を使用して、エラーの詳しい情報がないかリソースのステータスを確認します。


kubectl describe bucket my-bucket

エラーメッセージでステータス条件を確認し、最近調整を試みたことを示すイベントがないかチェックし、ステータス条件の message フィールドで障害に関する説明を参照します。よくあるエラーには、IAM アクセス許可が十分でない、AWS でリソース名が競合している、spec に無効な設定値がある、AWS サービスクォータが超過しているといったことがあります。

よくあるエラーのトラブルシューティングについては、「ACK 機能に関する問題をトラブルシューティングする」を参照してください。

kro によるリソース構成

複数の ACK リソースをまとめて作成および接続するには、EKS Capability for kro (Kube Resource Orchestrator) を使用します。kro を使用すると、リソースのグループを宣言的に定義し、リソース間で設定を渡して、複雑なインフラストラクチャパターンを容易に管理できます。

ACK リソースでカスタムリソース構成を作成する詳細な例については、「kro の概念」を参照してください。

次のステップ

EKS を利用する場合の ACK の考慮事項 - EKS に固有のパターンと統合戦略

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

eksctl

アクセス許可の設定