在 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