本頁內容適用於 Apigee，但不適用於 Apigee Hybrid。
查看
Apigee Edge 說明文件。
本頁說明 Apigee 根憑證授權單位 (CA) 憑證，該憑證可保護與 Apigee 執行階段的 TLS 連線，並說明輪替程序。此外，這份文件也列出受輪替影響的存取模式，以及您應採取哪些步驟來準備應用程式。
關於根 CA 憑證
每個 Apigee 機構都有 Google 管理的根 CA 憑證，可發行 Apigee 執行階段 Ingress 用於 TLS 終止的伺服器憑證。當用戶端開啟與 Apigee 執行個體的 HTTPS 連線時，伺服器會提供鏈結至這個根 CA 的憑證。驗證伺服器憑證的用戶端必須信任根 CA，無論是隱含 (流量流經終止 TLS 的客戶管理負載平衡器時) 或明確 (用戶端直接連線至 Apigee 執行階段時) 皆然。
根 CA 憑證會顯示在 organizations.get API 回應的 caCertificates[] 欄位中。這個欄位是陣列，因為在輪替期間，系統會同時傳回目前和即將推出的根 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 執行階段的方式：
| 存取模式 | 需要採取行動嗎？ | 原因 |
|---|---|---|
| 外部路由 (MIG)，搭配 Google Cloud 外部應用程式負載平衡器 | 否 | 外部負載平衡器會使用您管理的憑證終止 TLS。用戶端信任的是您的憑證，而非 Apigee 根 CA。輪替不會對這些用戶端造成影響。 |
| 內部路由 (VPC)、TLS 選項 1 (內部 HTTPS 應用程式負載平衡器) | 否 | 內部負載平衡器會使用您管理的憑證終止 TLS。用戶端信任的是您的憑證，而非 Apigee 根 CA。輪替不會對這些用戶端造成影響。 |
| 內部轉送 (虛擬私有雲)、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，且都經過 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。
確切程序取決於用戶端。常見情況包括：
- 將憑證新增至 OS 層級的信任儲存庫 (例如，在以 Debian 為基礎的系統上執行
/etc/ssl/certs/，然後執行update-ca-certificates)。 - 將憑證新增至應用程式管理的信任儲存庫 (例如 Java
cacerts金鑰存放區、Nginxssl_trusted_certificate套件或 Envoyvalidation_context信任套件)。 - 將憑證新增至 Kubernetes
Secret或ConfigMap，並掛接到工作負載 Pod 中。
步驟 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。
範例：內部路由 (虛擬私有雲)、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 的合併信任儲存區，並用於測試要求：
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 Proxy」。
- 如要查看
caCertificates[]欄位的完整結構定義，請參閱organizations.getAPI 參考資料。