**協助改進此頁面** 

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 GitHub 上編輯此頁面**連結。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 AWS Controllers for Kubernetes (ACK) 從 Kubernetes 部署 AWS 資源
<a name="ack"></a>

 AWS Kubernetes (ACK) 的控制器可讓您直接從 Kubernetes 定義和管理 AWS 服務資源。使用 AWS Controllers for Kubernetes (ACK)，您可以使用 Kubernetes 自訂資源來管理工作負載資源和雲端基礎設施，以及使用熟悉的 Kubernetes APIs 和工具的應用程式工作負載。

透過 EKS 功能，ACK 完全由 管理 AWS，無需在叢集上安裝、維護和擴展 ACK 控制器。

## ACK 的運作方式
<a name="_how_ack_works"></a>

ACK 會將 Kubernetes 自訂資源規格轉換為 AWS API 呼叫。當您建立、更新或刪除代表 AWS 服務資源的 Kubernetes 自訂資源時，ACK 會進行必要的 AWS API 呼叫來建立、更新或刪除 AWS 資源。

ACK 支援的每個 AWS 資源都有自己的自訂資源定義 (CRD)，可定義用於指定其組態的 Kubernetes API 結構描述。例如，ACK 為 S3 提供 CRDs，包括儲存貯體、儲存貯體政策和其他 S3 資源。

