本页面适用于 Apigee，但不适用于 Apigee Hybrid。
查看 Apigee Edge 文档。
本页介绍了用于保护与 Apigee 运行时之间的 TLS 连接的 Apigee 根证书授权机构 (CA) 证书，并说明了轮换流程。本文档还列出了受轮换影响的访问模式，以及您应采取的准备应用步骤。
根 CA 证书简介
每个 Apigee 组织都有一个由 Google 管理的根 CA 证书，该证书会颁发 Apigee 运行时入站网关用于 TLS 终结的服务器证书。当客户端打开与 Apigee 实例的 HTTPS 连接时，服务器会提供链接到此根 CA 的证书。验证服务器证书的客户端必须信任根 CA，无论是隐式（当流量流经终止 TLS 的客户管理的负载均衡器时）还是显式（当客户端直接连接到 Apigee 运行时时）。
根 CA 证书在 organizations.get API 响应的 caCertificates[] 字段中公开。该字段是一个数组，因为在轮替期间，系统会同时返回当前根 CA 证书和即将到来的根 CA 证书，以便客户端在割接之前信任这两个证书。
为什么要轮换根 CA 证书
Apigee 根 CA 证书的有效期较长，但有限（通常为 10 年）。在证书过期之前轮替证书，以便：
- 在 Apigee 运行时使用的安全证书永不过期。
- Apigee 组件之间的内部通信渠道继续正常运行，不会中断。
轮换是一项常规的计划内操作。Apigee 会按照 Google Cloud 控制的时间表运行该作业。您不会启动轮换，并且轮换本身不会更改 Apigee 运行时端点或 Apigee API 表面。
轮替阶段和时间表
Apigee 会分四个阶段轮换根 CA 证书。每个阶段都是循序渐进的：它会先在您组织中的一个区域应用，然后逐步扩展到其他区域，因此需要一段时间才能完成。下表介绍了每个阶段对客户的影响以及每个阶段的典型开始时间（相对于当前根 CA 的到期日期）。
| 阶段 | 典型时间安排 | caCertificates[] 中包含的内容 |
具体变化 |
|---|---|---|---|
| 1. 新证书已发布 | 在当前证书失效前大约 1 年 | 当前和新（两者） | Apigee 会生成新的根 CA 证书，并将其添加到每个 Apigee 自有组件的信任库中。新证书也会显示在 organizations.get 响应中，以便您提取并暂存该证书。Apigee 运行时会继续提供由当前根 CA 签名的服务器证书，因此现有客户端暂时不受影响。Apigee 会在开始此阶段时向客户发送通知。 |
| 2. 叶证书割接 | 当前证书到期前大约 60 天 | 当前和新（两者） | Apigee 运行时开始提供由新根 CA 签名的新服务器（叶）证书。仅信任当前根 CA 的客户端在所在区域完成此阶段后，将无法通过 TLS 验证。信任这两个证书（或仅信任新证书）的客户端会继续正常运行。当此阶段开始时，Apigee 会向客户发送通知。 |
| 3. 旧证书已撤销 | 在当前证书到期前大约 30 天 | 仅限新商品 | Apigee 会从内部信任库中移除旧的根 CA，并停止从 organizations.get 返回该根 CA。
仍仅信任旧根 CA 的客户端无法连接。
Apigee 会在开始此阶段时向客户发送通知。 |
| 4. 轮替完成 | 在原失效日期 | 仅限新商品 | Apigee 会永久删除旧根 CA，轮替完成。新根 CA 现在是唯一的根 CA，并且新的大约 10 年周期开始。当此阶段完成时，Apigee 会向客户发送通知。 |
轮替会影响哪些人
轮替是否需要您采取行动取决于客户端访问 Apigee 运行时的方式：
| 访问模式 | 需要采取行动？ | 原因 |
|---|---|---|
| 通过 Google Cloud 外部应用负载均衡器实现外部路由 (MIG) | 否 | 外部负载均衡器使用您管理的证书终止 TLS。客户端信任您的证书，而不是 Apigee 根 CA。轮换对这些客户端没有任何影响。 |
| 内部路由 (VPC)、TLS 选项 1（内部 HTTPS 应用负载均衡器） | 否 | 您的内部负载均衡器使用您管理的证书终止 TLS。客户端信任您的证书，而不是 Apigee 根 CA。轮换对这些客户端没有任何影响。 |
| 内部路由 (VPC)，TLS 选项 2（内部默认完全限定域名） | 是 | 客户端直接连接到 Apigee 管理的内部负载均衡器，并验证 Apigee 颁发的服务器证书。每个客户端都必须在轮替割接之前信任新的根 CA。 |
| 直接通过 TCP 连接到运行时实例入口 IP（例如，通过内部 TCP 负载均衡器） | 是 | 客户端验证 Apigee 颁发的服务器证书。 每个客户端都必须在轮替割接之前信任新的根 CA。 |
非 TLS 选项（curl -k 标志，或跳过证书验证的任何客户端）
|
否 | 客户端不验证服务器证书，因此轮替没有实际效果。在测试环境之外，不建议使用此选项。 |
如何为轮替做好准备
如果您使用的访问模式需要采取行动，请在轮换通知中收到的轮换割接日期之前，按照以下步骤操作。
第 1 步：发现 Apigee 运行时实例
列出组织中的 Apigee 运行时实例。每个实例都有一个专用入站 IP，即直连客户端到达的主机。
# Ensure $AUTH and $PROJECT_ID are set in your environment curl -H "$AUTH" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances \ | jq -r '.instances[] | "\(.name)\t\(.host)"'
如果您的客户端连接到这些 IP 以外的主机（例如，内部负载均衡器前面的自有 DNS 名称），请改用该主机。
第 2 步：获取当前和即将推出的根 CA 证书
从 organizations.get 读取 caCertificates[] 字段。在轮换期间，此数组包含当前根 CA 和新根 CA，每个根 CA 都采用 base64 编码：
curl -H "$AUTH" \
https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
| jq -r '.caCertificates[]' \
| awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'将每个条目解码为 PEM 格式，并检查有效期以确定新证书：
for f in ca_*.b64; do
base64 -d "$f" > "${f%.b64}.crt"
echo "==> ${f%.b64}.crt"
openssl x509 -in "${f%.b64}.crt" -noout -subject -issuer -dates
donenotAfter 日期较晚的证书是新的根 CA。
第 3 步：将新根 CA 添加到信任库
将新的根 CA 证书添加到当前信任 Apigee 根 CA 的每个客户端信任库。在割接完成之前，请保留当前根 CA，以便连接在割接窗口期间继续正常运行。割接后，您可以从信任库中移除旧的根 CA。
具体步骤取决于客户端。常见情况包括：
- 将证书添加到操作系统级信任库（例如，在基于 Debian 的系统上运行
/etc/ssl/certs/，然后运行update-ca-certificates）。 - 将证书添加到应用管理的信任库（例如，Java
cacerts密钥库、Nginxssl_trusted_certificate软件包或 Envoyvalidation_context信任软件包）。 - 将证书添加到已装载到工作负载 Pod 中的 Kubernetes
Secret或ConfigMap。
第 4 步：验证连接是否能正常使用新的根 CA
暂存新根 CA 后，请验证在仅信任新证书的情况下，对 Apigee 运行时的 HTTPS 请求是否成功：
# Ensure $ENV_GROUP_HOSTNAME and $INTERNAL_LOAD_BALANCER_IP are set curl -is -H "Host: $ENV_GROUP_HOSTNAME" \ https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \ --cacert NEW_CA_FILE \ --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP
如果此命令成功执行，则表示您的客户端已准备好进行割接。如果失败，则表示客户端尚不信任新的根 CA，请重新访问第 3 步。
示例：内部路由 (VPC)，TLS 选项 2
此示例演示了内部路由 (VPC)（TLS 选项 2）中记录的访问模式的轮替步骤，其中客户端直接连接到 Apigee 内部负载均衡器并验证 Apigee 自签名证书。这是最常受旋转影响的访问模式。
在割接之前：
- 获取 Apigee 内部负载均衡器的 IP：
export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s \ | jq -r '.instances[0].host')
- 将当前根 CA 和新根 CA 分别提取到单独的文件中，并确定新根 CA：
curl -H "$AUTH" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \ | jq -r '.caCertificates[]' \ | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}' for f in ca_*.b64; do base64 -d "$f" > "${f%.b64}.crt" done # Identify the new root CA (latest notAfter): openssl x509 -in ca_1.crt -noout -dates openssl x509 -in ca_2.crt -noout -dates - 构建一个包含当前根 CA 和新根 CA 的组合信任库，并将其用于测试请求：
cat ca_1.crt ca_2.crt > cacert-combined.crt curl -is -H "Host: $ENV_GROUP_HOSTNAME" \ https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \ --cacert cacert-combined.crt \ --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP
如果此请求成功，请将
cacert-combined.crt部署为客户端信任库。合并后的信任库今天会继续验证当前证书，并在割接后验证新证书。
割接后（通常在割接日期后的几天内），通过验证仅信任新证书时连接是否仍然成功，来确认轮替：
curl -is -H "Host: $ENV_GROUP_HOSTNAME" \ https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \ --cacert NEW_CA_FILE \ --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP
如果此请求成功，您可以放心地从信任库中移除旧的根 CA。
通知
在每个轮换阶段开始时，Apigee 会向 Google Cloud 项目的项目所有者和组织所有者发送通知。每封通知都包含阶段名称、阶段将应用于您组织的日期，以及指向此页面的链接。
| 通知 | 建议客户采取的操作 |
|---|---|
| 1. 发布新证书 （在过期前约 1 年） |
从 caCertificates[] 中获取新的根 CA，并将其添加到当前信任 Apigee 根 CA 的每个客户端信任库中。请参阅如何为轮替做好准备。 |
| 2. 叶证书割接 （在失效前约 60 天） |
在将此阶段应用于您的区域之前，请确认您的所有客户端都信任新的根 CA。在此阶段之后，仅信任旧根 CA 的客户端将无法连接。 |
| 3. 旧证书被撤消 （在失效前约 30 天） |
将此阶段应用于所有区域后，您可以放心地从客户端信任库中移除旧根 CA。 |
| 4. 轮替完成 （在原始到期日期） |
无需执行任何操作。旧根 CA 已被永久删除，新根 CA 是您组织的唯一根 CA。 |
如果您未收到轮换通知，并且您使用的访问模式属于哪些用户会受到轮换影响中列出的模式，请与 Apigee 支持团队联系，确认您组织的通知接收者。
后续步骤
- 查看用于配置 TLS 的选项，了解 Apigee 中的所有 TLS 终结选项。
- 如需了解完整的内部访问调用模式，请参阅调用仅限内部访问的 API 代理。
- 如需查看
caCertificates[]字段的完整架构，请参阅organizations.getAPI 参考文档。