**協助改進此頁面** 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 GitHub 上編輯此頁面**連結。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # ACK 概念 ACK 透過 Kubernetes APIs 持續協調資訊清單中的所需狀態與實際狀態，來管理 AWS 資源 AWS。當您建立或更新 Kubernetes 自訂資源時，ACK 會進行必要的 AWS API 呼叫來建立或修改對應的 AWS 資源，然後監控資源是否有偏離，並更新 Kubernetes 狀態以反映目前的狀態。此方法可讓您使用熟悉的 Kubernetes 工具和工作流程來管理基礎設施，同時保持叢集與 之間的一致性 AWS。 本主題說明 ACK 如何透過 Kubernetes APIs 管理 AWS 資源的基本概念。 ## ACK 入門 建立 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/)。 ## 資源生命週期和對帳 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/)。 ## 狀態條件 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/)。 ## 刪除政策 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/)。 ## 資源採用 採用可讓您在 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/)。 ## 跨帳戶和跨區域資源 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)。 ## 錯誤處理和重試行為 ACK 會自動處理暫時性錯誤並重試失敗的操作。 重試策略： + 暫時性錯誤 （速率限制、暫時性服務問題、許可不足） 觸發自動重試 + 指數退避可防止壓倒 AWS APIs + 重試嘗試次數上限因錯誤類型而異 + 永久錯誤 （無效的參數、資源名稱衝突） 不會重試 使用 檢查資源狀態的錯誤詳細資訊`kubectl describe`： ``` kubectl describe bucket my-bucket ``` 尋找包含錯誤訊息的狀態條件、顯示最近調校嘗試的事件，以及狀態條件中解釋失敗的 `message` 欄位。常見的錯誤包括 IAM 許可不足、資源名稱衝突 AWS、 中的組態值無效`spec`，以及超出 AWS 服務配額。 如需常見錯誤的疑難排解，請參閱 [對 ACK 功能的問題進行故障診斷](ack-troubleshooting.md)。 ## kro 的資源合成 若要編寫和連接多個 ACK 資源，請使用適用於 kro 的 EKS 功能 (Kube Resource Orchestrator)。kro 提供宣告式方法來定義資源群組，直接在資源之間傳遞組態以管理複雜的基礎設施模式。 如需使用 ACK 資源建立自訂資源組合的詳細範例，請參閱 [kro 概念](kro-concepts.md) ## 後續步驟 + [EKS 的 ACK 考量事項](ack-considerations.md) - EKS 特定的模式和整合策略