在 Hashicorp Vault 中輪替 Cassandra 憑證

總覽

本程序說明如何在 Hashicorp Vault 中輪替 Cassandra 憑證。如要輪替叢集中 Kubernetes 密鑰中的憑證，請參閱「輪替 Kubernetes 密鑰中的 Cassandra 憑證」。

這項功能可讓平台管理員：

• 在 HashiCorp 保管箱中輪替 Cassandra 憑證。
• 如果密碼輪替期間發生任何問題，請回復使用 Vault 中的舊 Cassandra 憑證。
• 請一次輪替一個區域的 Cassandra 密碼，以確保對服務可用性的影響降到最低，並維持輪替程序的控管權。
• 追蹤單一區域的旋轉作業開始、進度和完成情況。

這項功能適用於 Apigee Hybrid 1.13.1 以上版本。

中的操作說明進行。

事前準備

設定憑證輪替前：

• 備份 Cassandra 資料庫。這項備份功能可確保可復原先前輪替的憑證。
• 請確認叢集處於正常運作狀態 (也就是所有 Apigee 資源皆在執行中，沒有待處理的狀態變更)。

單一區域設定

1. 在 Apigee 命名空間中，為新的 Cassandra 憑證建立新的 SecretProviderClass Kubernetes 資源。請參閱「在 Hashicorp Vault 中儲存 Cassandra 機密」一文，瞭解可用的範本。這樣一來，Vault 角色就能存取 Kubernetes 命名空間中的密鑰。
2. 使用下列範本建立新的 SecretRotation 自訂資源：

   # rotation.yaml
   
   apiVersion: apigee.cloud.google.com/v1alpha1
   kind: SecretRotation
   metadata:
     name: ROTATION_PROCESS_NAME
     namespace: APIGEE_NAMESPACE
   spec:
     organizationId: ORG_NAME
     rotationId: ROTATION_ID
     timeoutMinutes: 480 # optional. overrides the default (480m == 8hr).
                         # less than or equal to 0 means infinite timeout.
     precheck: true
     cassandra:
       oldSecretProviderClass: OLD_SPC_NAME
       newSecretProviderClass: NEW_SPC_NAME
       jobType: ROTATE
   

   • ROTATION_PROCESS_NAME：輪替工作專屬名稱。您必須將 metadata.name 設為旋轉預檢工作和旋轉工作的專屬值。例如 sr-1-precheck 後面接著 sr-1。
   • ROTATION_ID：將 spec.rotationId 設為自訂 ID，例如 rotation-1-precheck。
   • NEW_SPC_NAME：將 spec.cassandra.newSecretProviderClass 設為您在上一個步驟中建立的新密鑰提供者類別名稱。
   • OLD_SPC_NAME：將 spec.cassandra.oldSecretProviderClass 設為 ApigeeDatastore 目前使用的 SPC 名稱。
3. 套用 rotation.yaml 檔案，觸發旋轉預先檢查工作。

   kubectl -n APIGEE_NAMESPACE apply -f rotation.yaml

4. 查看工作狀態，確認預先檢查工作是否已完成。

   kubectl -n APIGEE_NAMESPACE get job sr-(rotationId)-(rotate|rollback|cleanup)-job

5. 旋轉預先檢查工作完成後，請變更 metadata.name 的值，並將 spec.precheck 設為 false。再次套用檔案即可旋轉。

   kubectl -n APIGEE_NAMESPACE apply -f rotation.yaml

6. 輪替工作完成後，如果您已驗證流量仍可正常流動，請按照下列兩個步驟清理程序：
   1. 更新 metadata.name 的值，並將 spec.cassandra.jobType 設為 CLEANUP。
   2. 套用檔案即可觸發清理工作。

      kubectl -n APIGEE_NAMESPACE apply -f rotation.yaml

   清除工作完成後，輪替程序就會結束。

7. 更新覆寫檔案，並將 cassandra.auth.secretProviderClass 設為新的密鑰提供者類別 (newSecretProviderClass)。

   cassandra:
     auth:
       secretProviderClass: NEW_SPC_NAME

8. 備份 Cassandra 資料庫。這項備份功能可確保旋轉後的憑證可進行還原。
9. 從 Vault 中刪除舊的 Cassandra 憑證、角色和政策。

多區域設定

多區域設定程序分為兩個部分：第一個區域的設定，以及其餘區域的設定。

