轮替根 CA 证书

本页介绍了 Apigee Hybrid 根证书授权机构 (CA) 证书，该证书用于对混合组件彼此通信时使用的内部证书进行签名，并介绍了如何在证书过期之前轮替该证书。从 Apigee Hybrid v1.17 开始，您可以自行轮换此根 CA。

根 CA 证书简介

每个 Apigee Hybrid 安装都有一个根 CA，该根 CA 以 cert-manager Certificate 的形式存储在 cert-manager 命名空间中，名称为 apigee-ca。它是一个自签名 CA（isCA: true，通用名称 apigee-hybrid），充当混合内部证书的信任根，包括组件之间的双向 TLS (mTLS) 和保护准入 Webhook 和自定义资源转换的单向（服务器端）TLS。如果此 CA 过期，混合组件之间的内部通信会中断。

为什么要轮换根 CA 证书

混合图表生成的根 CA 的有效期为 10 年。必须在过期之前轮替该证书，以便其签名的内部证书可以继续续订，并且组件间通信永远不会中断。轮替旨在实现零停机时间：在过渡期间，您的组件同时信任旧根 CA 和新根 CA，因此由任一根 CA 签名的证书在旧 CA 移除之前都保持有效。

轮播的运作方式

您可以通过按顺序将集群推进到四个阶段来轮替根 CA。只有在每个组件上完成当前阶段后，您才能进入下一阶段。每个阶段都由单个替换字段 certRotation.phase 驱动，该字段通过 Apigee 运算符图表 (apigee-operator) 的 helm upgrade 应用。

准备工作

• 安装 kubectl 和 helm 命令行工具，并确保 kubectl 上下文指向您要轮换的集群。
• 确保集群健康状况良好。每个 helm upgrade 都会验证每个 ApigeeDeployment 是否处于 running 状态，以及您请求的阶段是否为当前阶段、下一阶段或回滚阶段。如果集群运行不正常或您尝试跳过某个阶段，则升级会被拒绝。
• 如果您运行的是多区域部署，请在开始之前阅读该部分内容 - 每个区域都必须收敛到相同的新根 CA。

轮替根 CA

按照轮换的运作方式中列出的每个阶段执行以下步骤：应用阶段，然后确认该阶段已完成，再继续执行下一阶段。在多区域部署中，请在每个区域中执行这些步骤。

第 1 步：设置阶段并应用

在替换文件中添加或更新 certRotation stanza，并将 phase 设置为您要应用的阶段。例如，如需启动轮替，请执行以下操作：

certRotation:
  phase: CREATE_NEW_CA

首先通过试运行测试更改：

helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f OVERRIDES_FILE.yaml \
  --dry-run=server

然后应用更改：

helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f OVERRIDES_FILE.yaml

第 2 步：确认阶段已完成

集群会在混合命名空间中的 cert-info ConfigMap 中记录轮换进度。读取其 currentPhase 值：

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.currentPhase}'

仅当 currentPhase 等于您刚刚应用的阶段时，阶段才算完成。只有在每个组件都已协调到请求的阶段后，currentPhase 才会继续推进，因此在匹配之前请勿继续操作。

当 currentPhase 匹配时，从同一 ConfigMap 中读取要应用的下一阶段：

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.readyForNextPhase}'

将 certRotation.phase 设置为该值，然后重复第 1 步和第 2 步。继续操作，直到完成 CLEANUP 阶段。

多区域部署

在多区域部署中，每个集群都有自己的 cert-info ConfigMap、自己的运算符和自己的信任库，并且所有区域最终都必须信任相同的新根 CA。该图表仅在 apigee-ca-2 Secret 尚不存在时生成新的根 CA，因此您只需在主区域中创建一次新的 CA，然后在轮换之前将其复制到其他区域。

按以下顺序执行轮替。在将某个区域移至下一阶段之前，请先确认该区域已完成 currentPhase（请参阅第 2 步：确认阶段已完成）。

1. 在主要区域中运行 CREATE_NEW_CA。该图表会创建新的根 CA 并将其存储在 apigee-ca-2 Secret 中。
2. 在其他区域中运行 CREATE_NEW_CA 之前，请先将主区域的 cert-manager 命名空间中的 apigee-ca-2 secret 复制到每个其他区域的 cert-manager 命名空间中。这与您扩展到新区域时使用的相同密钥复制模式；请参阅多区域部署。
3. 在每个其他区域中运行 CREATE_NEW_CA，一次运行一个区域。由于 apigee-ca-2 Secret 已存在，因此图表会跳过创建新 CA 的步骤，并将区域绑定到共享 CA。
4. 在每个区域中运行 CREATE_NEW_LEAF。
5. 在每个区域中运行 HIDE_OLD_CA。
6. 在每个区域中运行 CLEANUP。
7. 从每个区域的替换文件移除 certRotation stanza，以整理您的配置。