ACK 會持續將 AWS 資源的狀態與 Kubernetes 自訂資源中定義的所需狀態進行協調。如果資源偏離其所需狀態，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
```

當您將此自訂資源套用至叢集時，如果帳戶尚未存在，ACK 會在帳戶中建立 Amazon S3 儲存貯體。此資源的後續變更，例如指定非預設儲存層或新增政策，將會套用至其中的 S3 資源 AWS。從叢集刪除此資源時，預設 AWS 會刪除 中的 S3 儲存貯體。

## ACK 的優點
<a name="_benefits_of_ack"></a>

ACK 提供 Kubernetes 原生 AWS 資源管理，可讓您使用與應用程式相同的 Kubernetes APIs 和工具來管理 AWS 資源。這種統一的方法可簡化您的基礎設施管理工作流程，無需在不同工具之間切換或學習單獨的infrastructure-as-code系統。您可以在 Kubernetes 資訊清單中宣告地定義 AWS 資源，讓 GitOps 工作流程和基礎設施成為與現有開發程序無縫整合的程式碼實務。

ACK 會持續協調 AWS 資源的所需狀態及其實際狀態，修正偏離並確保基礎設施的一致性。此持續對帳表示對 AWS 資源進行必要的out-of-band變更會自動還原，以符合您宣告的組態，以維護基礎設施的完整性做為程式碼。您可以設定 ACK 以跨多個 AWS 帳戶和區域管理資源，啟用複雜的多帳戶架構，無需額外的工具。

對於從其他基礎設施管理工具遷移的組織，ACK 支援資源採用，可讓您在 ACK 管理下使用現有 AWS 資源，而無需重新建立。ACK 也提供唯讀資源，無需修改存取即可進行 AWS 資源觀察，以及即使從叢集刪除 Kubernetes 資源，也可以選擇保留 AWS 資源的註釋。

若要進一步了解並開始使用適用於 ACK 的 EKS 功能，請參閱 [ACK 概念](ack-concepts.md)和 [EKS 的 ACK 考量事項](ack-considerations.md)。

## 支援 AWS 的服務
<a name="supported_shared_aws_services"></a>

ACK 支援廣泛的 AWS 服務，包括但不限於：
+ Amazon EC2
+ Amazon S3
+ Amazon RDS
+ Amazon DynamoDB
+ Amazon ElastiCache
+ Amazon EKS
+ Amazon SQS
+ Amazon SNS
+  AWS Lambda
+  AWS IAM

ACK 的 EKS 功能支援所有列為一般可用的上游 AWS 服務。如需詳細資訊，請參閱[支援 AWS 的服務完整清單](https://aws-controllers-k8s.github.io/community/docs/community/services/)。

## 與其他 EKS 受管功能的整合
<a name="_integration_with_other_eks_managed_capabilities"></a>

ACK 與其他 EKS 受管功能整合。
+  **Argo CD**：使用 Argo CD 管理跨多個叢集的 ACK 資源部署，為您的 AWS 基礎設施啟用 GitOps 工作流程。
  + ACK 與 ArgoCD 搭配使用時可延伸 GitOps 的優點，但 ACK 不需要與 git 整合。
+  **kro (Kube Resource Orchestrator)**：使用 kro 從 ACK 資源編寫複雜的資源，建立更高階的抽象，簡化資源管理。
  + 您可以使用同時定義 Kubernetes 資源和資源的 kro 建立複合自訂 AWS 資源。團隊成員可以使用這些自訂資源快速部署複雜的應用程式。

## ACK 入門
<a name="_getting_started_with_ack"></a>

若要開始使用 ACK 的 EKS 功能：

1. 建立並設定具有必要許可的 IAM 功能角色，讓 ACK 代表您管理 AWS 資源。

1.  透過 AWS 主控台、 AWS CLI 或您偏好的基礎設施做為程式碼工具，在您的 EKS 叢集上[建立 ACK 功能資源](create-ack-capability.md)。

1. 將 Kubernetes 自訂資源套用至您的叢集，以開始在 Kubernetes 中管理您的 AWS 資源。

# 建立 ACK 功能
<a name="create-ack-capability"></a>

本章說明如何在 Amazon EKS 叢集上建立 ACK 功能。

## 先決條件
<a name="_prerequisites"></a>

建立 ACK 功能之前，請確定您有：
+ Amazon EKS 叢集
+ IAM 功能角色，具有 ACK 管理 AWS 資源的許可
+ 足夠的 IAM 許可，可在 EKS 叢集上建立功能資源
+ 安裝和設定適當的 CLI 工具，或存取 EKS 主控台

如需建立 IAM 功能角色的說明，請參閱 [Amazon EKS 功能 IAM 角色](capability-role.md)。

**重要**  
ACK 是一種基礎設施管理功能，可授予建立、修改和刪除 AWS 資源的能力。這是應謹慎控制的管理員範圍功能。有權在叢集中建立 Kubernetes 資源的任何人都可以有效透過 ACK 建立 AWS 資源，但需受 IAM 功能角色許可的約束。您提供的 IAM 功能角色會決定 ACK 可以建立和管理哪些 AWS 資源。如需建立具有最低權限許可之適當角色的指引，請參閱 [Amazon EKS 功能 IAM 角色](capability-role.md)和 [EKS 功能的安全考量](capabilities-security.md)。

## 選擇您的工具
<a name="_choose_your_tool"></a>

您可以使用、 AWS 管理主控台 AWS CLI 或 eksctl 建立 ACK 功能：
+  [使用主控台建立 ACK 功能](ack-create-console.md) - 使用 主控台進行引導式體驗
+  [使用 CLI 建立 ACK AWS 功能](ack-create-cli.md) - 使用 AWS CLI 進行指令碼編寫和自動化
+  [使用 eksctl 建立 ACK 功能](ack-create-eksctl.md) - 使用 eksctl 進行 Kubernetes 原生體驗

## 建立 ACK 功能時會發生什麼情況
<a name="_what_happens_when_you_create_an_ack_capability"></a>

當您建立 ACK 功能時：

1. EKS 會建立 ACK 功能服務，並將其設定為監控和管理叢集中的資源

1. 您的叢集中已安裝自訂資源定義 (CRDs)

1. 會自動為您的 IAM 功能角色建立存取項目，其中包含授予基準 Kubernetes 許可的特定功能存取項目政策 （請參閱 [EKS 功能的安全考量](capabilities-security.md))

1. 該功能假設您提供的 IAM 功能角色

1. ACK 開始在您的叢集中監看其自訂資源

1. 功能狀態從 變更為 `CREATING` `ACTIVE` 

啟用後，您可以在叢集中建立 ACK 自訂資源來管理 AWS 資源。

**注意**  
自動建立的存取項目包含授予 ACK 管理 AWS 資源許可`AmazonEKSACKPolicy`的 。有些參考 Kubernetes 秘密的 ACK 資源 （例如具有密碼的 RDS 資料庫） 需要額外的存取項目政策。若要進一步了解存取項目以及如何設定其他許可，請參閱 [EKS 功能的安全考量](capabilities-security.md)。

## 後續步驟
<a name="_next_steps"></a>

建立 ACK 功能之後：
+  [ACK 概念](ack-concepts.md) - 了解 ACK 概念並開始使用 AWS 資源
+  [ACK 概念](ack-concepts.md) - 了解對帳、欄位匯出和資源採用模式
+  [設定 ACK 許可](ack-permissions.md) - 設定 IAM 許可和多帳戶模式

# 使用主控台建立 ACK 功能
<a name="ack-create-console"></a>

本主題說明如何使用 建立 Kubernetes 專用 AWS 控制器 (ACK) 功能 AWS 管理主控台。

## 建立 ACK 功能
<a name="_create_the_ack_capability"></a>

1. 在以下網址開啟 Amazon EKS 主控台：https://console.aws.amazon.com/eks/home\$1/clusters。

1. 選取您的叢集名稱以開啟叢集詳細資訊頁面。

1. 選擇**功能**索引標籤。

1. 在左側導覽中，選擇 **Kubernetes (ACK) 的 AWS 控制器**。

1. 選擇**建立 Kubernetes 功能的 AWS 控制器**。

1. 對於 **IAM 功能角色**：
   + 如果您已經有 IAM 功能角色，請從下拉式清單中選取它
   + 如果您需要建立角色，請選擇**建立管理員角色** 

     這會在新標籤中開啟 IAM 主控台，其中包含預先填入的信任政策和 `AdministratorAccess`受管政策。您可以取消選取此政策，並視需要新增其他許可。

     建立角色後，返回 EKS 主控台並自動選取角色。
**重要**  
建議`AdministratorAccess`的政策授予廣泛的許可，旨在簡化入門。針對生產用途，請以自訂政策取代此政策，該政策僅授予您計劃使用 ACK 管理之特定 AWS 服務所需的許可。如需建立最低權限政策的指引，請參閱 [設定 ACK 許可](ack-permissions.md)和 [EKS 功能的安全考量](capabilities-security.md)。

1. 選擇**建立**。

功能建立程序開始。

## 驗證功能是否處於作用中狀態
<a name="_verify_the_capability_is_active"></a>

1. 在**功能**索引標籤上，檢視 ACK 功能狀態。

1. 等待狀態從 變更為 `CREATING` `ACTIVE`。

1. 啟用後，此功能即可使用。

如需功能狀態和故障診斷的資訊，請參閱 [使用 功能資源](working-with-capabilities.md)。

## 確認可用的自訂資源
<a name="_verify_custom_resources_are_available"></a>

功能處於作用中狀態後，請確認叢集中可用的 ACK 自訂資源。

 **使用主控台** 

1. 在 Amazon EKS 主控台中導覽至您的叢集

1. 選擇**資源**索引標籤

1. 選擇**延伸模組** 

1. 選擇 **CustomResourceDefinitions** 

您應該會看到一些針對 AWS 資源列出的 CRDs。

 **使用 kubectl** 

```
kubectl api-resources | grep services.k8s.aws
```

您應該會看到一些針對 AWS 資源列出的 APIs。

**注意**  
適用於 Kubernetes 的 AWS 控制器功能將為各種 AWS 資源安裝多個 CRDs。

## 後續步驟
<a name="_next_steps"></a>
+  [ACK 概念](ack-concepts.md) - 了解 ACK 概念並開始使用
+  [設定 ACK 許可](ack-permissions.md) - 設定其他服務的 IAM 許可 AWS 
+  [使用 功能資源](working-with-capabilities.md) - 管理您的 ACK 功能資源

# 使用 CLI 建立 ACK AWS 功能
<a name="ack-create-cli"></a>

本主題說明如何使用 CLI 建立 AWS Controllers for Kubernetes (ACK) AWS 功能。

## 先決條件
<a name="_prerequisites"></a>
+  ** 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 功能角色
<a name="_step_1_create_an_iam_capability_role"></a>

建立信任政策檔案：

```
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 功能
<a name="_step_2_create_the_ack_capability"></a>

