Deploy Etcd Cluster

Overview

TIP

本指南演示如何使用 etcd operator 部署高可用的 etcd 集群。Etcd 是一个分布式键值存储，为分布式系统提供可靠的数据存储，通常用作 Kubernetes 控制平面数据的后端存储。

INFO

要部署 etcd 集群，您需要安装集群插件 Alauda Build Of etcd Operator，请参考 Install

Prerequisites

在部署 etcd 集群之前，请确保满足以下要求：

已运行的 Kubernetes 集群并安装了 etcd operator
集群中已安装并配置 cert-manager
有足够的资源供 etcd 集群使用（CPU、内存和存储）
配置了用于持久卷的存储类（例如 sc-topolvm）
已配置 kubectl CLI 工具以访问您的集群

Certificate Management

Etcd 需要 TLS 证书以保障集群成员之间的安全通信。您可以使用 cert-manager 生成新的证书，也可以使用已有证书。

本节使用的参数：

{ROOT_CA_NAME}：根 CA 证书及 Secret 的名称（例如 etcd-root-ca）
{CA_ISSUER_NAME}：cert-manager Issuer 的名称（例如 etcd-ca-issuer）

方案一：使用 Cert-Manager 生成 CA

如果您没有现成的 CA，可以使用 cert-manager 创建一个。

步骤 1：生成 CA Secret

创建一个 Certificate 资源来生成根 CA：

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: {ROOT_CA_NAME}
  namespace: cpaas-system
spec:
  isCA: true
  commonName: {ROOT_CA_NAME}
  secretName: {ROOT_CA_NAME}
  duration: 87600h # 10 年
  renewBefore: 720h # 到期前 30 天续期
  issuerRef:
    name: cpaas-ca
    kind: Issuer

应用此配置：

kubectl apply -f root-ca-certificate.yaml

步骤 2：创建根 CA Issuer

CA Secret 创建完成后，创建一个引用该 Secret 的 Issuer：

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: {CA_ISSUER_NAME}
  namespace: cpaas-system
spec:
  ca:
    secretName: {ROOT_CA_NAME}

应用 Issuer 配置：

kubectl apply -f ca-issuer.yaml

验证 Issuer 是否就绪：

kubectl get issuer {CA_ISSUER_NAME} -n cpaas-system

方案二：使用已有 CA

如果您已有存储为 Kubernetes Secret 的 CA 证书，可以直接创建 Issuer：

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: {CA_ISSUER_NAME}
  namespace: cpaas-system
spec:
  ca:
    secretName: {ROOT_CA_NAME}

应用配置：

kubectl apply -f ca-issuer.yaml

Deployment Procedure

步骤 1：确定 Etcd 版本

首先确定要使用的 etcd 版本。您可以查看 global 集群使用的版本：

kubectl get pods -n kube-system -l component=etcd \
  -o jsonpath='{.items[0].spec.containers[0].image}' | awk -F: '{print $NF}'

该命令将输出 etcd 版本，例如：v3.5.21

步骤 2：创建 EtcdCluster 资源

创建一个带有所需配置的 EtcdCluster 自定义资源：

apiVersion: operator.etcd.io/v1alpha1
kind: EtcdCluster
metadata:
  name: {ETCD_CLUSTER_NAME}
  namespace: cpaas-system
spec:
  size: 3  # etcd 成员数量（推荐：3、5 或 7）
  storageSpec:
    accessModes: ReadWriteOnce
    storageClassName: {SC_NAME}  # 使用您的存储类
    volumeSizeLimit: 20Gi  # 最大卷大小
    volumeSizeRequest: 10Gi  # 初始卷大小
  tls:
    provider: cert-manager
    providerCfg:
      certManagerCfg:
        issuerKind: Issuer
        issuerName: {CA_ISSUER_NAME}  # 引用您的 CA issuer
        validityDuration: 87600h 
  version: {ETCD_VERSION}  # 例如 v3.5.21
  etcdOptions:
  - --auto-compaction-mode=periodic
  - --auto-compaction-retention=24h

替换占位符：

{ETCD_CLUSTER_NAME}：您的 etcd 集群名称
{SC_NAME}：您的存储类名称
{CA_ISSUER_NAME}：cert-manager Issuer 名称
{ETCD_VERSION}：etcd 版本（例如 v3.5.21）

应用配置：

kubectl apply -f etcd-cluster.yaml

步骤 3：监控部署状态

监控 StatefulSet 的创建和滚动更新：

# 查看 StatefulSet 状态
kubectl get statefulset -n cpaas-system {ETCD_CLUSTER_NAME}

# 监视 Pod 创建
kubectl get pods -n cpaas-system -l controller={ETCD_CLUSTER_NAME} -w

等待所有 Pod 处于 Running 状态且就绪（可能需要几分钟）。

Verification

部署完成后，验证 etcd 集群是否健康且正常运行：

设置以下变量：

{ETCD_CLUSTER_NAME}：您的 etcd 集群名称（与 EtcdCluster 资源中一致）
{NAMESPACE}：etcd 部署的命名空间（例如 cpaas-system）

检查集群健康

访问其中一个 etcd Pod 并检查集群健康：


