輪替根 CA 憑證

本頁說明 Apigee Hybrid 根憑證授權單位 (CA) 憑證，該憑證會簽署內部憑證，Hybrid 元件會使用這些憑證彼此通訊，並說明如何在憑證到期前輪替。從 Apigee Hybrid 1.17 版開始，您可以自行輪替這個根 CA。

關於根 CA 憑證

每個 Apigee Hybrid 安裝作業都有單一根層級 CA，以 cert-manager Certificate 的形式儲存在 cert-manager 命名空間中，名稱為 apigee-ca。這是自簽署的 CA (isCA: true，通用名稱為 apigee-hybrid)，可做為混合式發行內部憑證的信任根，包括元件之間的雙向 TLS (mTLS)，以及保護許可控制器和自訂資源轉換的單向 (伺服器端) 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 節，並將 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 密鑰尚不存在時，圖表才會產生新的根 CA，因此您可以在主要區域建立新的 CA，然後在輪替前將其複製到其他區域。

請依下列順序執行輪替作業。確認區域中的 currentPhase (請參閱「步驟 2：確認階段已完成」) 後，再將該區域移至下一個階段。

1. 在主要區域中執行 CREATE_NEW_CA。圖表會鑄造新的根 CA，並將其儲存在 apigee-ca-2 密鑰中。
2. 將主要區域 cert-manager 命名空間中的 apigee-ca-2 密鑰，複製到其他每個區域的 cert-manager 命名空間中，然後再在這些區域中執行 CREATE_NEW_CA。這與您擴展至新區域時使用的密碼副本模式相同；請參閱多區域部署。
3. 在每個其他區域中執行 CREATE_NEW_CA，一次一個區域。由於已存在 apigee-ca-2 密鑰，圖表會略過建立新 CA 的步驟，並將區域繫結至共用 CA。
4. 在每個區域執行 CREATE_NEW_LEAF。
5. 在每個區域執行 HIDE_OLD_CA。
6. 在每個區域執行 CLEANUP。
7. 從每個區域的覆寫檔案中移除 certRotation 節，整理設定。

透過 CREATE_NEW_CA、CREATE_NEW_LEAF 和 HIDE_OLD_CA，每個區域都會信任新舊根 CA，因此在這段期間，各區域可以處於不同階段，彼此之間的流量也不會中斷。

自備 CA

如要使用自己的根 CA，而不是圖表產生的根 CA，請先預先建立新的 CA 密鑰，再開始輪替。由於圖表只會在目標密鑰不存在時產生 CA，因此現有密鑰會照常使用。

根 CA 名稱並非任意形式。hybrid 會預期每個世代的 CA 都有固定名稱，依序為 apigee-ca、apigee-ca-2、apigee-ca-3 等，而圖表會尋找具有該名稱的下一個 CA。自備 CA 時，您必須使用下一個確切名稱 (第一次輪替時為 apigee-ca-2) 建立密鑰；圖表不會偵測以任何其他名稱建立的 CA。如要找出目前的密鑰名稱和下一個要使用的名稱，請列出 CA 憑證和支援這些憑證的密鑰：

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

如要進一步瞭解如何檢查叢集所屬的世代，請參閱「追蹤根憑證授權單位到期日」。

1. 執行 CREATE_NEW_CA 前，請在 cert-manager 命名空間中，使用下一個 CA 名稱 (第一次輪替時為 apigee-ca-2) 建立密鑰，並保留 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 密碼、略過產生 CA，並將新簽發者 (apigee-ca-issuer-2) 繫結至 CA。其他階段則維持不變。

如果您自備 CA，其生命週期會與憑證的生命週期相同， 而非圖表的 10 年預設值。

復原輪替

CLEANUP 之前的每個階段都可以復原。如要復原，請將 certRotation.phase 設為叢集回報的回原目標值，然後使用 helm upgrade 套用，就像套用前進階段一樣。

從 cert-info ConfigMap 讀取回溯目標：

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

各階段的前進和回溯目標如下：

追蹤根憑證授權單位到期日

由於 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 列出這些問題。在例行監控時，檢查是否有浮現的問題。

後續步驟

• 如要瞭解如何跨區域共用憑證和密鑰，請參閱「多區域部署」。
• 請參閱「在 Ingress 閘道上設定 TLS 和 mTLS」，瞭解客戶提供的個別 Ingress 憑證。
• 查看「自動顯示問題」一文，瞭解如何監控叢集，找出偵測到的問題。