在叢集上建立 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：確認功能處於作用中狀態
<a name="_step_3_verify_the_capability_is_active"></a>

等待 功能變成作用中。將 *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：確認可用的自訂資源
<a name="_step_4_verify_custom_resources_are_available"></a>

功能處於作用中狀態後，請確認叢集中是否有可用的 ACK 自訂資源：

```
kubectl api-resources | grep services.k8s.aws
```

您應該會看到一些針對 AWS 資源列出的 APIs。

**注意**  
適用於 Kubernetes 的 AWS 控制器功能將為各種 AWS 資源安裝多個 CRDs。

## 後續步驟
<a name="_next_steps"></a>
+  [ACK 概念](ack-concepts.md) - 了解 ACK 概念並開始使用
+  [設定 ACK 許可](ack-permissions.md) - 設定其他服務的 IAM 許可 AWS 
+  [使用 功能資源](working-with-capabilities.md) - 管理您的 ACK 功能資源

# 使用 eksctl 建立 ACK 功能
<a name="ack-create-eksctl"></a>

本主題說明如何使用 eksctl 建立 AWS Controllers for Kubernetes (ACK) 功能。

**注意**  
下列步驟需要 eksctl 版本 `0.220.0` 或更新版本。若要檢查您的版本，請執行 `eksctl version`。

