在 Hashicorp Vault 中輪替 Cassandra 憑證

總覽

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

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

  • 在 Hashicorp Vault 中輪替 Cassandra 憑證。
  • 如果密碼輪替期間發生任何問題，請在 Vault 中復原至先前的 Cassandra 憑證。
  • 一次只輪替一個區域的 Cassandra 密碼，確保對服務可用性的影響降到最低，並控管輪替程序。
  • 追蹤單一區域的輪替作業開始、進度和完成情況。

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

事前準備

設定憑證輪換前，請先完成下列事項：

  • 備份 Cassandra 資料庫。這項備份作業可確保能復原至輪替前的憑證。
  • 確認叢集狀態良好 (即所有 Apigee 資源都在運作中，沒有待處理的狀態變更)。

單一區域設定

  1. 在 Apigee 命名空間中建立新的 SecretProviderClass Kubernetes 資源，用於存放新的 Cassandra 憑證。如需可使用的範本，請參閱「在 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. 在 APIGEE_NAMESPACE 命名空間中，為新的 Cassandra 憑證建立新的 SecretProviderClass Kubernetes 資源。如需可使用的範本，請參閱「在 Hashicorp Vault 中儲存 Cassandra 密鑰」。這樣一來，Vault 角色就能存取 Kubernetes 命名空間中的 Secret。
    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 命名空間中建立新的 SecretProviderClass Kubernetes 資源，用於存放新的 Cassandra 憑證。如需可使用的範本，請參閱「在 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。確認新的 controller-manager 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 == 8 小時)。<=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 設為舊的 Secret Provider 類別 (oldSecretProviderClass)。
    cassandra:
  auth:
    secretProviderClass: OLD_SPC_NAME