1. 請先在第一個區域完成下列步驟，再開始處理後續區域。
   1. 為新的 Cassandra 憑證，在 APIGEE_NAMESPACE 命名空間中建立新的 SecretProviderClass Kubernetes 資源。請參閱「在 Hashicorp Vault 中儲存 Cassandra 機密」一文，瞭解可用的範本。這樣一來，Vault 角色就能存取 Kubernetes 命名空間中的密鑰。
   2. 使用下列範本建立新的 SecretRotation 自訂資源：

      # rotation.yaml
      
      apiVersion: apigee.cloud.google.com/v1alpha1
      kind: SecretRotation
      metadata:
        name: ROTATION_PROCESS_NAME
        namespace: APIGEE_NAMESPACE
      spec:
        organizationId: ORG_NAME
        rotationId: ROTATION_ID
        timeoutMinutes: -1 # this value is required and should not be changed.
        precheck: true
        cassandra:
          oldSecretProviderClass: OLD_SPC_NAME
          newSecretProviderClass: NEW_SPC_NAME
          jobType: ROTATE
      

      • ROTATION_PROCESS_NAME：輪替工作專屬名稱。您必須將 metadata.name 設為旋轉預檢工作和旋轉工作的專屬值。例如 sr-1-precheck 後面接著 sr-1。
      • ROTATION_ID：將 spec.rotationId 設為自訂 ID，例如 rotation-1-precheck。
      • NEW_SPC_NAME：將 spec.cassandra.newSecretProviderClass 設為您在上一個步驟中建立的新密鑰提供者類別名稱。
      • OLD_SPC_NAME：將 spec.cassandra.oldSecretProviderClass 設為 ApigeeDatastore 目前使用的 SPC 名稱。
   3. 套用 rotation.yaml 檔案，觸發旋轉預先檢查工作。

      kubectl -n APIGEE_NAMESPACE apply -f rotation.yaml

   4. 查看工作狀態，確認預先檢查工作是否已完成。

      kubectl -n APIGEE_NAMESPACE get job sr-(rotationId)-(rotate|rollback|cleanup)-job

   5. 輪替預先檢查工作完成後：
      • 變更 metadata.name 的值，例如從 sr-1-precheck 變更為 sr-1。
      • 將 spec.precheck 設為 false 即可關閉預先檢查並執行旋轉。
      • 將 spec.rotationId 設為新的 ID，例如 rotation-1。
   6. 再次套用檔案即可旋轉。

      kubectl -n APIGEE_NAMESPACE apply -f rotation.yaml

   7. 請檢查 SecretRotation 的狀態，並等待狀態變成 complete。

      kubectl -n APIGEE_NAMESPACE get sr SR_NAME

2. 在後續每個區域中，完成下列步驟：
   1. 在 Apigee 命名空間中，為新的 Cassandra 憑證建立新的 SecretProviderClass Kubernetes 資源。請參閱「在 Hashicorp Vault 中儲存 Cassandra 機密」一文，瞭解可用的範本。這個定義應與步驟 1a 相同。
   2. 更新 overrides.yaml，並將 cassandra.auth.secretProviderClass 設為與 rotation.yaml 檔案中的 spec.cassandra.newSecretProviderClass 值相符。

      cassandra:
        auth:
          secretProviderClass: NEW_SPC_NAME

   3. 套用運算子圖表：

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

   4. 系統會建立新的 ReplicaSet。確認新的控制器管理員 Pod 是否使用新的 SPC：

      export POD=NEW_CONTROLLER_MANAGER_POD_NAME
      kubectl -n APIGEE_NAMESPACE get pods $POD -o jsonpath='{.spec.volumes[?(@.name=="apigee-external-secrets")].csi.volumeAttributes.secretProviderClass}'
      

      結果應與您在 rotation.yaml 中為 spec.cassandra.newSecretProviderClass 設定的值相符，例如：

      kubectl -n apigee get pods $POD -o jsonpath='{.spec.volumes[?(@.name=="apigee-external-secrets")].csi.volumeAttributes.secretProviderClass}'
      
      my-new-spc

   5. 套用資料儲存庫圖表：

      helm upgrade datastore apigee-datastore/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f OVERRIDES_FILE

   6. 資料儲存庫會進入釋出狀態。請等待資料儲存庫釋出完成，並處於執行狀態。

      kubectl -n APIGEE_NAMESPACE get apigeedatastore DATASTORE_NAME

      在大多數安裝作業中，DATASTORE_NAME 為 default。

   7. 確認新的資料儲存庫 Pod 是否使用新的 SPC：

      export POD=NEW_DATASTORE_POD_NAME
      kubectl -n APIGEE_NAMESPACE get pods $POD -o jsonpath='{.spec.volumes[?(@.name=="apigee-external-secrets")].csi.volumeAttributes.secretProviderClass}'
      

      結果應與您在 rotation.yaml 中為 spec.cassandra.newSecretProviderClass 設定的值相符，例如：

      kubectl -n apigee get pods $POD -o jsonpath='{.spec.volumes[?(@.name=="apigee-external-secrets")].csi.volumeAttributes.secretProviderClass}'
      
      my-new-spc

   8. 等待機構和環境的發布作業完成，並已恢復執行狀態。

      kubectl -n APIGEE_NAMESPACE get apigeeorg ORG_NAME
      kubectl -n APIGEE_NAMESPACE get apigeeenv ENV_NAME

   9. 確認新的 MART、執行階段和同步器 Pod 是否使用新的 SPC：

      export POD=NEW_MART_POD_NAME
      kubectl -n APIGEE_NAMESPACE get pods $POD -o jsonpath='{.spec.volumes[?(@.name=="apigee-external-secrets")].csi.volumeAttributes.secretProviderClass}'
      export POD=NEW_RUNTIME_POD_NAME
      kubectl -n APIGEE_NAMESPACE get pods $POD -o jsonpath='{.spec.volumes[?(@.name=="apigee-external-secrets")].csi.volumeAttributes.secretProviderClass}'
      export POD=NEW_SYNCHRONIZER_POD_NAME
      kubectl -n APIGEE_NAMESPACE get pods $POD -o jsonpath='{.spec.volumes[?(@.name=="apigee-external-secrets")].csi.volumeAttributes.secretProviderClass}'
      

      結果應與您在 rotation.yaml 中為 spec.cassandra.newSecretProviderClass 設定的值相符，例如：

      kubectl -n apigee get pods $POD -o jsonpath='{.spec.volumes[?(@.name=="apigee-external-secrets")].csi.volumeAttributes.secretProviderClass}'
      
      my-new-spc