## 步驟 1：建立 IAM 功能角色
<a name="_step_1_create_an_iam_capability_role"></a>

建立信任政策檔案：

```
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)。

**重要**  
此政策使用 授予 S3 儲存貯體管理的許可`"Resource": "*"`，允許對所有 S3 儲存貯體執行操作。  
對於生產用途：\$1 將 `Resource` 欄位限制為特定儲存貯體 ARNs或名稱模式 \$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 功能
<a name="_step_2_create_the_ack_capability"></a>

使用 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：確認功能處於作用中狀態
<a name="_step_3_verify_the_capability_is_active"></a>

檢查功能狀態：

```
eksctl get capability \
  --cluster [.replaceable]`my-cluster` \
  --region [.replaceable]`region-code` \
  --name ack
```

當狀態顯示 時，此功能已就緒`ACTIVE`。

## 步驟 4：確認可用的自訂資源
<a name="_step_4_verify_custom_resources_are_available"></a>

功能處於作用中狀態後，請確認叢集中是否有可用的 ACK 自訂資源：

```
kubectl api-resources | grep services.k8s.aws
```

您應該會看到一些針對 AWS 資源列出的 APIs。

**注意**  
適用於 Kubernetes 的 AWS 控制器功能將為各種 AWS 資源安裝多個 CRDs。

## 後續步驟
<a name="_next_steps"></a>
+  [ACK 概念](ack-concepts.md) - 了解 ACK 概念並開始使用
+  [設定 ACK 許可](ack-permissions.md) - 設定其他服務的 IAM 許可 AWS 
+  [使用 功能資源](working-with-capabilities.md) - 管理您的 ACK 功能資源

# ACK 概念
<a name="ack-concepts"></a>

ACK 透過 Kubernetes APIs 持續協調資訊清單中的所需狀態與實際狀態，來管理 AWS 資源 AWS。當您建立或更新 Kubernetes 自訂資源時，ACK 會進行必要的 AWS API 呼叫來建立或修改對應的 AWS 資源，然後監控資源是否有偏離，並更新 Kubernetes 狀態以反映目前的狀態。此方法可讓您使用熟悉的 Kubernetes 工具和工作流程來管理基礎設施，同時保持叢集與 之間的一致性 AWS。

本主題說明 ACK 如何透過 Kubernetes APIs 管理 AWS 資源的基本概念。

## ACK 入門
<a name="_getting_started_with_ack"></a>

建立 ACK 功能後 （請參閱 [建立 ACK 功能](create-ack-capability.md))，您可以開始使用叢集中的 Kubernetes 資訊清單來管理 AWS 資源。

例如，在 中建立此 S3 儲存貯體資訊清單`bucket.yaml`，選擇您自己的唯一儲存貯體名稱。

```
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/)。

## 資源生命週期和對帳
<a name="_resource_lifecycle_and_reconciliation"></a>

ACK 使用持續對帳迴圈，確保您的 AWS 資源符合 Kubernetes 資訊清單中定義的所需狀態。

 **對帳的運作方式**：

1. 您可以建立或更新 Kubernetes 自訂資源 （例如 S3 儲存貯體）

1. ACK 會偵測變更，並將所需的狀態與 中的實際狀態進行比較 AWS 

1. 如果不同，ACK 會呼叫 AWS API 以協調差異

1. ACK 會更新 Kubernetes 中的資源狀態，以反映目前狀態

1. 迴圈會持續重複，通常每隔幾小時重複一次

當您建立新的 Kubernetes 資源、更新現有資源的 ，或當 ACK AWS 從 ACK 外部的手動變更偵測到偏離時`spec`，就會觸發調校。此外，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/)。

## 狀態條件
<a name="_status_conditions"></a>

ACK 資源使用狀態條件來傳達其狀態。了解這些條件可協助您疑難排解問題並了解資源運作狀態。
+  **就緒**：表示資源已就緒可供使用 （標準化 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/)。

## 刪除政策
<a name="_deletion_policies"></a>

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
```

刪除此資源會刪除其中的 S3 儲存貯體 AWS。

 **保留** 

當您刪除 Kubernetes 資源時， AWS 資源會保留：

```
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。

此`retain`政策適用於生產資料庫，這些資料庫應超過 Kubernetes 資源、多個應用程式使用的共用資源、具有不應意外刪除重要資料的資源，或您採用資源的暫時 ACK 管理、進行設定，然後將其釋出給手動管理。

