**このページの改善にご協力ください**
このユーザーガイドに貢献するには、すべてのページの右側のペインにある「**GitHub でこのページを編集する**」リンクを選択してください。
# Kubernetes 用 AWS コントローラー (ACK) で Kubernetes から AWS リソースをデプロイする
Kubernetes 用 AWS コントローラー (ACK) を使用すると、Kubernetes から直接 AWS サービスリソースを定義および管理できます。Kubernetes 用 AWS コントローラー (ACK) により、Kubernetes カスタムリソースを使用してワークロードリソースとクラウドインフラストラクチャを管理できるほか、使い慣れた Kubernetes API とツールを使用してアプリケーションワークロードも管理できます。
AWS では EKS の機能を使用して ACK を完全に管理できるため、クラスターに ACK コントローラーをインストールして保守およびスケールする必要がありません。
## ACK の仕組み
ACK は、Kubernetes カスタムリソース仕様を AWS API コールに変換します。AWS サービスリソースを表す Kubernetes カスタムリソースを作成、更新、または削除すると、ACK は AWS リソースを作成、更新、または削除するために必要な AWS API コールを実行します。
ACK でサポートされている AWS リソースごとに独自のカスタムリソース定義 (CRD) を用意して、そのリソース設定を指定するための Kubernetes API スキーマを定義します。例えば、S3 の CRD にバケットやバケットポリシーなどの S3 リソースを含めることができます。
ACK は、Kubernetes カスタムリソースに定義された目的の状態に合わせて AWS リソースの状態を継続的に調整します。リソースが目的の状態からドリフトした場合、ACK はそれを検出し、是正アクションを実行して調整し直します。Kubernetes リソースへの変更は、すぐに AWS リソースの状態に反映されます。一方、アップストリームの AWS リソースに対する変更の場合、ドリフトをパッシブに検出して修復するには 10 時間もかかることがありますが (再同期期間)、通常ははるかに早く終了します。
**S3 バケットリソースマニフェストの例**
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-ack-bucket
spec:
name: my-unique-bucket-name
```
このカスタムリソースをクラスターに適用すると、アカウントに Amazon S3 バケットがまだ存在しない場合には ACK によって作成されます。以後、このリソースに変更を加えた場合、例えばデフォルト以外のストレージ階層を指定したりポリシーを追加したりすると、その変更が AWS 内の S3 リソースに適用されます。このリソースがクラスターから削除されると、デフォルトでは AWS 内の S3 バケットも削除されます。
## ACK のメリット
ACK では Kubernetes ネイティブの AWS リソース管理を利用できるため、普段アプリケーションで使用しているのと同じ Kubernetes API とツールで AWS リソースを管理できます。このように統合が図られているため、さまざまなツールを切り替えたり、Infrastructure as Code 管理ワークフローを個別に習得したりする必要がありません。Kubernetes マニフェストで AWS リソースを宣言的に定義して、GitOps ワークフローとインフラストラクチャを、既存の開発プロセスとシームレスに統合するコードプラクティスとして有効にします。
ACK は、AWS リソースの目的の状態を実際の状態で継続的に調整し、ドリフトを修正して、インフラストラクチャ全体の一貫性を確保します。このように継続的に調整することで、AWS リソースに必須の帯域外変更が、宣言した設定に合わせて自動的に元に戻されるため、Infrastructure as Code の整合性が維持されます。複数の AWS アカウントとリージョンにわたるリソースを管理するように ACK を設定することで、他にツールを追加することなく、複雑なマルチアカウントアーキテクチャを実現できます。
組織全体で他のインフラストラクチャ管理ツールから移行するできるように、ACK がリソースの採用をサポートしているため、再作成することなく既存の AWS リソースを ACK の管理下に置くことができます。ACK ではこのほか、読み取り専用リソースにより、変更アクセス権がなくても AWS リソースを監視でき、注釈により、Kubernetes リソースがクラスターから削除された場合でもオプションで AWS リソースを保持できます。
EKS Capability for ACK の詳細と使用開始については、「[ACK の概念](ack-concepts.md)」および「[EKS を利用する場合の ACK の考慮事項](ack-considerations.md)」を参照してください。
## サポートされる AWS サービス
ACK は、次のような幅広い AWS サービスをサポートしています。
+ Amazon EC2
+ Amazon S3
+ Amazon RDS
+ Amazon DynamoDB
+ Amazon ElastiCache
+ Amazon EKS
+ Amazon SQS
+ Amazon SNS
+ AWS Lambda
+ AWS IAM
一般提供アップストリームとしてリストされているすべての AWS サービスが、EKS Capability for ACK でサポートされています。詳細については、[サポートされている AWS サービスの完全なリスト](https://aws-controllers-k8s.github.io/community/docs/community/services/)を参照してください。
## 他の EKS マネージド機能との統合
ACK は、他の EKS マネージド機能と統合されています。
+ **Argo CD**: Argo CD を使用すると、複数のクラスターにまたがる ACK リソースのデプロイを管理して、AWS インフラストラクチャの GitOps ワークフローを有効にできます。
+ ACK を ArgoCD と組み合わせると GitOps のメリットが広がりますが、ACK を git と統合する必要はありません。
+ **kro (Kube Resource Orchestrator)**: kro を使用すると、ACK リソースから複雑なリソースを作成して、高次の抽象化を作成してリソース管理をシンプルにできます。
+ kro で Kubernetes リソースと AWS リソースの両方を定義することで、複合カスタムリソースを作成できます。チームメンバーは、こうしたカスタムリソースを使用して、複雑なアプリケーションをすばやくデプロイできます。
## ACK の使用を開始する
EKS Capability for ACK の使用を開始するには:
1. 自分の代わりに ACK で AWS リソースを管理できるように、IAM 機能ロールを作成して、必要なアクセス許可を設定します。
1. AWS コンソール、AWS CLI、または任意の Infrastructure as Code ツールを使用して、EKS クラスターに [ACK 機能リソースを作成](create-ack-capability.md)します。
1. Kubernetes カスタムリソースをクラスターに適用して、Kubernetes での AWS リソースの管理を開始します。
# ACK 機能を作成する
この章では、Amazon EKS クラスターに ACK 機能を作成する方法について説明します。
## 前提条件
ACK 機能を作成する前に、以下の点を確認してください。
+ Amazon EKS クラスター
+ ACK で AWS リソースを管理するためのアクセス許可が IAM 機能ロールに付与されている
+ EKS クラスターに機能リソースを作成するための十分な IAM アクセス許可がある
+ 適切な CLI ツールがインストールおよび設定されているか、EKS コンソールにアクセスできる
IAM 機能ロールを作成する手順については、「[Amazon EKS 機能 IAM ロール](capability-role.md)」を参照してください。
**重要**
ACK は、AWS リソースを作成、変更、削除する権限を付与するインフラストラクチャ管理機能です。これは、制御に慎重を要する管理者範囲の機能です。クラスターに Kubernetes リソースを作成するためのアクセス許可があれば誰でも、IAM 機能ロールのアクセス許可に従って、ACK で AWS リソースを効果的に作成できます。ACK でどの AWS リソースを作成および管理できるかは、どの IAM 機能ロールを使用するかによって決まります。最小特権のアクセス許可を付与した適切なロールを作成する際のガイダンスについては、「[Amazon EKS 機能 IAM ロール](capability-role.md)」および「[EKS 機能のセキュリティに関する考慮事項](capabilities-security.md)」を参照してください。
## ツールを選択する
AWS マネジメントコンソール、AWS CLI、または eksctl を使用して、ACK 機能を作成できます。
+ [コンソールを使用して ACK 機能を作成する](ack-create-console.md) - 指示に従って操作する場合はコンソールを使用します。
+ [AWS CLI を使用して ACK 機能を作成する](ack-create-cli.md) - スクリプトを作成して自動化を図る場合は AWS CLI を使用します。
+ [eksctl を使用して ACK 機能を作成する](ack-create-eksctl.md) - Kubernetes ネイティブの操作をする場合は eksctl を使用します。
## ACK 機能を作成するとどうなるか
ACK 機能を作成すると、次のようになります。
1. EKS が、ACK 機能サービスを作成して、クラスター内のリソースをモニタリングおよび管理するように設定します。
1. カスタムリソース定義 (CRD) がクラスターにインストールされます。
1. Kubernetes のベースラインアクセス許可を付与する機能固有のアクセスエントリポリシーを使用して、IAM 機能ロールのアクセスエントリを自動的に作成します (「[EKS 機能のセキュリティに関する考慮事項](capabilities-security.md)」を参照)。
1. 機能が、指定した IAM 機能ロールを引き受けます。
1. ACK が、クラスター内のカスタムリソースを監視し始めます。
1. 機能のステータスが `CREATING` から `ACTIVE` に変わります。
アクティブになったら、AWS リソースを管理するための ACK カスタムリソースをクラスターに作成できます。
**注記**
自動的に作成されたアクセスエントリには、AWS リソースを管理するための ACK アクセス許可を付与する `AmazonEKSACKPolicy` が含まれます。Kubernetes シークレットを参照する一部の ACK リソース (パスワード付きの RDS データベースなど) には、追加のアクセスエントリポリシーが必要です。アクセスエントリの詳細と追加のアクセス許可の設定方法については、「[EKS 機能のセキュリティに関する考慮事項](capabilities-security.md)」を参照してください。
## 次のステップ
ACK 機能の作成後:
+ [ACK の概念](ack-concepts.md) - ACK の概念を理解し、AWS リソースの使用を開始する
+ [ACK の概念](ack-concepts.md) - 調整、フィールドエクスポート、リソース採用パターンについて学ぶ
+ [ACK アクセス許可を設定する](ack-permissions.md) - IAM アクセス許可およびマルチアカウントパターンを設定する
# コンソールを使用して ACK 機能を作成する
このトピックでは、AWS マネジメントコンソール を使用して Kubernetes 用 AWS コントローラー (ACK) 機能を作成する方法について説明します。
## ACK 機能を作成する
1. https://console.aws.amazon.com/eks/home\$1/clusters で Amazon EKS コンソールを開きます。
1. クラスター名を選択して、クラスターの詳細ページを開きます。
1. **[機能]** タブを選択します。
1. 左側のナビゲーションで、**[Kubernetes 用 AWS コントローラー (ACK)]** を選択します。
1. **[Kubernetes 用 AWS コントローラー (ACK) 機能]** を選択します。
1. **IAM 機能ロール**に対して以下の操作を行います。
+ IAM 機能ロールが既に存在する場合は、ドロップダウンから選択します。
+ ロールを作成する必要がある場合は、**[管理者ロールを作成]** を選択します。
IAM コンソールが新しいタブに開かれます。信頼ポリシーと `AdministratorAccess` 管理ポリシーには、値があらかじめ入力されています。このポリシーを選択解除し、必要に応じて他のアクセス許可を追加できます。
ロールを作成して EKS コンソールに戻ると、そのロールが自動的に選択されます。
**重要**
提案された `AdministratorAccess` ポリシーは、幅広いアクセス許可を付与し、使用開始を効率化することを目的としています。本番稼働で使用する場合は、これをカスタムポリシーに置き換えて、そのポリシーでは ACK で管理する特定の AWS サービスに必要なアクセス許可のみを付与します。最小特権ポリシーを作成する際のガイダンスについては、「[ACK アクセス許可を設定する](ack-permissions.md)」および「[EKS 機能のセキュリティに関する考慮事項](capabilities-security.md)」を参照してください。
1. **[作成]** を選択します。
機能作成プロセスが始まります。
## 機能がアクティブであることを確認する
1. **[機能]** タブで、ACK 機能のステータスを表示します。
1. ステータスが `CREATING` から `ACTIVE` に変わるまで待ちます。
1. アクティブになったら、この機能を使用する準備は完了です。
機能のステータスとトラブルシューティングの詳細については、「[機能リソースの使用](working-with-capabilities.md)」を参照してください。
## カスタムリソースが使用可能であることを確認する
機能がアクティブになったら、ACK カスタムリソースがクラスターで使用可能になっていることを確認します。
**コンソールの使用**
1. Amazon EKS コントロールでクラスターに移動します。
1. **[リソース]** タブを選択します。
1. **[拡張機能]** を選択します。
1. **[CustomResourceDefinitions]** を選択します。
AWS リソースに使用可能な多数の CRD がリストされます。
**kubectl を使用する**
```
kubectl api-resources | grep services.k8s.aws
```
AWS リソースに使用可能な多数の API がリストされます。
**注記**
Kubernetes 用 AWS コントローラーの機能は、さまざまな AWS リソース用に多数の CRD をインストールします。
## 次のステップ
+ [ACK の概念](ack-concepts.md) - ACK の概念を理解して使用を開始する
+ [ACK アクセス許可を設定する](ack-permissions.md) - 他の AWS サービスに対して IAM アクセス許可を設定する
+ [機能リソースの使用](working-with-capabilities.md) - ACK 機能リソースを管理する
# AWS CLI を使用して ACK 機能を作成する
このトピックでは、AWS CLI を使用して Kubernetes 用 AWS コントローラー (ACK) 機能を作成する方法について説明します。
## 前提条件
+ **AWS CLI** バージョン `2.12.3` 以降。バージョンを確認するには、`aws --version` を実行します。詳細についてはAWS コマンドラインインターフェイスユーザーガイドの「[インストール](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)」を参照してください。
+ **`kubectl`** - Kubernetes クラスターを操作するためのコマンドラインツール。詳細については、「[`kubectl` および `eksctl` のセットアップ](install-kubectl.md)」を参照してください。
## ステップ 1: IAM 機能ロールを作成する
信頼ポリシーファイルを作成します。
```
cat > ack-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
IAM ロールを作成します。
```
aws iam create-role \
--role-name ACKCapabilityRole \
--assume-role-policy-document file://ack-trust-policy.json
```
`AdministratorAccess` マネージドポリシーをロールにアタッチします。
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**重要**
提案された `AdministratorAccess` ポリシーは、幅広いアクセス許可を付与し、使用開始を効率化することを目的としています。本番稼働で使用する場合は、これをカスタムポリシーに置き換えて、そのポリシーでは ACK で管理する特定の AWS サービスに必要なアクセス許可のみを付与します。最小特権ポリシーを作成する際のガイダンスについては、「[ACK アクセス許可を設定する](ack-permissions.md)」および「[EKS 機能のセキュリティに関する考慮事項](capabilities-security.md)」を参照してください。
## ステップ 2: ACK 機能を作成する
ACK 機能リソースをクラスターに作成します。*region-code* はクラスターがある AWS リージョンに、*my-cluster* はクラスターの名前に置き換えます。
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack \
--type ACK \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ACKCapabilityRole \
--delete-propagation-policy RETAIN
```
このコマンドはすぐに戻りますが、EKS が必要な機能インフラストラクチャとコンポーネントを作成するため、機能がアクティブになるまでにはしばらく時間がかかります。EKS は、この機能に関連する Kubernetes カスタムリソース定義をその作成時にクラスターにインストールします。
**注記**
クラスターが存在しないというエラーやアクセス許可がないというエラーが表示された場合は、以下の点を確認します。
クラスター名が正しいこと
AWS CLI が正しいリージョンに設定されていること
必要な IAM アクセス許可を追加したこと
## ステップ 3: 機能がアクティブであることを確認する
機能がアクティブになるまで待機します。*region-code* はクラスターがある AWS リージョンに、*my-cluster* はクラスターの名前に置き換えます。
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack \
--query 'capability.status' \
--output text
```
ステータスが `ACTIVE` と表示されたら、機能の準備は完了です。ステータスが `ACTIVE` になるまで、次のステップに進まないでください。
機能の詳細全体を表示することもできます。
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack
```
## ステップ 4: カスタムリソースが使用可能であることを確認する
機能がアクティブになったら、ACK カスタムリソースがクラスターで使用可能になっていることを確認します。
```
kubectl api-resources | grep services.k8s.aws
```
AWS リソースに使用可能な多数の API がリストされます。
**注記**
Kubernetes 用 AWS コントローラーの機能は、さまざまな AWS リソース用に多数の CRD をインストールします。
## 次のステップ
+ [ACK の概念](ack-concepts.md) - ACK の概念を理解して使用を開始する
+ [ACK アクセス許可を設定する](ack-permissions.md) - 他の AWS サービスに対して IAM アクセス許可を設定する
+ [機能リソースの使用](working-with-capabilities.md) - ACK 機能リソースを管理する
# eksctl を使用して ACK 機能を作成する
このトピックでは、eksctl を使用して Kubernetes 用 AWS コントローラー (ACK) 機能を作成する方法について説明します。
**注記**
以下のステップを実行するには、eksctl バージョン `0.220.0` 以降が必要です。バージョンを確認するには、`eksctl version` を実行します。
## ステップ 1: IAM 機能ロールを作成する
信頼ポリシーファイルを作成します。
```
cat > ack-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
IAM ロールを作成します。
```
aws iam create-role \
--role-name ACKCapabilityRole \
--assume-role-policy-document file://ack-trust-policy.json
```
`AdministratorAccess` マネージドポリシーをロールにアタッチします。
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**重要**
提案された `AdministratorAccess` ポリシーは、幅広いアクセス許可を付与し、使用開始を効率化することを目的としています。本番稼働で使用する場合は、これをカスタムポリシーに置き換えて、そのポリシーでは ACK で管理する特定の AWS サービスに必要なアクセス許可のみを付与します。最小特権ポリシーを作成する際のガイダンスについては、「[ACK アクセス許可を設定する](ack-permissions.md)」および「[EKS 機能のセキュリティに関する考慮事項](capabilities-security.md)」を参照してください。
**重要**
このポリシーは、`"Resource": "*"` で S3 バケット管理に必要なアクセス許可を付与して、すべての S3 バケットに対してオペレーションを実行できるようにします。
本番稼働で使用する場合: \$1 `Resource` フィールドを特定のバケット ARN または名前パターンに制限します。\$1 IAM 条件キーを使用すると、リソースタグでアクセスを制限できます。\$1 ユースケースに必要な最小限のアクセス許可のみを付与します。
その他の AWS サービスについては、「[ACK アクセス許可を設定する](ack-permissions.md)」を参照してください。
ロールにポリシーを付与します。
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/ACKS3Policy
```
## ステップ 2: ACK 機能を作成する
eksctl を使用して ACK 機能を作成します。*region-code* はクラスターがある AWS リージョンに、*my-cluster* はクラスターの名前に置き換えます。
```
eksctl create capability \
--cluster [.replaceable]`my-cluster` \
--region [.replaceable]`region-code` \
--name ack \
--type ACK \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ACKCapabilityRole \
--ack-service-controllers s3
```
**注記**
`--ack-service-controllers` フラグはオプションです。省略した場合、ACK は使用可能なすべてのコントローラーを有効にします。パフォーマンスとセキュリティを高めるため、必要なコントローラーのみを有効にすることを検討してください。`--ack-service-controllers s3,rds,dynamodb` のように、複数のコントローラーを指定できます。
このコマンドはすぐに戻りますが、機能がアクティブになるまでにはしばらく時間がかかります。
## ステップ 3: 機能がアクティブであることを確認する
機能のステータスを確認します。
```
eksctl get capability \
--cluster [.replaceable]`my-cluster` \
--region [.replaceable]`region-code` \
--name ack
```
ステータスが `ACTIVE` と表示されたら、機能の準備は完了です。
## ステップ 4: カスタムリソースが使用可能であることを確認する
機能がアクティブになったら、ACK カスタムリソースがクラスターで使用可能になっていることを確認します。
```
kubectl api-resources | grep services.k8s.aws
```
AWS リソースに使用可能な多数の API がリストされます。
**注記**
Kubernetes 用 AWS コントローラーの機能は、さまざまな AWS リソース用に多数の CRD をインストールします。
## 次のステップ
+ [ACK の概念](ack-concepts.md) - ACK の概念を理解して使用を開始する
+ [ACK アクセス許可を設定する](ack-permissions.md) - 他の AWS サービスに対して IAM アクセス許可を設定する
+ [機能リソースの使用](working-with-capabilities.md) - ACK 機能リソースを管理する
# ACK の概念
ACK は、AWS の実際の状態に照らしてマニフェストの目的の状態を継続的に調整することで、Kubernetes API を利用して AWS リソースを管理します。Kubernetes カスタムリソースを作成または更新すると、ACK は対応する AWS リソースを作成または変更するために必要な AWS API コールを実行し、ドリフトがないかモニタリングして、現在の状態を反映するように Kubernetes ステータスを更新します。このアプローチにより、クラスターと AWS との一貫性を維持しながら、使い慣れた Kubernetes ツールとワークフローを使用してインフラストラクチャを管理できます。
このトピックでは、ACK が Kubernetes API を利用して AWS リソースを管理する際の土台となる概念について説明します。
## ACK の使用を開始する
ACK 機能を作成したら (「[ACK 機能を作成する](create-ack-capability.md)」を参照)、クラスターで 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 の使用を開始する](https://aws-controllers-k8s.github.io/community/docs/user-docs/getting-started/)」を参照してください。
## リソースのライフサイクルと調整
ACK は、継続的な調整ループを使用して、AWS リソースが Kubernetes マニフェストに定義された目的の状態と一致するようにします。
**調整の仕組み**:
1. ユーザーが Kubernetes カスタムリソース (S3 バケットなど) を作成または更新します。
1. ACK がその変更を検出し、目的の状態を AWS の実際の状態と比較します。
1. 両者が異なる場合、ACK は AWS API コールを実行して差分を調整します。
1. ACK が現在の状態を反映するように Kubernetes のリソースステータスを更新します。
1. このループが通常数時間ごとに継続的に繰り返されます。
調整がトリガーされるのは、Kubernetes リソースを新規に作成したとき、既存のリソースの `spec` を更新したとき、または ACK 外での手動変更によって AWS でドリフトが発生したことを ACK が検出したときです。また、ACK は 10 時間という再同期期間で定期的に調整を行います。Kubernetes リソースを変更した場合は即時調整がトリガーされるのに対して、アップストリームの AWS リソースを変更した場合はパッシブなドリフト検出が定期的な再同期で行われます。
上記のように使用を開始すると、ACK は次のステップを実行します。
1. バケットが AWS に存在するかどうかを確認します。
1. 存在しない場合は、`s3:CreateBucket` を呼び出します。
1. バケットの ARN と状態で Kubernetes ステータスを更新します。
1. ドリフトがないか継続的にモニタリングします。
ACK の仕組みの詳細については、「[ACK 調整](https://aws-controllers-k8s.github.io/community/docs/user-docs/reconciliation/)」を参照してください。
## ステータス条件
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 の条件](https://aws-controllers-k8s.github.io/community/docs/user-docs/conditions/)」を参照してください。
## 削除ポリシー
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 削除ポリシー](https://aws-controllers-k8s.github.io/community/docs/user-docs/deletion-policy/)」を参照してください。
## リソースの採用
リソースを採用すると、既存の 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
```
このリソースを作成すると、次のようになります。
1. ACK が、その名前のバケットが AWS に存在するかどうかを確認します。
1. 存在すれば、ACK はそのバケットを採用します (API コールは作成されません)。
1. ACK が AWS から現在の設定を読み取ります。
1. ACK が実際の状態を反映するように Kubernetes ステータスを更新します。
1. 今後の更新でリソースを正常に調整します。
採用されたら、リソースは他の ACK リソースと同様に管理され、`retain` 削除ポリシーを使用しない限り、Kubernetes リソースを削除すると、AWS リソースも削除されます。
リソースを採用するときに、AWS リソースは既に存在している必要があり、それを検出するためには ACK に読み取りアクセス許可が必要です。`adopt-or-create` ポリシーは、リソースが存在すれば採用し、存在しなければ作成します。これは、リソースが存在するかどうかにかかわらず宣言型ワークフローを機能させるときに便利です。
ACK リソースの採用の詳細については、「[ACK リソースの採用](https://aws-controllers-k8s.github.io/community/docs/user-docs/adopted-resource/)」を参照してください。
## クロスアカウントおよびクロスリージョンのリソース
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 クロスアカウントリソース管理](https://aws-controllers-k8s.github.io/docs/guides/cross-account)」を参照してください。クロスアカウント設定の詳細については、「[ACK アクセス許可を設定する](ack-permissions.md)」を参照してください。
## エラー処理と再試行動作
ACK は、一時的なエラーを自動的に処理し、失敗したオペレーションを再試行します。
再試行戦略:
+ 一時的なエラー (レート制限、サービスの一時的な問題、不十分なアクセス許可) が発生したら、自動再試行をトリガーします。
+ エクスポネンシャルバックオフにより、AWS API が過剰になるのを防ぎます。
+ エラータイプに応じて最大再試行回数を変えます。
+ 永続的なエラー (無効なパラメータ、リソース名の競合) は再試行されません。
`kubectl describe` を使用して、エラーの詳しい情報がないかリソースのステータスを確認します。
```
kubectl describe bucket my-bucket
```
エラーメッセージでステータス条件を確認し、最近調整を試みたことを示すイベントがないかチェックし、ステータス条件の `message` フィールドで障害に関する説明を参照します。よくあるエラーには、IAM アクセス許可が十分でない、AWS でリソース名が競合している、`spec` に無効な設定値がある、AWS サービスクォータが超過しているといったことがあります。
よくあるエラーのトラブルシューティングについては、「[ACK 機能に関する問題をトラブルシューティングする](ack-troubleshooting.md)」を参照してください。
## kro によるリソース構成
複数の ACK リソースをまとめて作成および接続するには、EKS Capability for kro (Kube Resource Orchestrator) を使用します。kro を使用すると、リソースのグループを宣言的に定義し、リソース間で設定を渡して、複雑なインフラストラクチャパターンを容易に管理できます。
ACK リソースでカスタムリソース構成を作成する詳細な例については、「[kro の概念](kro-concepts.md)」を参照してください。
## 次のステップ
+ [EKS を利用する場合の ACK の考慮事項](ack-considerations.md) - EKS に固有のパターンと統合戦略
# ACK アクセス許可を設定する
自分の代わりに ACK で AWS リソースを作成および管理できるようにするには、IAM アクセス許可が必要です。このトピックでは、IAM が ACK でどのように機能するかを説明し、さまざまなユースケースに合わせてアクセス許可を設定する際のガイダンスを示します。
## IAM は ACK でどのように機能するか
ACK は、IAM ロールを使用して AWS で認証し、リソースに対してアクションを実行します。ACK にアクセス許可を付与する方法が 2 つあります。
**機能ロール**: ACK 機能の作成時に指定する IAM ロールです。このロールは、デフォルトではすべての ACK オペレーションに使用されます。
**IAM ロールセレクター**: 特定の名前空間またはリソースにマッピングできる追加の IAM ロールです。これらのロールの範囲内にあるリソースの機能ロールは上書きされます。
リソースを作成または管理する必要があるときに、ACK はどの IAM ロールを使用するかを決定します。
1. IAMRoleSelector がリソースの名前空間に一致するかどうかを確認します。
1. 一致した場合、その IAM ロールを引き受けます。
1. 一致しない場合、機能ロールを使用します。
このアプローチにより、シンプルな単一ロールセットアップから複雑なマルチアカウントかつマルチチームの設定まで、アクセス許可を柔軟に管理できます。
## 使用開始: シンプルなアクセス許可セットアップ
開発、テスト、またはシンプルなユースケースの場合、必要なすべてのサービスアクセス許可を機能ロールに直接追加できます。
このアプローチは、次の場合に適しています。
+ ACK の使用を開始している
+ すべてのリソースが同じ AWS アカウントにある
+ 1 つのチームがすべての ACK リソースを管理する
+ すべての ACK ユーザーに同じアクセス許可が付与されていると確信している
## 本番稼働でのベストプラクティス: IAM ロールセレクター
本番稼働環境では、IAM ロールセレクターを使用して、最小特権のアクセスと名前空間レベルでの分離を実装します。
IAM ロールセレクターを使用する場合、機能ロールに必要なアクセス許可はサービス固有のロールを引き受けるための `sts:AssumeRole` および `sts:TagSession` アクセス許可だけです。機能ロール自体に AWS サービスアクセス許可 (S3 や RDS など) を追加する必要はありません。そうしたアクセス許可は、機能ロールが引き受ける個々の IAM ロールに付与します。
**アクセス許可モデルを選択する**:
次の場合は、**直接アクセス許可** (機能ロールにサービスアクセス許可を追加すること) を使用します。
+ 使用を開始し、最もシンプルなセットアップにする場合
+ すべてのリソースがクラスターと同じアカウントにある場合
+ クラスター全体の管理アクセス許可を必要とする場合
+ すべてのチームが同じアクセス許可を共有できる場合
次の場合は、**IAM ロールセレクター**を使用します。
+ 複数の AWS アカウント全体のリソースを管理する場合
+ チームや名前空間ごとに異なるアクセス許可が必要な場合
+ 名前空間ごとにきめ細かなアクセスコントロールが必要な場合
+ 最小特権のセキュリティプラクティスに従う場合
直接アクセス許可から開始し、その後、要件の増大に応じて IAM ロールセレクターに移行できます。
**なぜ本番稼働で IAM ロールセレクターを使用するのか:**
+ **最小特権**: 名前空間ごとに必要なアクセス許可のみを取得します。
+ **チーム分離**: チーム A が誤ってチーム B のアクセス許可を使用することがないようにします。
+ **容易な監査**: どの名前空間がどのロールを使用するかを明確にマッピングします。
+ **クロスアカウントサポート**: 複数のアカウントのリソースを管理する場合に必要です。
+ **関心の分離**: サービスや環境ごとに異なるロールを使用します。
### 基本的な IAM ロールセレクターのセットアップ
**ステップ 1: サービス固有の IAM ロールを作成する**
特定の AWS サービスに対するアクセス許可を付与した IAM ロールを作成します。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": "*"
}
]
}
```
機能ロールに引き受けられるように信頼ポリシーを設定します。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole"
},
"Action": ["sts:AssumeRole", "sts:TagSession"]
}
]
}
```
**ステップ 2: AssumeRole アクセス許可を機能ロールに付与する**
サービス固有のロールを引き受けるためのアクセス許可を機能ロールに追加します。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::111122223333:role/ACK-S3-Role"
}
]
}
```
**ステップ 3: IAMRoleSelector を作成する**
名前空間に IAM ロールをマッピングします。
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: s3-namespace-config
spec:
arn: arn:aws:iam::111122223333:role/ACK-S3-Role
namespaceSelector:
names:
- s3-resources
```
**ステップ 4: マッピングした名前空間にリソースを作成する**
`s3-resources` 名前空間内のリソースは、指定されたロールを自動的に使用します。
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-bucket
namespace: s3-resources
spec:
name: my-production-bucket
```
## マルチアカウント管理
IAM ロールセレクターを使用すると、複数の AWS アカウントのリソースを管理できます。
**ステップ 1: クロスアカウント IAM ロールを作成する**
ターゲットアカウント (444455556666) に、ソースアカウントの機能ロールを信頼するロールを作成します。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole"
},
"Action": ["sts:AssumeRole", "sts:TagSession"]
}
]
}
```
このロールにサービス固有のアクセス許可をアタッチします。
**ステップ 2: AssumeRole アクセス許可を付与する**
ソースアカウント (111122223333) で、機能ロールがターゲットアカウントロールを引き受けられるようにします。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::444455556666:role/ACKTargetAccountRole"
}
]
}
```
**ステップ 3: IAMRoleSelector を作成する**
名前空間にクロスアカウントロールをマッピングします。
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: production-account-config
spec:
arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
namespaceSelector:
names:
- production
```
**ステップ 4: リソースを作成する**
`production` 名前空間内のリソースは、ターゲットアカウントに作成します。
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-bucket
namespace: production
spec:
name: my-cross-account-bucket
```
## セッションタグ
EKS ACK 機能は、すべての AWS API リクエストにセッションタグを自動的に設定します。これらのタグは、各リクエストのソースを特定することで、きめ細かなアクセスコントロールと監査を可能にします。
### 利用可能なセッションタグ
ACK によって行われるすべての AWS API コールには、次のセッションタグが含まれています。
| タグキー | 説明 |
| --- | --- |
| `eks:eks-capability-arn` | リクエストを行う EKS 機能の ARN |
| `eks:kubernetes-namespace` | 管理対象のリソースの Kubernetes 名前空間 |
| `eks:kubernetes-api-group` | リソースの Kubernetes API グループ (例: `s3.services.k8s.aws`) |
### セッションタグを使用したアクセス制御
これらのセッションタグを IAM ポリシー条件で使用して、ACK が管理できるリソースを制限できます。これにより、名前空間ベースの IAM ロールセレクターに加えて追加セキュリティレイヤーが設定されます。
**例: 名前空間による制限**
リクエストが `production` 名前空間から発信された場合にのみ、ACK が S3 バケットを作成できるようにします。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:CreateBucket",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks:kubernetes-namespace": "production"
}
}
}
]
}
```
**例: 機能による制限**
特定の ACK 機能からのアクションのみを許可します。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks:eks-capability-arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack"
}
}
}
]
}
```
**注記**
セッションタグは、デフォルトでこれらのタグを設定しないセルフマネージド ACK とは異なります。これにより、マネージド機能によるより詳細なアクセスコントロールが可能になります。
## 高度な IAM ロールセレクターパターン
ラベルセレクターやリソース固有のロールマッピングなどの例に見られる高度な設定については、「[ACK IRSA ドキュメント](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/)」を参照してください。
## 次のステップ
+ [ACK の概念](ack-concepts.md) - ACK の概念およびリソースライフサイクルを理解する
+ [ACK の概念](ack-concepts.md) - リソースの採用と削除ポリシーについて学ぶ
+ [EKS 機能のセキュリティに関する考慮事項](capabilities-security.md) - 機能のセキュリティベストプラクティスを理解する
# EKS を利用する場合の ACK の考慮事項
このトピックでは、IAM 設定、マルチアカウントパターン、他の EKS 機能との統合など、EKS Capability for ACK を使用する際の重要な考慮事項について説明します。
## IAM 設定のパターン
ACK 機能は、IAM 機能ロールを使用して AWS で認証します。要件に基づいて適切な IAM パターンを選択します。
### シンプル: 単一の機能ロール
開発、テスト、またはシンプルなユースケースの場合、必要なすべてのアクセス許可を機能ロールに直接付与します。
**どのようなときに使うか**:
+ ACK の使用を開始する
+ シングルアカウントでデプロイする
+ 1 つのチームがすべてのリソースを管理する
+ 開発環境とテスト環境
**例**: リソースのタグ付け条件に従って、S3 と RDS のアクセス許可を機能ロールに追加します。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:*"],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": ["us-west-2", "us-east-1"]
}
}
},
{
"Effect": "Allow",
"Action": ["rds:*"],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": ["us-west-2", "us-east-1"]
},
}
}
]
}
```
この例では、S3 と RDS のオペレーションを特定のリージョンに制限し、RDS リソースに `ManagedBy: ACK` タグが必要です。
### 本番稼働: IAM ロールセレクター
本番稼働環境では、IAM ロールセレクターを使用して、最小特権のアクセスと名前空間レベルでの分離を実装します。
**どのようなときに使うか**:
+ 本番稼働環境
+ マルチチームクラスター
+ マルチアカウントリソース管理
+ 最小特権セキュリティ要件
+ サービスごとに異なるアクセス許可が必要
**利点:**
+ 名前空間ごとに必要なアクセス許可のみを取得できます。
+ チーム分離 - チーム A は、チーム B のアクセス許可を使用できません。
+ 監査とコンプライアンスが容易です。
+ クロスアカウントリソース管理に必須です。
IAM ロールセレクターの設定の詳細については、「[ACK アクセス許可を設定する](ack-permissions.md)」を参照してください。
## 他の EKS 機能との統合
### GitOps と Argo CD
EKS Capability for Argo CD を使用すると、Git リポジトリから ACK リソースをデプロイして、インフラストラクチャの管理に GitOps ワークフローを使用できます。
**考慮事項**:
+ エンドツーエンドの GitOps のアプリケーションマニフェストと共に ACK リソースを保存する
+ チーム構造に基づいて環境、サービス、またはリソースタイプ別に整理する
+ Argo CD の自動同期を使用して継続的に調整を行う
+ プルーニングを有効にして削除済みのリソースを自動的に除去する
+ マルチクラスターのインフラストラクチャ管理にハブアンドスポークパターンを検討する
GitOps は、監査証跡、ロールバック機能、および宣言型のインフラストラクチャ管理を備えています。Argo CD の詳細については、「[Argo CD の使用](working-with-argocd.md)」を参照してください。
### kro によるリソース構成
EKS Capability for kro (Kube Resource Orchestrator) を使用すると、複数の ACK リソースを高次の抽象化とカスタム API に構成できます。
**どのような場合に ACK で kro を使用するか**:
+ よく見られるインフラストラクチャスタック用に再利用可能なパターンを作成する場合 (データベース \$1 バックアップ \$1 モニタリング)
+ アプリケーションチーム向けに API をシンプルにしてセルフサービスプラットフォームを構築する場合
+ リソースの依存関係を管理し、リソース間で値を渡す (S3 バケット ARN を Lambda 関数に渡す) 場合
+ チーム間でインフラストラクチャ設定を標準化する場合
+ カスタムリソースの背後に実装の詳細を隠して複雑さを軽減する場合
**パターンの例**:
+ アプリケーションスタック: S3 バケット \$1 SQS キュー \$1 通知設定
+ データベースセットアップ: RDS インスタンス \$1 パラメータグループ \$1 セキュリティグループ \$1 シークレット
+ ネットワーク: VPC \$1 サブネット \$1 ルートテーブル \$1 セキュリティグループ
kro は、構成済みのリソースに対して依存関係の順序付け、ステータスの伝播、ライフサイクルの管理を行います。kro の詳細については、「[kro の概念](kro-concepts.md)」を参照してください。
## リソースを整理する
Kubernetes 名前空間と AWS リソースタグを使用して ACK リソースを整理すると、管理、アクセスコントロール、コスト追跡を改善できます。
### 名前空間の整理
Kubernetes 名前空間を使用すると、環境 (本番稼働、ステージング、開発)、チーム (プラットフォーム、データ、ml)、またはアプリケーション別に ACK リソースを論理的に分離できます。
**利点:**
+ アクセスコントロール用に RBAC を名前空間範囲で限定する
+ 注釈を使用して名前空間ごとにデフォルトリージョンを設定する
+ リソース管理とクリーンアップが容易になる
+ 組織構造に沿って論理的に分離できる
### リソースのタグ付け
EKS ACK 機能は、作成するすべての AWS リソースにデフォルトのタグを自動的に適用します。これらのタグはセルフマネージド ACK とは異なり、トレーサビリティが強化されています。
**この機能によって適用されるデフォルトのタグ**:
| タグキー | 説明 |
| --- | --- |
| `eks:controller-version` | ACK コントローラーのバージョン |
| `eks:kubernetes-namespace` | ACK リソースの Kubernetes 名前空間 |
| `eks:kubernetes-resource-name` | Kubernetes リソースの名前 |
| `eks:kubernetes-api-group` | Kubernetes API グループ (例: `s3.services.k8s.aws`) |
| `eks:eks-capability-arn` | EKS ACK 機能の ARN |
**注記**
セルフマネージド ACK は、`services.k8s.aws/controller-version` や `services.k8s.aws/namespace` といった異なるデフォルトタグを使用します。この機能のタグは、他の EKS 機能との一貫性を保つために `eks:` プレフィックスを使用します。
**その他の推奨タグ**:
コスト配分、所有権追跡、および整理目的でカスタムタグを追加します。
+ 環境 (本番稼働、ステージング、開発)
+ チームまたは部門の所有権
+ 請求を配分するためのコストセンター
+ アプリケーション名やサービス名
## 他の Infrastructure as Code ツールからの移行
多くの組織が、Kubernetes を土台にワークロードのオーケストレーションを超えた標準化を図ることに価値を見出しています。インフラストラクチャと AWS リソースの管理を ACK に移行することで、アプリケーションワークロードと共に Kubernetes API を使用してインフラストラクチャ管理を標準化できます。
**Kubernetes を土台にインフラストラクチャを標準化するメリット**:
+ **信頼できる単一のソース**: Kubernetes でアプリケーションとインフラストラクチャの両方を管理して、エンドツーエンドの GitOps プラクティスを実現する
+ **統一されたツール**: チームは Kubernetes のリソースとツールを使用すればよく、いくつものツールやフレームワークを学習する必要がない
+ **一貫性のある調整**: ACK は、Kubernetes がワークロードに対してそうであるように、AWS リソースを継続的に調整し、必須のツールと比較してドリフトを検出して修正する
+ **ネイティブコンポジション**: kro と ACK を一緒に使用して、アプリケーションとリソースのマニフェストで AWS リソースを直接参照し、リソース間で接続文字列と ARN を渡す
+ **シンプルなオペレーション**: 1 つのコントロールプレーンでシステム全体のデプロイ、ロールバック、オブザーバビリティを実現する
ACK は、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 によって管理され、Kubernetes マニフェストを介して更新できます。段階的に移行できるため、必要に応じてリソースを採用しながら、他のリソースでは既存の IaC ツールを維持できます。
また、ACK は読み取り専用リソースもサポートしています。他のチームやツールで管理されるリソースを変更するのではなく参照するだけにする場合は、採用と `retain` 削除ポリシーとを組み合わせて、読み取り IAM アクセス許可のみを付与します。これにより、アプリケーションは変更のリスクを冒すことなく Kubernetes API を介して共有インフラストラクチャ (VPC、IAM ロール、KMS キー) を検出できます。
リソースの採用の詳細については、「[ACK の概念](ack-concepts.md)」を参照してください。
## 削除ポリシー
削除ポリシーは、対応する Kubernetes リソースを削除したときに AWS リソースがどうなるかを制御します。リソースのライフサイクルと実際の運用要件に基づいて、適切なポリシーを選択します。
### 削除する (デフォルト)
Kubernetes リソースを削除すると、AWS リソースも削除されます。そのため、クラスターと AWS との一貫性が維持され、リソースの蓄積を防ぐことができます。
**どのような場合に削除を使用するか**:
+ 開発環境とテスト環境でクリーンアップが重要な場合
+ エフェメラルリソースがアプリケーションのライフサイクルに結びついている場合 (テストデータベースや一時バケット)
+ リソースがアプリケーションよりも長く存続してはいけない場合 (SQS キューや ElastiCache クラスター)
+ コスト最適化 - 未使用のリソースを自動的にクリーンアップする場合
+ GitOps で管理された環境で、Git からリソースが削除されたらインフラストラクチャも削除される場合
Kubernetes の宣言型モデルに合わせてデフォルトの削除ポリシーを調整します。クラスターの内容は AWS に存在するものと一致します。
### Retain
Kubernetes リソースを削除しても、AWS リソースは保持されます。これにより、重要なデータが保護され、リソースは Kubernetes 表現よりも長く存続できます。
**どのような場合に保持を使用するか**:
+ 本番稼働用データベースにクラスターの変更後も存続する必要がある重要なデータが保存されている場合
+ 長期ストレージバケットにコンプライアンス要件や監査要件がある場合
+ 複数のアプリケーションやチームが共有リソースを使用している場合
+ さまざまな管理ツールにリソースを移行する場合
+ ディザスタリカバリでインフラストラクチャを維持する場合
+ 廃止に慎重を要する複雑な依存関係がリソースにある場合
```
apiVersion: rds.services.k8s.aws/v1alpha1
kind: DBInstance
metadata:
name: production-db
annotations:
services.k8s.aws/deletion-policy: "retain"
spec:
dbInstanceIdentifier: prod-db
# ... configuration
```
**重要**
保持したリソースは、引き続き AWS コストが発生するため、不要になったら AWS から手動で削除する必要があります。リソースのタグ付けを使用すると、保持したリソースの中にクリーンアップが必要なものがないかを追跡できます。
削除ポリシーの詳細については、「[ACK の概念](ack-concepts.md)」を参照してください。
## アップストリームドキュメント
ACK の使用の詳細については、以下を参照してください。
+ [ACK 使用ガイド](https://aws-controllers-k8s.github.io/community/docs/user-docs/usage/) - リソースの作成および管理
+ [ACK API リファレンス](https://aws-controllers-k8s.github.io/community/reference/) - すべてのサービスの詳細な API ドキュメント
+ [ACK ドキュメント](https://aws-controllers-k8s.github.io/community/docs/) - ユーザー向けの包括的なドキュメント
## 次のステップ
+ [ACK アクセス許可を設定する](ack-permissions.md) - IAM アクセス許可およびマルチアカウントパターンを設定する
+ [ACK の概念](ack-concepts.md) - ACK の概念およびリソースライフサイクルを理解する
+ [ACK 機能に関する問題をトラブルシューティングする](ack-troubleshooting.md) - ACK の問題をトラブルシューティングする
+ [Argo CD の使用](working-with-argocd.md) - GitOps で ACK リソースをデプロイする
+ [kro の概念](kro-concepts.md) - ACK リソースを高次の抽象化に構成する
# ACK 機能に関する問題をトラブルシューティングする
このトピックでは、機能のヘルスチェック、リソースステータスの確認、IAM アクセス許可の問題など、EKS Capability for ACK をトラブルシューティングする際のガイダンスを示します。
**注記**
EKS の機能は完全に管理され、クラスターの外部で実行されます。コントローラーのログや名前空間にアクセスすることはできません。トラブルシューティングでは、機能のヘルス、リソースのステータス、IAM の設定に焦点を当てています。
## 機能がアクティブなのにリソースが作成されない
ACK 機能のステータスが `ACTIVE` なのに AWS にリソースが作成されない場合は、機能のヘルス、リソースのステータス、IAM アクセス許可を確認してください。
**機能のヘルスを確認する**:
機能のヘルスとステータスの問題は、EKS コンソールまたは AWS CLI を使用して表示できます。
**コンソール:**
1. https://console.aws.amazon.com/eks/home\$1/clusters で Amazon EKS コンソールを開きます。
1. クラスター名を選択します。
1. **[オブザーバビリティ]** タブを選択します。
1. **[クラスターを監視する]** を選択します。
1. **[機能]** タブを選択すると、すべての機能のヘルスとステータスが表示されます。
**AWS CLI**:
```
# View capability status and health
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack
# Look for issues in the health section
```
**一般的な原因:**
+ **IAM アクセス許可がない**: 機能ロールに AWS サービスのアクセス許可が付与されていません。
+ **名前空間が間違っている: **IAMRoleSelector が適切でない名前空間にリソースが作成されました。
+ **リソース仕様が無効である**: リソースのステータス条件に検証エラーがないか確認してください。
+ **API スロットリング**: AWS API レートリミットに達しています。
+ **アドミッションウェブフック**: アドミッションウェブフックのために、コントローラーがリソースステータスにパッチを適用できません。
**リソースのステータスを確認する**:
```
# Describe the resource to see conditions and events
kubectl describe bucket my-bucket -n default
# Look for status conditions
kubectl get bucket my-bucket -n default -o jsonpath='{.status.conditions}'
# View resource events
kubectl get events --field-selector involvedObject.name=my-bucket -n default
```
**IAM アクセス許可を確認する**:
```
# View the Capability Role's policies
aws iam list-attached-role-policies --role-name my-ack-capability-role
aws iam list-role-policies --role-name my-ack-capability-role
# Get specific policy details
aws iam get-role-policy --role-name my-ack-capability-role --policy-name policy-name
```
## AWS にリソースが作成されているのに Kubernetes に表示されない
ACK で追跡できるリソースは、Kubernetes マニフェストを介して作成されたものだけです。ACK で既存の AWS リソースを管理するには、採用機能を使用します。
```
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 の概念](ack-concepts.md)」を参照してください。
## クロスアカウントリソースが作成されない
IAM ロールセレクターの使用時にターゲット AWS アカウントにリソースが作成されない場合は、信頼関係と IAMRoleSelector 設定を確認します。
**信頼関係を確認する**:
```
# Check the trust policy in the target account role
aws iam get-role --role-name cross-account-ack-role --query 'Role.AssumeRolePolicyDocument'
```
信頼ポリシーは、ソースアカウントの機能ロールに引き受けられるようになっている必要があります。
**IAMRoleSelector 設定を確認する**:
```
# List IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector
# Describe specific selector
kubectl describe iamroleselector my-selector
```
**名前空間の配置を確認する**:
IAMRoleSelectors は、クラスター範囲のリソースですが、特定の名前空間をターゲットとします。ACK リソースが IAMRoleSelector の名前空間セレクターに一致する名前空間にあることを確認してください。
```
# Check resource namespace
kubectl get bucket my-cross-account-bucket -n production
# List all IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector
# Check which namespace the selector targets
kubectl get iamroleselector my-selector -o jsonpath='{.spec.namespaceSelector}'
```
**IAMRoleSelected 条件を確認する**:
`ACK.IAMRoleSelected` 条件を調べて、IAMRoleSelector がリソースに正常に一致したものであることを確認します。
```
# Check if IAMRoleSelector was matched
kubectl get bucket my-cross-account-bucket -n production -o jsonpath='{.status.conditions[?(@.type=="ACK.IAMRoleSelected")]}'
```
条件が `False` であるか指定されていない場合は、IAMRoleSelector の名前空間セレクターがリソースの名前空間と一致しません。セレクターの `namespaceSelector` がリソースの名前空間ラベルと一致していることを確認します。
**機能ロールのアクセス許可を確認する**:
機能ロールには、ターゲットアカウントロールの `sts:AssumeRole` および `sts:TagSession` のアクセス許可が必要です。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::[.replaceable]`444455556666`:role/[.replaceable]`cross-account-ack-role`"
}
]
}
```
クロスアカウント設定の詳細については、「[ACK アクセス許可を設定する](ack-permissions.md)」を参照してください。
## 次のステップ
+ [EKS を利用する場合の ACK の考慮事項](ack-considerations.md) - ACK の考慮事項とベストプラクティス
+ [ACK アクセス許可を設定する](ack-permissions.md) - IAM アクセス許可およびマルチアカウントパターンを設定する
+ [ACK の概念](ack-concepts.md) - ACK の概念およびリソースライフサイクルを理解する
+ [EKS 機能をトラブルシューティングする](capabilities-troubleshooting.md) - 一般的な機能をトラブルシューティングする際のガイダンス
# EKS Capability for ACK とセルフマネージド ACK を比較する
EKS Capability for ACK が提供する機能はセルフマネージド ACK コントローラーと同じですが、その操作性に大きなメリットがあります。EKS 機能とセルフマネージドソリューションの全般的な比較については、「[EKS 機能と考慮事項](capabilities-considerations.md)」を参照してください。このトピックでは、ACK に固有の違いに焦点を当てます。
## アップストリーム ACK との違い
EKS Capability for ACK は、アップストリーム ACK コントローラーに基づいていますが、IAM との統合に違いがあります。
**IAM 機能ロール**: この機能は、信頼ポリシーが付与された専用の IAM ロールを使用して `capabilities.eks.amazonaws.com` サービスプリンシパルを許可します。IRSA (サービスアカウントの IAM ロール) は使用しません。IAM ポリシーを直接アタッチできるため、Kubernetes サービスアカウントを作成して注釈を付ける必要も、OIDC プロバイダーを設定する必要もありません。本番稼働のユースケースでは、`IAMRoleSelector` を使用してサービスアクセス許可を設定するのがベストプラクティスです。詳細については、「[ACK アクセス許可を設定する](ack-permissions.md)」を参照してください。
**セッションタグ**: マネージド機能は、すべての AWS API リクエストにセッションタグを自動的に設定し、きめ細かなアクセスコントロールと監査を可能にします。タグには、`eks:eks-capability-arn`、`eks:kubernetes-namespace`、および `eks:kubernetes-api-group` が含まれます。これは、これらのタグをデフォルトで設定しないセルフマネージド ACK とは異なります。IAM ポリシーでのセッションタグの使用の詳細については、「[ACK アクセス許可を設定する](ack-permissions.md)」を参照してください。
**リソースタグ**: この機能は、セルフマネージド ACK とは異なるデフォルトタグを AWS リソースに適用します。この機能では、セルフマネージド ACK で使用される `services.k8s.aws/` タグの代わりに `eks:` プレフィックス付きタグ (`eks:kubernetes-namespace`、`eks:eks-capability-arn` など) を使用します。デフォルトのリソースタグの完全なリストについては、「[EKS を利用する場合の ACK の考慮事項](ack-considerations.md)」を参照してください。
**リソースの互換性**: ACK カスタムリソースは、アップストリーム ACK と同じように動作するため、ACK リソース YAML ファイルを変更する必要はありません。この機能は同じ Kubernetes API と CRD を使用するため、`kubectl` のようなツールは同じように機能します。アップストリーム ACK のすべての GA コントローラーおよびリソースがサポートされています。
ACK ドキュメントとサービス固有の詳細なガイドについては、[ACK ドキュメント](https://aws-controllers-k8s.github.io/community/)を参照してください。
## 移行パス
セルフマネージド ACK からマネージド機能にダウンタイムなしで移行できます。
1. リーダー選出リースに `kube-system` を使用するようにセルフマネージド ACK コントローラーを更新します。次に例を示します。
```
helm upgrade --install ack-s3-controller \
oci://public.ecr.aws/aws-controllers-k8s/s3-chart \
--namespace ack-system \
--set leaderElection.namespace=kube-system
```
これにより、コントローラーのリースが `kube-system` に移動するため、マネージド機能がコントローラーを調整できるようになります。
1. クラスターに ACK 機能を作成します (「[ACK 機能を作成する](create-ack-capability.md)」を参照)。
1. マネージド機能が既存の ACK マネージド AWS リソースを認識して、調整を引き継ぎます。
1. セルフマネージドコントローラーのデプロイを段階的にスケールダウンするか、削除します。
```
helm uninstall ack-s3-controller --namespace ack-system
```
このアプローチにより、移行中、両方のコントローラーを安全に共存させることができます。マネージド機能がこれまでセルフマネージドコントローラーで管理されていたリソースを自動的に採用するため、引き続き競合なく調整を図ることができます。
## 次のステップ
+ [ACK 機能を作成する](create-ack-capability.md) - ACK の機能リソースを作成する
+ [ACK の概念](ack-concepts.md) - ACK の概念およびリソースライフサイクルを理解する
+ [ACK アクセス許可を設定する](ack-permissions.md) - IAM およびアクセス許可を設定する