診斷護欄問題

防護機制總覽

Apigee Hybrid Guardrails 是一種機制，可在潛在問題影響 Hybrid 執行個體前，向客戶發出警示。換句話說，如果指令會危及 Hybrid 執行個體的穩定性，Hybrid Guardrails 就會停止該指令。無論是設定有誤或資源不足，Hybrid Guardrails 都會禁止修改 Hybrid 執行個體，直到問題風險解除為止。這樣一來，顧客就不必花費數小時或數天解決問題。

搭配使用 Guardrails 與 Apigee Hybrid

如要使用 Hybrid Guardrails，請執行 Hybrid 安裝說明中記錄的相同 Hybrid Helm 安裝或 Hybrid Helm 升級指令。執行 Guardrails 時不需要其他指令。

當您發出 Apigee Hybrid 的 Helm 指令時，Helm 指令會先執行兩項作業，再將設定套用至 Hybrid 執行個體：

  • Helm 會使用您套用的設定，建立暫時的 Guardrails Pod。如果 Guardrails Pod 啟動至健康狀態，Pod 會根據您套用的設定測試混合執行個體。如果測試通過，Guardrails Pod 會終止，然後系統會將設定套用至 Apigee Hybrid 執行個體。
  • 如果測試失敗，Guardrails Pod 會處於不健康的狀態，方便您診斷 Pod。helm 指令會顯示錯誤訊息，指出 Guardrails Pod 失敗。

以下範例說明如何使用 Guardrails，在安裝 apigee-datastore 元件時，測試從 Hybrid 執行個體到 Apigee 控制平面的網路連線。您可以為所有 Apigee Hybrid 元件使用相同順序：

使用下列指令安裝 apigee-datastore 元件： 

helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace apigee \
  --atomic \
  -f overrides.yaml

如果發生立即錯誤，Helm 指令也會顯示錯誤訊息，指出 Guardrails 檢查失敗，如下列範例所示： 

 helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace apigee \
  -f my-overrides.yaml

  . . .
    Error: UPGRADE FAILED: pre-upgrade hooks failed: 1 error occurred:
      * pod apigee-hybrid-helm-guardrail-datastore failed

如要查看失敗的檢查項目和原因，請檢查 Guardrails Pod 記錄，如下列範例所示： 

kubectl logs -n apigee apigee-hybrid-helm-guardrail-datastore
{"level":"INFO","timestamp":"2024-02-01T20:28:55.934Z","msg":"logging enabled","log-level":"INFO"}
{"level":"INFO","timestamp":"2024-02-01T20:28:55.935Z","msg":"","checkpoint":"upgrade","component":"apigee-datastore"}
{"level":"INFO","timestamp":"2024-02-01T20:28:55.935Z","msg":"initiating pre-install checks"}
{"level":"INFO","timestamp":"2024-02-01T20:28:55.935Z","msg":"check validation starting...","check":"controlplane_connectivity"}
{"level":"ERROR","timestamp":"2024-02-01T20:28:55.961Z","msg":"connectivity test failed","check":"controlplane_connectivity","host":"https://apigee.googleapis.com","error":"Get \"https://apigee.googleapis.com\": dial tcp: lookup apigee.googleapis.com on 10.92.0.10:53: no such host"}

在本例中，實際的測試失敗訊息是這部分： 

{"level":"ERROR","timestamp":"2024-02-01T20:28:55.961Z","msg":"connectivity test failed","check":"controlplane_connectivity","host":"https://apigee.googleapis.com","error":"Get \"https://apigee.googleapis.com\": dial tcp: lookup apigee.googleapis.com on 10.92.0.10:53: no such host"}

發出 Helm 指令時，系統會自動佈建 Guardrails Pod。如果 Apigee 控制平面連線測試通過，Guardrails Pod 會在執行結束時終止。

發出 helm install 指令後，請立即檢查 Pod 的狀態。以下範例輸出內容顯示 Guardrail Pod 處於正常狀態，表示控制平面連線測試已通過：