若要進一步了解 ACK 刪除政策，請參閱 [ACK 刪除政策](https://aws-controllers-k8s.github.io/community/docs/user-docs/deletion-policy/)。

## 資源採用
<a name="_resource_adoption"></a>

採用可讓您在 ACK 管理下使用現有 AWS 資源，而無需重新建立這些資源。

何時使用採用：
+ 將現有基礎設施遷移至 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/)。

## 跨帳戶和跨區域資源
<a name="_cross_account_and_cross_region_resources"></a>

ACK 可以從單一叢集管理不同 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)。

## 錯誤處理和重試行為
<a name="_error_handling_and_retry_behavior"></a>

ACK 會自動處理暫時性錯誤並重試失敗的操作。

重試策略：
+ 暫時性錯誤 （速率限制、暫時性服務問題、許可不足） 觸發自動重試
+ 指數退避可防止壓倒 AWS APIs
+ 重試嘗試次數上限因錯誤類型而異
+ 永久錯誤 （無效的參數、資源名稱衝突） 不會重試

使用 檢查資源狀態的錯誤詳細資訊`kubectl describe`：

```
kubectl describe bucket my-bucket
```

尋找包含錯誤訊息的狀態條件、顯示最近調校嘗試的事件，以及狀態條件中解釋失敗的 `message` 欄位。常見的錯誤包括 IAM 許可不足、資源名稱衝突 AWS、 中的組態值無效`spec`，以及超出 AWS 服務配額。

如需常見錯誤的疑難排解，請參閱 [對 ACK 功能的問題進行故障診斷](ack-troubleshooting.md)。

## kro 的資源合成
<a name="_resource_composition_with_kro"></a>

若要編寫和連接多個 ACK 資源，請使用適用於 kro 的 EKS 功能 (Kube Resource Orchestrator)。kro 提供宣告式方法來定義資源群組，直接在資源之間傳遞組態以管理複雜的基礎設施模式。

如需使用 ACK 資源建立自訂資源組合的詳細範例，請參閱 [kro 概念](kro-concepts.md) 

## 後續步驟
<a name="_next_steps"></a>
+  [EKS 的 ACK 考量事項](ack-considerations.md) - EKS 特定的模式和整合策略

# 設定 ACK 許可
<a name="ack-permissions"></a>

ACK 需要 IAM 許可，才能代表您建立和管理 AWS 資源。本主題說明 IAM 如何與 ACK 搭配使用，並提供設定不同使用案例許可的指引。

## IAM 如何與 ACK 搭配使用
<a name="_how_iam_works_with_ack"></a>

ACK 使用 IAM 角色對 資源進行身分驗證 AWS 和執行動作。提供許可給 ACK 的方式有兩種：

 **功能角色**：您在建立 ACK 功能時提供的 IAM 角色。根據預設，所有 ACK 操作都會使用此角色。

 **IAM 角色選取器**：可映射至特定命名空間或資源的其他 IAM 角色。這些角色會覆寫其範圍內資源的功能角色。

當 ACK 需要建立或管理資源時，它會決定要使用的 IAM 角色：

1. 檢查 IAMRoleSelector 是否符合資源的命名空間

1. 如果找到相符項目，請擔任該 IAM 角色

1. 否則，請使用 功能角色

此方法可實現從簡單的單一角色設定到複雜多帳戶、多團隊組態的彈性許可管理。

## 入門：簡易許可設定
<a name="_getting_started_simple_permission_setup"></a>

對於開發、測試或簡單使用案例，您可以將所有必要的服務許可直接新增至功能角色。

此方法在下列情況下運作良好：
+ 您即將開始使用 ACK
+ 所有資源都在同一個 AWS 帳戶中
+ 單一團隊管理所有 ACK 資源
+ 您信任所有 ACK 使用者都具有相同的許可

## 生產最佳實務：IAM 角色選取器
<a name="_production_best_practice_iam_role_selectors"></a>

對於生產環境，請使用 IAM 角色選取器實作最低權限存取和命名空間層級隔離。

使用 IAM 角色選取器時，功能角色只需要 `sts:AssumeRole`和 `sts:TagSession`許可，即可擔任服務特定的角色。您不需要將任何 AWS 服務許可 （例如 S3 或 RDS) 新增至功能角色本身，這些許可會授予功能角色擔任的個別 IAM 角色。

 **在許可模型之間進行選擇**：

在下列情況下使用**直接許可** （將服務許可新增至功能角色）：
+ 您正在開始使用，並想要最簡單的設定
+ 所有資源都與您的叢集位於相同的帳戶
+ 您有全叢集的管理許可要求
+ 所有團隊都可以共用相同的許可

