在 Hashicorp Vault 中輪替 Cassandra 憑證

總覽

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

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

  • 在 Hashicorp Vault 中輪換 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。
    • ：將 spec.rotationId 設為自訂 ID，例如 rotation-1-precheck。ROTATION_ID
    • 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. 在 APIGEE_NAMESPACE 命名空間中，為新的 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: -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。
      • ：將 spec.rotationId 設為自訂 ID，例如 rotation-1-precheck。ROTATION_ID
      • 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