通过 CREATE_NEW_CA、CREATE_NEW_LEAF 和 HIDE_OLD_CA，每个区域都信任旧根 CA 和新根 CA，因此在此期间，各区域可以处于不同的阶段，而不会中断它们之间的流量。

自带 CA

如果您想使用自己的根 CA 而不是图表生成的根 CA，请在开始轮换之前预先创建新的 CA Secret。由于图表仅在缺少目标 Secret 时生成 CA，因此现有 Secret 会按原样使用。

根 CA 名称不是自由格式。hybrid 要求每一代 CA 都采用固定的名称，即 apigee-ca、apigee-ca-2、apigee-ca-3 等，并且图表会查找具有相应名称的下一个 CA。如果您自带 CA，则必须使用确切的下一个名称（首次轮换时为 apigee-ca-2）创建 Secret；图表不会检测到使用任何其他名称创建的 CA。如需查找当前 Secret 名称和要使用的下一个名称，请列出 CA 证书和支持它们的 Secret：

kubectl get certificate -n cert-manager \
  -o custom-columns=CERTIFICATE:.metadata.name,SECRET:.spec.secretName

如需了解检查集群所处代数的更多方法，请参阅跟踪根 CA 过期情况。

1. 在运行 CREATE_NEW_CA 之前，请在 cert-manager 命名空间中创建一个包含下一个 CA 名称（首次轮换为 apigee-ca-2）的 Secret，其中包含您的 CA 证书和私钥。密钥必须为 kubernetes.io/tls 类型，并且包含三个键：tls.crt、tls.key 和 ca.crt。由于 kubectl create secret tls 无法设置 ca.crt 键，因此请使用通用形式：

   kubectl create secret generic apigee-ca-2 \
     --namespace cert-manager \
     --type=kubernetes.io/tls \
     --from-file=tls.crt=CERT_FILE \
     --from-file=tls.key=KEY_FILE \
     --from-file=ca.crt=CA_FILE
   

2. 按照轮替根 CA 中的说明运行轮替。在 CREATE_NEW_CA 期间，图表会检测到您的 apigee-ca-2 Secret，跳过生成 CA 的步骤，并将新签发者 (apigee-ca-issuer-2) 绑定到您的 CA。其他所有阶段均保持不变。

如果您自带证书授权机构，其有效期将与证书的有效期相同，而不是图表的 10 年默认有效期。

回滚轮替

CLEANUP 之前的所有阶段都可以回滚。如需回滚，请将 certRotation.phase 设置为集群报告的回滚目标值，并使用 helm upgrade 应用该值，就像应用正向阶段一样。

从 cert-info ConfigMap 中读取回滚目标：

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.readyForRollbackPhase}'

各阶段的前滚和回滚目标如下：

跟踪根 CA 过期情况

由于 Apigee Hybrid 轮替是由客户驱动的，因此您负责在根 CA 过期之前对其进行轮替。跟踪 apigee-ca 证书的到期时间，并在该日期之前规划轮换，以便您有时间在每个区域完成所有四个阶段。

如需查看根 CA 的过期时间，请列出 cert-manager 命名空间中的 CA 证书，然后读取您当前使用的代际的过期日期：

kubectl get certificate -n cert-manager

kubectl get certificate apigee-ca -n cert-manager \
  -o jsonpath='{.status.notAfter}'

第一个命令会列出每个世代的根 CA（apigee-ca、apigee-ca-2 等）。第二个命令会输出指定证书的到期日期；请针对当前使用的生成版本运行此命令。

Apigee Hybrid 自动问题呈现功能会将检测到的集群问题报告为 ApigeeIssue 资源，您可以使用 kubectl get apigeeissues 列出这些资源。在日常监控过程中，检查是否有已发现的问题。

后续步骤

• 如需了解如何在区域之间共享证书和密钥，请参阅多区域部署。
• 查看在入站流量网关上配置 TLS 和 mTLS，了解单独的客户提供的入站流量证书。
• 查看自动显示问题，以监控集群中检测到的问题。