在下列情況下使用 **IAM 角色選取器**：
+ 跨多個 AWS 帳戶管理資源
+ 不同的團隊或命名空間需要不同的許可
+ 您需要每個命名空間的精細存取控制
+ 您想要遵循最低權限的安全實務

您可以從直接許可開始，並在需求增加之後遷移至 IAM 角色選取器。

 **為什麼要在生產環境中使用 IAM 角色選取器：**
+  **最低權限**：每個命名空間只會取得所需的許可
+  **團隊隔離**：團隊 A 不會意外使用團隊 B 的許可
+  **更容易稽核**：明確映射命名空間使用哪個角色
+  **跨帳戶支援**：管理多個帳戶中的資源時需要
+  **問題分離**：不同的服務或環境使用不同的角色

### 基本 IAM 角色選取器設定
<a name="_basic_iam_role_selector_setup"></a>

 **步驟 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
```

## 多帳戶管理
<a name="_multi_account_management"></a>

使用 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
```

## 工作階段標籤
<a name="_session_tags"></a>

EKS ACK 功能會自動在所有 AWS API 請求上設定工作階段標籤。這些標籤透過識別每個請求的來源來啟用精細存取控制和稽核。

### 可用的工作階段標籤
<a name="_available_session_tags"></a>

ACK 所做的每個 AWS API 呼叫都會包含下列工作階段標籤：


| 標籤索引鍵 | Description | 
| --- | --- | 
|   `eks:eks-capability-arn`   |  提出請求之 EKS 功能的 ARN  | 
|   `eks:kubernetes-namespace`   |  受管資源的 Kubernetes 命名空間  | 
|   `eks:kubernetes-api-group`   |  資源的 Kubernetes API 群組 （例如 `s3.services.k8s.aws`)  | 

### 使用工作階段標籤進行存取控制
<a name="_using_session_tags_for_access_control"></a>

您可以在 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 角色選取器模式
<a name="_advanced_iam_role_selector_patterns"></a>

如需進階組態，包括標籤選擇器、資源特定角色映射和其他範例，請參閱 [ACK IRSA 文件](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/)。

## 後續步驟
<a name="_next_steps"></a>
+  [ACK 概念](ack-concepts.md) - 了解 ACK 概念和資源生命週期
+  [ACK 概念](ack-concepts.md) - 了解資源採用和刪除政策
+  [EKS 功能的安全考量](capabilities-security.md) - 了解 功能的安全最佳實務

# EKS 的 ACK 考量事項
<a name="ack-considerations"></a>

本主題涵蓋使用 ACK 的 EKS 功能的重要考量，包括 IAM 組態、多帳戶模式，以及與其他 EKS 功能的整合。

## IAM 組態模式
<a name="_iam_configuration_patterns"></a>

ACK 功能使用 IAM 功能角色進行身分驗證 AWS。根據您的需求選擇正確的 IAM 模式。

### 簡單：單一功能角色
<a name="_simple_single_capability_role"></a>

對於開發、測試或簡單使用案例，請將所有必要的許可直接授予能力角色。

 **使用時機**：
+ ACK 入門
+ 單一帳戶部署
+ 由一個團隊管理的所有資源
+ 開發和測試環境

 **範例**：使用資源標記條件將 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 角色選取器
<a name="_production_iam_role_selectors"></a>

對於生產環境，請使用 IAM 角色選取器實作最低權限存取和命名空間層級隔離。

 **使用時機**：
+ 生產環境
+ 多團隊叢集
+ 多帳戶資源管理
+ 最低權限的安全需求
+ 不同的服務需要不同的許可

 **優點**：
+ 每個命名空間只會取得所需的許可
+ 團隊隔離 - 團隊 A 無法使用團隊 B 的許可
+ 更輕鬆地稽核和合規
+ 跨帳戶資源管理的必要項目

如需詳細的 IAM 角色選取器組態，請參閱 [設定 ACK 許可](ack-permissions.md)。

## 與其他 EKS 功能整合
<a name="_integration_with_other_eks_capabilities"></a>

### 使用 Argo CD 的 GitOps
<a name="_gitops_with_argo_cd"></a>

使用適用於 Argo CD 的 EKS 功能從 Git 儲存庫部署 ACK 資源，啟用基礎設施管理的 GitOps 工作流程。

 **考量：**
+ 將 ACK 資源與end-to-end GitOps 的應用程式資訊清單一起存放
+ 根據您的團隊結構，依環境、服務或資源類型進行組織
+ 使用 Argo CD 的自動同步進行持續調校
+ 啟用剔除以自動移除已刪除的資源
+ 考慮多叢集基礎設施管理的hub-and-spoke模式

