本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Terraform 在 Amazon EKS 中部署 CockroachDB 叢集
*Sandip Gangapadhyay 和 Kalyan Senthilnathan，Amazon Web Services*
## 總結
此模式提供 HashiCorp Terraform 模組，用於使用 [CockroachDB](https://www.cockroachlabs.com/docs/stable/) [運算子在 Amazon Elastic Kubernetes Service (Amazon EKS) 上部署多節點 CockroachDB ](https://www.cockroachlabs.com/docs/v25.4/cockroachdb-operator-overview)叢集。CockroachDB 是分散式 SQL 資料庫，可在地理分佈叢集中提供自動水平分片、高可用性和一致的效能。此模式使用 Amazon EKS 作為受管 Kubernetes 平台，並實作 [cert-manager](https://cert-manager.io/docs/) 進行 TLS 安全節點通訊。它還使用 [Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) 進行流量分佈，並使用 Pod 建立 CockroachDB [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/)，以自動複寫資料以實現容錯能力和效能。
**目標對象**
若要實作此模式，建議您熟悉下列項目：
+ HashiCorp Terraform 概念和基礎設施即程式碼 (IaC) 實務
+ AWS 服務，特別是 Amazon EKS
+ Kubernetes 基本概念，包括 StatefulSets、運算子和服務組態
+ 分散式 SQL 資料庫
+ 安全概念，例如 TLS 憑證管理。
+ DevOps 實務、CI/CD 工作流程和基礎設施自動化
## 先決條件和限制
**先決條件**
+ 作用中 AWS 帳戶
+ 在 Amazon EKS 叢集中部署資源的許可
+ 標記節點的 Amazon EKS 叢集版本 1.23 或更新版本 `node=cockroachdb`
+ [Amazon Elastic Block Store 容器儲存界面 (CSI) 驅動程式](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) 1.19.0 版或更新版本，安裝在 Amazon EKS 叢集中
+ Terraform CLI 1.0.0 版或更新版本，[已安裝](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)
+ kubectl，[已安裝](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html)
+ Git，[已安裝](https://git-scm.com/install/)
+ AWS Command Line Interface (AWS CLI) 2.9.18 版或更新版本，[已安裝](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)並[設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
**限制**
+ CockroachDB Kubernetes Operator 不支援多區域部署的多個 Kubernetes 叢集。如需更多限制，請參閱[跨多個 Kubernetes 叢集協調 CockroachDB ](https://www.cockroachlabs.com/docs/stable/orchestrate-cockroachdb-with-kubernetes-multi-cluster.html#eks)(CockroachDB 文件） 和 [CockroachDB Kubernetes Operator](https://github.com/cockroachdb/cockroach-operator) (GitHub)。
+ 持久性磁碟區宣告 (PVCs的自動剔除目前預設為停用。這表示在解除委任並移除節點之後，運算子不會移除掛載至其 Pod 的持久性磁碟區。如需詳細資訊，請參閱 CockroachDB 文件中的[自動 PVC 剔除](https://www.cockroachlabs.com/docs/stable/scale-cockroachdb-kubernetes.html#automatic-pvc-pruning)。
**產品版本**
+ CockroachDB 22.2.2 版
## Architecture
**目標架構**
下圖顯示虛擬私有雲端 (VPC) 中三個 AWS 可用區域的高可用性 CockroachDB 部署。CockroachDB Pod 是透過 Amazon EKS 管理。架構說明使用者如何透過 Network Load Balancer 存取資料庫，將流量分配到 CockroachDB Pod。在每個可用區域中的 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體上執行的 Pod，可提供彈性和容錯能力。
**已建立資源**
部署此模式中使用的 Terraform 模組會建立下列資源：
1. **Network Load Balancer** – 此資源可做為用戶端請求的進入點，並將流量平均分配到 CockroachDB 執行個體。
1. **CockroachDB StatefulSet** – StatefulSet 定義 Amazon EKS 叢集中 CockroachDB 部署的所需狀態。它會管理 CockroachDB Pod 的排序部署、擴展和更新。
1. **CockroachDB Pod** – 這些 Pod 是做為 Kubernetes Pod 內容器執行的 CockroachDB 執行個體。這些 Pod 會跨分散式叢集存放和管理資料。
1. **CockroachDB 資料庫** – 這是由 CockroachDB 管理的分散式資料庫，跨越多個 Pod。它會複寫資料以實現高可用性、容錯能力和效能。
## 工具
**AWS 服務**
+ [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) 是一種開放原始碼工具，可協助您 AWS 服務 透過命令列 shell 中的命令與 互動。
+ [Amazon Elastic Kubernetes Service (Amazon EKS)](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html) 可協助您在 上執行 Kubernetes， AWS 而無需安裝或維護您自己的 Kubernetes 控制平面或節點。
**其他工具**
+ [HashiCorp Terraform](https://www.terraform.io/docs) 是一種基礎設施即程式碼 (IaC) 工具，可協助您使用程式碼來佈建和管理雲端基礎設施和資源。
+ [kubectl](https://kubernetes.io/docs/tasks/tools/) 是一種命令列界面，可協助您針對 Kubernetes 叢集執行命令。
**程式碼儲存庫**
此模式的程式碼可在 GitHub 中使用 [Terraform 儲存庫在 Amazon EKS 中部署 CockroachDB 叢集](https://github.com/aws-samples/crdb-cluster-eks-terraform)中取得。程式碼儲存庫包含下列適用於 Terraform 的檔案和資料夾：
+ `modules` 資料夾 – 此資料夾包含 CockroachDB 的 Terraform 模組
+ `main` 資料夾 – 此資料夾包含呼叫 CockroachDB 子模組的根模組，以建立 CockroachDB 資料庫叢集。
## 最佳實務
+ 請勿縮減至少於三個節點。這被視為 CockroachDB 上的反模式，並可能導致錯誤。如需詳細資訊，請參閱 CockroachDB 文件中的[叢集擴展](https://www.cockroachlabs.com/docs/stable/scale-cockroachdb-kubernetes.html)。
+ 使用 Karpernter 或 Cluster Autoscaler 實作 Amazon EKS 自動擴展。這可讓 CockroachDB 叢集自動水平擴展和自動擴展新節點。如需詳細資訊，請參閱 Amazon EKS 文件中的[使用 Karpenter 和 Cluster Autoscaler 擴展叢集運算](https://docs.aws.amazon.com/eks/latest/userguide/autoscaling.html)。
**注意**
由於 `podAntiAffinity` Kubernetes 排程規則，在一個 Amazon EKS 節點中只能排程一個 CockroachDB Pod。
+ 如需 Amazon EKS 安全最佳實務，請參閱 Amazon EKS 文件中的[安全最佳實務](https://docs.aws.amazon.com/eks/latest/best-practices/security.html)。
+ 如需 CockroachDB 的 SQL 效能最佳實務，請參閱 CockroachDB 文件中的 [SQL 效能最佳實務](https://www.cockroachlabs.com/docs/stable/performance-best-practices-overview.html)。
+ 如需為 Terraform 狀態檔案設定 Amazon Simple Storage Service (Amazon S3) 遠端後端的詳細資訊，請參閱 Terraform 文件中的 [Amazon S3](https://developer.hashicorp.com/terraform/language/backend/s3)。
## 史詩
### 設定您的環境
| 任務 | Description | 所需的技能 |
| --- | --- | --- |
| 複製程式碼儲存庫。 | 輸入下列命令來複製儲存庫：git clone https://github.com/aws-samples/crdb-cluster-eks-terraform.git
| DevOps 工程師，Git |
| 更新 Terraform 變數。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/deploy-cockroachdb-on-eks-using-terraform.html) | DevOps 工程師，Terraform |
### 部署 資源
| 任務 | Description | 所需的技能 |
| --- | --- | --- |
| 部署 基礎設施。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/deploy-cockroachdb-on-eks-using-terraform.html) | DevOps 工程師，Terraform |
### 驗證部署
| 任務 | Description | 所需的技能 |
| --- | --- | --- |
| 驗證資源建立。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/deploy-cockroachdb-on-eks-using-terraform.html) | DevOps 工程師 |
| （選用） 向上或向下擴展。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/deploy-cockroachdb-on-eks-using-terraform.html) | DevOps 工程師，Terraform |
### 清除
| 任務 | Description | 所需的技能 |
| --- | --- | --- |
| 刪除基礎設施。 | 將節點擴展至 `0`可降低運算成本。不過，對於此模組建立的持久性 Amazon EBS 磁碟區，您仍需支付費用。若要降低儲存成本，請依照下列步驟刪除所有磁碟區：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/deploy-cockroachdb-on-eks-using-terraform.html) | Terraform |
## 疑難排解
| 問題 | 解決方案 |
| --- | --- |
| 驗證供應商登入資料時發生錯誤 | 當您執行 Terraform `apply`或 `destroy`命令時，您可能會遇到下列錯誤：
`Error: configuring Terraform AWS Provider: error validating provider credentials: error calling sts:GetCallerIdentity: operation error STS: GetCallerIdentity, https response error StatusCode: 403, RequestID: 123456a9-fbc1-40ed-b8d8-513d0133ba7f, api error InvalidClientTokenId: The security token included in the request is invalid.`
此錯誤是由本機電腦組態中使用的登入資料的安全字符過期所造成。如需如何解決錯誤的指示，請參閱 AWS CLI 文件中的[設定和檢視組態設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-methods)。 |
| 處於待定狀態的 CockroachDB Pod | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/deploy-cockroachdb-on-eks-using-terraform.html) |
## 相關資源
+ [在單一 Kubernetes 叢集中部署 CockroachDB ](https://www.cockroachlabs.com/docs/dev/deploy-cockroachdb-with-kubernetes.html)(CockroachDB 文件）
+ [跨多個 Kubernetes 叢集協調 CockroachDB ](https://www.cockroachlabs.com/docs/dev/orchestrate-cockroachdb-with-kubernetes-multi-cluster.html)(CockroachDB 文件）
+ [AWS 提供者](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) (Terraform 文件）
## 附件
若要存取與本文件相關聯的其他內容，請解壓縮下列檔案： [attachment.zip](samples/p-attach/e22d81ab-b85c-4709-8579-4c9cdb4afdb6/attachments/attachment.zip)