診斷護欄問題

防護機制總覽

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 執行個體。
  • 如果測試失敗，Guardails 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

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

從 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: "12345_6789abcde"
    pullPolicy: Always

搭配 Guardrails 使用 Kubernetes 容錯

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

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

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

排解限制機制問題

環境變數檢查點遺失或空白

如果在 apigee 運算子 guradrails Pod 記錄檔中看到 Client.Timeout exceeded 錯誤，請嘗試下列疑難排解步驟，判斷問題是出在 Guardrails 端還是基礎架構端。

  1. 建立含有下列內容的新 YAML 檔案。您可以隨意命名 yaml 檔案。
    2.     apiVersion: v1
    kind: Pod
    metadata:
      labels:
      name: apigee-simple-client  
    spec:
      containers:
      - name: apigee-simple-client
        image: "gcr.io/apigee-release/hybrid/apigee-hybrid-cassandra-client:1.10.1"
        imagePullPolicy: Always
        command:
        - sleep
        - "3650d"
      restartPolicy: Never
      hostNetwork: false
  2. 使用下列指令套用新的 yaml 檔案：
    3.     kubectl apply -n apigee-system -f name of the yaml file
  3. 使用下列指令進入 Pod：
    4.     kubectl exec -it -n apigee-system apigee-simple-client -- /bin/bash
  4. 在 apigee-simple-client Pod 中執行下列指令，並檢查輸出內容：
    5.     curl -v -I --proxy http://forwarding-proxy.example.com:5678 \
      https://apigee.googleapis.com

    forwarding-proxy.example.com 是 Proxy 位址。您可以使用任何有權存取的 Proxy 位址。如果無法存取 Proxy，可以使用下列指令測試網路連線：

        curl -v -I https://apigee.googleapis.com

    如果 curl 指令成功連線至 HTTP Proxy 並連上 apigee.googleapis.com，curl 指令應會傳回 HTTP 回應碼。如果 curl 指令無法連上 Proxy，或無法透過 Proxy 連線至 apigee.googleapis.com，curl 指令應會顯示錯誤訊息。