GitOps 提供稽核追蹤、復原功能和宣告式基礎設施管理。如需 Argo CD 的詳細資訊，請參閱[使用 Argo CD](working-with-argocd.md)。

### kro 的資源合成
<a name="_resource_composition_with_kro"></a>

使用 kro 的 EKS 功能 (Kube Resource Orchestrator)，將多個 ACK 資源組成更高層級的抽象和自訂 APIs。

 **何時搭配 ACK 使用 kro**：
+ 為常見的基礎設施堆疊建立可重複使用的模式 （資料庫 \$1 備份 \$1 監控）
+ 為應用程式團隊建置具有簡化 APIs自助式平台
+ 管理資源相依性，並在資源之間傳遞值 (S3 儲存貯體 ARN 至 Lambda 函數）
+ 標準化跨團隊的基礎設施組態
+ 透過隱藏自訂資源後方的實作詳細資訊來降低複雜性

 **範例模式**：
+ 應用程式堆疊：S3 儲存貯體 \$1 SQS 佇列 \$1 通知組態
+ 資料庫設定：RDS 執行個體 \$1 參數群組 \$1 安全群組 \$1 秘密
+ 網路：VPC \$1 子網路 \$1 路由表 \$1 安全群組

kro 會處理編寫資源的相依性排序、狀態傳播和生命週期管理。如需 kro 的詳細資訊，請參閱[kro 概念](kro-concepts.md)。

## 組織您的 資源
<a name="_organizing_your_resources"></a>

使用 Kubernetes 命名空間和資源標籤組織 ACK AWS 資源，以獲得更好的管理、存取控制和成本追蹤。

### 命名空間組織
<a name="_namespace_organization"></a>

使用 Kubernetes 命名空間，以邏輯方式依環境 （生產、預備、開發）、團隊 （平台、資料、ml) 或應用程式分隔 ACK 資源。

 **優點**：
+ 用於存取控制的命名空間範圍 RBAC
+ 使用註釋設定每個命名空間的預設區域
+ 更輕鬆地進行資源管理和清理
+ 符合組織結構的邏輯分隔

### 資源標記
<a name="_resource_tagging"></a>

EKS ACK 功能會自動將預設標籤套用至其建立的所有 AWS 資源。這些標籤與自我管理的 ACK 不同，並提供增強的可追蹤性。

 **功能套用的預設標籤**：


| 標籤索引鍵 | Description | 
| --- | --- | 
|   `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工具遷移
<a name="_migration_from_other_infrastructure_as_code_tools"></a>

許多組織發現在 Kubernetes 上標準化工作負載協同運作之外的價值。將基礎設施 AWS 和資源管理遷移到 ACK 可讓您使用 Kubernetes APIs 和應用程式工作負載來標準化基礎設施管理。

 **在適用於基礎設施的 Kubernetes 上標準化的優勢**：
+  **單一事實來源**：在 Kubernetes 中管理應用程式和基礎設施，實現end-to-end GitOps 實務
+  **統一工具**：團隊使用 Kubernetes 資源和工具，而不是學習多個工具和架構
+  **一致的對帳**：ACK 會持續對 Kubernetes 對工作負載所做的 AWS 資源進行對帳，並與必要工具相比，偵測和修正偏離
+  **原生組成**：使用 kro 和 ACK， AWS 直接在應用程式和資源資訊清單中參考資源，在資源之間傳遞連線字串和 ARNs 
+  **簡化的操作**：在整個系統中部署、復原和可觀測性的單一控制平面

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 探索共用基礎設施 (VPCs、IAM 角色、KMS 金鑰），而不會有修改的風險。 APIs 

如需資源採用的詳細資訊，請參閱[ACK 概念](ack-concepts.md)。

## 刪除政策
<a name="_deletion_policies"></a>

當您刪除對應的 AWS Kubernetes 資源時，刪除政策會控制資源會發生的情況。根據資源生命週期和您的操作需求，選擇正確的政策。

### 刪除 （預設）
<a name="_delete_default"></a>

 AWS 刪除 Kubernetes 資源時會刪除資源。這可維持叢集與 之間的一致性 AWS，確保資源不會累積。

 **何時使用刪除**：
+ 清理很重要的開發和測試環境
+ 與應用程式生命週期繫結的暫時性資源 （測試資料庫、臨時儲存貯體）
+ 不應讓應用程式過期的資源 (SQS 佇列、ElastiCache 叢集）
+ 成本最佳化 - 自動清除未使用的資源
+ 使用 GitOps 管理的環境，其中從 Git 移除資源應刪除基礎設施

預設刪除政策符合 Kubernetes 的宣告式模型：叢集中的內容符合 中存在的內容 AWS。

### 保留
<a name="_retain"></a>

當您刪除 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)。

## 上游文件
<a name="_upstream_documentation"></a>

如需使用 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/) - 完整的使用者文件

## 後續步驟
<a name="_next_steps"></a>
+  [設定 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 功能的問題進行故障診斷
<a name="ack-troubleshooting"></a>

本主題提供 ACK 的 EKS 功能疑難排解指引，包括功能運作狀態檢查、資源狀態驗證和 IAM 許可問題。

**注意**  
EKS 功能是完全受管的，並在叢集外部執行。您無法存取控制器日誌或控制器命名空間。故障診斷著重於功能運作狀態、資源狀態和 IAM 組態。

## 功能是 ACTIVE，但資源尚未建立
<a name="_capability_is_active_but_resources_arent_being_created"></a>

如果您的 ACK 功能顯示`ACTIVE`狀態，但未在其中建立資源 AWS，請檢查功能運作狀態、資源狀態和 IAM 許可。

 **檢查功能運作狀態**：

您可以在 EKS 主控台或使用 AWS CLI 檢視功能運作狀態和狀態問題。

 **主控台**：

1. 在以下網址開啟 Amazon EKS 主控台：https://console.aws.amazon.com/eks/home\$1/clusters。

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 速率限制
+  **許可 Webhook**：許可 Webhook 封鎖控制器修補資源狀態

 **檢查資源狀態**：

```
# 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 中顯示的資源
<a name="resources_created_in_shared_aws_but_not_showing_in_kubernetes"></a>

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)。