3. 完成每個區域的步驟後，請確認流量仍可正常傳送，然後按照下列兩個步驟清理第一個區域的程序：
   1. 在第一個區域中，更新 metadata.name 的值，並將 spec.cassandra.jobType 設為 CLEANUP。
   2. 套用檔案即可觸發清理工作。

      kubectl -n APIGEE_NAMESPACE apply -f rotation.yaml

   3. 請檢查工作狀態並查看工作記錄，確認清理工作何時完成。

   清除工作完成後，輪替程序就會結束。

4. 更新覆寫檔案，並將 cassandra.auth.secretProviderClass 設為新的密鑰提供者類別 (newSecretProviderClass)。

   cassandra:
     auth:
       secretProviderClass: NEW_SPC_NAME

5. 備份 Cassandra 資料庫。這項備份功能可確保旋轉後的憑證可進行還原。
6. 從 Vault 中刪除舊的 Cassandra 憑證、角色和政策。

復原旋轉

如果是多個區域，請在每個區域執行回溯作業。

1. 使用下列範本建立新的 SecretRotation 自訂資源：

   # rollback-rotation.yaml
   
   apiVersion: apigee.cloud.google.com/v1alpha1
   kind: SecretRotation
   metadata:
     name: ROLLBACK_NAME
     namespace: APIGEE_NAMESPACE
   spec:
     organizationId: APIGEE_ORG
     rotationId: ROTATION_ID # match the current rotation.
     timeoutMinutes: TIMEOUT_MINUTES # optional.
     precheck: false
     cassandra:
       oldSecretProviderClass: OLD_SPC_NAME # Must match the previous oldSecretProviderClass.
       newSecretProviderClass: NEW_SPC_NAME # Must match the previous newSecretProviderClass.
       jobType: ROLLBACK
   

   其中：

   • ROLLBACK_NAME：回溯作業的名稱，例如 sr-1-rollback。
   • APIGEE_NAMESPACE：您的 Apigee 命名空間。
   • APIGEE_ORG：您的 Apigee 機構組織 ID。
   • ROTATION_ID：您要回溯的目前輪替項目 ID，例如：rot-1。
   • TIMEOUT_MINUTES：選用。覆寫預設值 (480m == 8hr)。<=0 表示無限超時。
   • OLD_SPC_NAME：此值必須與您在單一區域設定或多區域設定程序中使用的輪替 YAML 檔案中 oldSecretProviderClass: 的機密名稱相符。
   • NEW_SPC_NAME：此值必須與您在單一地區設定或多地區設定程序中使用的輪替 YAML 檔案中 newSecretProviderClass: 的祕密名稱相符。
2. 套用復原：

   kubectl -n APIGEE_NAMESPACE apply -f ROLLBACK_YAML_FILE
   

3. 查看工作狀態，並等待工作完成。

   kubectl -n APIGEE_NAMESPACE describe sr ROTATION_NAME
   

4. 回溯作業完成後，請確認流量仍能正確流動。
5. 如果是多區域安裝，請在流量正常傳送後，在各個區域重複執行復原程序。
6. 完成回溯作業並確認所有區域仍可正常流量後，請開始清理程序。

   請在輪替 YAML 檔案中進行下列變更：

   • 將 metadata.name 變更為表示這是清理工作的名稱，例如 sr-1-cleanup-rollback。
   • 將 spec.cassandra.jobType 變更為 CLEANUP_ROLLBACK。
7. 套用檔案以觸發清理工作：

   kubectl -n APIGEE_NAMESPACE apply -f ROTATION_YAML_FILE
   

8. 查看工作狀態，並等待工作完成。

   kubectl -n APIGEE_NAMESPACE describe sr ROTATION_NAME
   

   清理工作完成後，還原程序就會完成。

9. 更新覆寫檔案，並將 cassandra.auth.secretProviderClass 設為舊的密鑰提供者類別 (oldSecretProviderClass)。

   cassandra:
     auth:
       secretProviderClass: OLD_SPC_NAME