kubectl get pods -n apigee -w
NAME                                      READY    STATUS             RESTARTS    AGE
apigee-hybrid-helm-guardrail-datastore    0/1      Pending            0           0s
apigee-hybrid-helm-guardrail-datastore    0/1      Pending            0           1s
apigee-hybrid-helm-guardrail-datastore    0/1      ContainerCreating  0           1s
apigee-hybrid-helm-guardrail-datastore    0/1      Completed          0           2s
apigee-hybrid-helm-guardrail-datastore    0/1      Completed          0           3s
apigee-hybrid-helm-guardrail-datastore    0/1      Terminating        0           3s
apigee-hybrid-helm-guardrail-datastore    0/1      Terminating        0           3s

如果 Apigee Control Plane 連線測試失敗，Guardrails Pod 會維持在「錯誤」狀態，類似於下列範例輸出內容： 

kubectl get pods -n apigee -w
NAME                                      READY    STATUS             RESTARTS    AGE
apigee-hybrid-helm-guardrail-datastore    0/1      Pending            0           0s
apigee-hybrid-helm-guardrail-datastore    0/1      Pending            0           0s
apigee-hybrid-helm-guardrail-datastore    0/1      ContainerCreating  0           0s
apigee-hybrid-helm-guardrail-datastore    0/1      Error              0           4s
apigee-hybrid-helm-guardrail-datastore    0/1      Error              0           5s
apigee-hybrid-helm-guardrail-datastore    0/1      Error              0           6s

暫時停用防護機制

如要停用 Guardrails 檢查，請在 Helm 指令中新增 --no-hooks 旗標。下列範例顯示 Helm 指令中的 --no-hooks 標記：

helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace apigee \
  -f overrides.yaml \
  --no-hooks

防護機制檢查

下表列出部分 Guardrails 檢查的詳細資料，這些檢查會隨附於 Apigee Hybrid 1.15 版。
名稱 Checkpoint 說明
cassandra_backup_enabled upgrade 推出版本：1.14.0

嚴重程度： error

這項檢查會要求您先啟用備份功能，才能升級。升級前請務必備份，以便在必要時還原為先前的版本。如要進一步瞭解可用的備份選項，請參閱「Cassandra 備份與復原」。
cassandra_recent_backup_csi upgrade 推出版本：1.14.0

嚴重程度： error

如果啟用 CSI 備份，升級前必須先檢查過去 24 小時內是否有備份。如果需要還原至先前的版本，這麼做可將資料遺失的風險降到最低。如要進一步瞭解 CSI 備份與還原，請參閱「CSI 備份」。

在覆寫檔案中設定防護機制

從 Apigee Hybrid 1.12 版開始，每個圖表都會預設設定 Guardrails。您可以在 overrides 檔案中覆寫圖片網址、標記和圖片提取政策。

舉例來說，以下 Guardrails 圖片網址、標記和提取政策會新增至覆寫檔案：

# Apigee Ingressgateway
ingressGateway:
  image:
    pullPolicy: Always

## NOTE: The Guardrails config is below. The ingressgateway config above is for position reference only and is NOT required for Guardrails config.

# Apigee Guardrails
guardrails:
  image:
    url: "gcr.io/ng-hybrid/guardrails/apigee-watcher"
    tag: "1.15.1"
    pullPolicy: Always

搭配 Guardrails 使用 Kubernetes 容許度

您也可以在 overrides 檔案中，為 Guardrails 新增容許度。如果 Guardrails overrides 設定中未定義任何容許度，Guardrails 會使用全域定義的容許度。

舉例來說，如要在 overrides 檔案的 Guardrails 區段中加入容許度，請新增類似下列詩節的內容：

  # Apigee Guardrails
  guardrails:
    image:
      url: "gcr.io/ng-hybrid/guardrails/apigee-watcher"
      tag: "1.15.1"
      pullPolicy: Always
    tolerations:
    - key: "say"
      operator: "Equal"
      value: "taunt"
      effect: "NoSchedule"