## 未建立跨帳戶資源
<a name="_cross_account_resources_not_being_created"></a>

如果使用 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)。

## 後續步驟
<a name="_next_steps"></a>
+  [EKS 的 ACK 考量事項](ack-considerations.md) - ACK 考量事項和最佳實務
+  [設定 ACK 許可](ack-permissions.md) - 設定 IAM 許可和多帳戶模式
+  [ACK 概念](ack-concepts.md) - 了解 ACK 概念和資源生命週期
+  [對 EKS 功能進行故障診斷](capabilities-troubleshooting.md) - 一般功能故障診斷指引

# 比較 ACK 與自我管理 ACK 的 EKS 功能
<a name="ack-comparison"></a>

EKS 的 ACK 功能提供與自我管理 ACK 控制器相同的功能，但具有顯著的操作優勢。如需 EKS 功能與自我管理解決方案的一般比較，請參閱 [EKS 功能考量事項](capabilities-considerations.md)。本主題著重於 ACK 特定的差異。

## 與上游 ACK 的差異
<a name="_differences_from_upstream_ack"></a>

ACK 的 EKS 功能是以上游 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 不同，其預設不會設定這些標籤。如需在 [設定 ACK 許可](ack-permissions.md) IAM 政策中使用工作階段標籤的詳細資訊，請參閱 。

 **資源標籤**： 功能會將不同的預設標籤套用至 AWS 資源，而非自我管理的 ACK。此功能使用字`eks:`首標籤 （例如 `eks:kubernetes-namespace`、`eks:eks-capability-arn`)，而不是自我管理 ACK 使用的`services.k8s.aws/`標籤。如需預設資源標籤的完整清單，[EKS 的 ACK 考量事項](ack-considerations.md)請參閱 。

 **資源相容性**：ACK 自訂資源的運作方式與上游 ACK 相同，不會變更您的 ACK 資源 YAML 檔案。該功能使用相同的 Kubernetes APIs 和 CRDs，因此 等工具`kubectl`的運作方式相同。支援來自上游 ACK 的所有 GA 控制器和資源。

如需完整的 ACK 文件和服務特定指南，請參閱 [ACK 文件](https://aws-controllers-k8s.github.io/community/)。

## 遷移路徑
<a name="_migration_path"></a>

您可以從自我管理的 ACK 遷移到受管功能，無需停機：

1. 更新您的自我管理 ACK 控制器以`kube-system`用於領導者選擇租用，例如：

   ```
   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
   ```

此方法可讓兩個控制器在遷移期間安全地共存。受管功能會自動採用先前由自我管理控制器管理的資源，確保持續對帳而不會發生衝突。

## 後續步驟
<a name="_next_steps"></a>
+  [建立 ACK 功能](create-ack-capability.md) - 建立 ACK 功能資源
+  [ACK 概念](ack-concepts.md) - 了解 ACK 概念和資源生命週期
+  [設定 ACK 許可](ack-permissions.md) - 設定 IAM 和許可