ETCD_CLUSTER_NAME={ETCD_CLUSTER_NAME}
NAMESPACE={NAMESPACE}
ETCD_POD=$(kubectl get pods -n cpaas-system -l controller=$ETCD_CLUSTER_NAME -o jsonpath='{.items[0].metadata.name}')

# 检查集群健康
kubectl exec -n cpaas-system $ETCD_POD -- etcdctl \
  --endpoints=$ETCD_POD.$ETCD_CLUSTER_NAME.$NAMESPACE.svc.cluster.local:2379 \
  --cacert=/etc/etcd/certs/server/ca.crt \
  --cert=/etc/etcd/certs/server/tls.crt \
  --key=/etc/etcd/certs/server/tls.key \
  endpoint health

检查集群成员

列出所有集群成员：

kubectl exec -n cpaas-system $ETCD_POD -- etcdctl \
  --endpoints=$ETCD_POD.$ETCD_CLUSTER_NAME.$NAMESPACE.svc.cluster.local:2379 \
  --cacert=/etc/etcd/certs/server/ca.crt \
  --cert=/etc/etcd/certs/server/tls.crt \
  --key=/etc/etcd/certs/server/tls.key \
  member list

测试数据操作

执行简单的写入和读取测试：

# 写入测试键
kubectl exec -n cpaas-system $ETCD_POD -- etcdctl \
  --endpoints=$ETCD_POD.$ETCD_CLUSTER_NAME.$NAMESPACE.svc.cluster.local:2379 \
  --cacert=/etc/etcd/certs/server/ca.crt \
  --cert=/etc/etcd/certs/server/tls.crt \
  --key=/etc/etcd/certs/server/tls.key \
  put test-key Hello

# 读取测试键
kubectl exec -n cpaas-system $ETCD_POD -- etcdctl \
  --endpoints=$ETCD_POD.$ETCD_CLUSTER_NAME.$NAMESPACE.svc.cluster.local:2379 \
  --cacert=/etc/etcd/certs/server/ca.crt \
  --cert=/etc/etcd/certs/server/tls.crt \
  --key=/etc/etcd/certs/server/tls.key \
  get test-key

Configuration Options

集群规模

size 字段决定 etcd 成员数量。生产环境建议：

3 个成员：标准配置，容忍 1 个节点故障
5 个成员：高可用，容忍 2 个节点故障
7 个成员：最大推荐，容忍 3 个节点故障

WARNING

始终使用奇数个成员，以保证故障时能够维持法定人数。

存储配置

storageClassName：指定支持动态供应的存储类
volumeSizeRequest：持久卷的初始大小
volumeSizeLimit：卷可扩展的最大大小（如果存储类支持）

TLS 配置

validityDuration：证书有效期（推荐：8760h，即 1 年）
证书由 cert-manager 在过期前自动续期

Troubleshooting

本节使用的参数：

{ETCD_CLUSTER_NAME}：您的 etcd 集群名称
{POD_NAME}：某个 Pod 的名称（通过 kubectl get pods 获取）
{OTHER_POD_IP}：另一个 Pod 的 IP 地址（通过 kubectl get pods -o wide 获取）
{ROOT_CA_NAME}：根 CA 证书名称
{CA_ISSUER_NAME}：cert-manager Issuer 名称

Pod 无法启动

如果 Pod 启动失败，请检查以下内容：

# 查看 Pod 事件
kubectl describe pods -n cpaas-system -l controller={ETCD_CLUSTER_NAME}

# 查看 Pod 日志
kubectl logs -n cpaas-system {POD_NAME}

# 查看 PVC 状态
kubectl get pvc -n cpaas-system

# 查看 etcd operator 控制器管理器日志
kubectl logs -n cpaas-system -l service_name=etcd-operator-controller-manager

常见问题：

存储容量不足
找不到存储类
证书颁发者未就绪
资源限制（CPU/内存）

集群无法形成法定人数

如果集群无法形成法定人数：

# 查看所有 Pod 日志
kubectl logs -n cpaas-system -l controller={ETCD_CLUSTER_NAME} --all-containers=true

证书问题

验证证书是否正确颁发：

# 查看证书资源
kubectl get certificates -n cpaas-system

# 查看证书详情
kubectl describe certificate {ROOT_CA_NAME} -n cpaas-system

# 查看 Issuer 状态
kubectl get issuer {CA_ISSUER_NAME} -n cpaas-system -o yaml

Best Practices

备份策略：实施定期 etcd 备份以支持灾难恢复
监控：设置监控和告警以保障集群健康
资源限制：配置合适的资源请求和限制
网络策略：实施网络策略以保障 etcd 通信安全
定期维护：保持 etcd 版本更新并监控存储使用情况

#Deploy Etcd Cluster

#目录

#Overview

#Prerequisites

#Certificate Management

#方案一：使用 Cert-Manager 生成 CA

#步骤 1：生成 CA Secret

#步骤 2：创建根 CA Issuer

#方案二：使用已有 CA

#Deployment Procedure

#步骤 1：确定 Etcd 版本

#步骤 2：创建 EtcdCluster 资源

#步骤 3：监控部署状态

#Verification

#检查集群健康

#检查集群成员

#测试数据操作

#Configuration Options

#集群规模

#存储配置

#TLS 配置

#Troubleshooting

#Pod 无法启动

#集群无法形成法定人数

#证书问题

#Best Practices