將 Apigee Hybrid 升級至 1.9 版

本程序涵蓋從 Apigee Hybrid 1.8.x 版升級至 Apigee Hybrid 1.9.4 版，以及從先前的 Hybrid 1.9.x 版升級至 1.9.4 版。

次要版本升級 (例如從 1.8 版升級至 1.9 版) 和修補程式版本升級 (例如從 1.9.0 版升級至 1.9.4 版) 均使用相同程序。

如果您要從 Apigee Hybrid 1.7 以下版本升級，請先升級至 Hybrid 1.8 版，再升級至 1.9.4 版。請參閱將 Apigee Hybrid 升級至 1.8 版的說明。

自 1.9.0 版起，Apigee Hybrid 只支援 Apigee Ingress 閘道做為 Ingress 層。

升級至 1.9.4 版總覽

升級 Apigee Hybrid 的程序分為下列幾節：

  1. 準備升級。
  2. 安裝混合式執行階段 1.9.4 版。

必要條件

  • 這些升級說明假設您已安裝 Apigee Hybrid 1.8.x 版，並想升級至 1.9.4 版。如要從舊版更新，請參閱升級 Apigee Hybrid 至 1.8 版的操作說明。
  • 在 Apigee Hybrid 1.8 版中，我們推出了 Apigee Ingress 閘道，做為 Anthos 服務網格的替代 Ingress 層。自 1.9.0 版起，Apigee Hybrid 必須使用 Apigee Ingress 閘道，不再支援使用 Anthos 服務網格進行 Ingress。如果升級前安裝的服務使用 Anthos 服務網格，您必須先遷移至使用 Apigee Ingress 閘道，才能升級至 1.9.4 版。

    Apigee 進入閘道會使用一小部分的 Anthos 服務網格功能做為進入閘道。 Apigee Hybrid 會自動管理及升級這些功能。 因此，您不需要具備 Anthos 服務網格專業知識，即可安裝、升級及管理 Apigee Hybrid Ingress 閘道。

    如需操作說明，請參閱 Hybrid 1.8 說明文件中的「遷移至 Apigee Ingress 閘道」。

準備升級至 1.9 版

  1. 這些操作說明會使用環境變數 APIGEECTL_HOME，代表您在檔案系統中安裝 apigeectl 的目錄。如有需要，請將目錄變更為 apigeectl 目錄，並使用下列指令定義變數：

    Linux 

    export APIGEECTL_HOME=$PWD
echo $APIGEECTL_HOME

    Mac OS 

    export APIGEECTL_HOME=$PWD
echo $APIGEECTL_HOME

    Windows 

    set APIGEECTL_HOME=%CD%
echo %APIGEECTL_HOME%
  2. 建立 1.8 版 $APIGEECTL_HOME/ 目錄的備份副本。例如： 
    tar -czvf $APIGEECTL_HOME/../apigeectl-v1.8-backup.tar.gz $APIGEECTL_HOME
  3. 按照「Cassandra 備份與復原」一文中的說明，備份 Cassandra 資料庫。

將「Cloud Trace 代理人」角色新增至 Apigee 執行階段的服務帳戶。(選填)

選用步驟：如果您打算使用 Cloud Trace，且尚未將 Cloud Trace Agent 角色新增至混合式 1.8 安裝作業，請確保 Apigee 執行階段服務的服務帳戶具有 Cloud Trace 代理者 Google Cloud IAM 角色 (roles/cloudtrace.agent)。

在實際工作環境中，執行階段服務帳戶為 apigee-runtime。對於非正式環境，執行階段服務帳戶為 apigee-non-prod。

您可以在 Cloud 控制台 > IAM 與管理 > 服務帳戶使用者介面中新增角色，也可以使用下列指令：

  1. 使用下列指令取得服務帳戶的電子郵件地址：

    正式版 

    gcloud iam service-accounts list --filter "apigee-runtime"

    如果電子郵件地址符合 apigee-runtime@$ORG_NAME.iam.gserviceaccount.com 模式，您可以在下一個步驟中使用該模式。

    非正式環境 

    gcloud iam service-accounts list --filter "apigee-non-prod"

    如果符合 apigee-non-prod@$ORG_NAME.iam.gserviceaccount.com 模式，您可以在下一個步驟中使用該模式。
  2. 將 Cloud Trace 代理者角色指派給服務帳戶：

    正式版 

    gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:apigee-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

    非正式環境 

    gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

    範例 

    gcloud projects add-iam-policy-binding hybrid-example-project \
    --member="serviceAccount:apigee-runtime@hybrid-example-project.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

    其中：$PROJECT_ID 是安裝 Apigee Hybrid 的 Google Cloud 專案名稱。

如果安裝作業使用 Anthos 服務網格，請安裝 Apigee Ingress 閘道

自 1.9 版起，Apigee Hybrid 不再支援使用 Anthos 服務網格進行 Ingress。如果混合式安裝作業使用 Anthos 服務網格，您必須先將目前的安裝作業遷移至 Apigee Ingress 閘道，才能安裝 1.9 版混合式安裝作業。

  1. 將 ingressGateways 屬性新增至覆寫檔案。

    語法

      ingressGateways:
  - name: INGRESS_NAME
    replicaCountMin: REPLICAS_MIN
    replicaCountMax: REPLICAS_MAX
    resources:
      requests:
        cpu: CPU_COUNT_REQ
        memory: MEMORY_REQ
      limits:
        cpu: CPU_COUNT_LIMIT
        memory: MEMORY_LIMIT
    svcAnnotations:  # optional.
      SVC_ANNOTATIONS_KEY: SVC_ANNOTATIONS_VALUE
    svcLoadBalancerIP: SVC_LOAD_BALANCER_IP # optional

    範例

      ingressGateways:
  - name: prod1
    replicaCountMin: 2
    replicaCountMax: 100
    resources:
      requests:
        cpu: 1
        memory: 1Gi
      limits:
        cpu: 2
        memory: 2Gi
    svcAnnotations:  # optional. See Known issue 243599452.
      networking.gke.io/load-balancer-type: "Internal"
    svcLoadBalancerIP: 198.252.0.123
    • INGRESS_NAME 是 Ingress 部署作業的名稱。只要符合下列規定，任何名稱都可以：
      • 長度上限為 17 個半形字元
      • 只能包含小寫英數字元、「-」或「.」
      • 開頭為英數字元
      • 結尾為英數字元
      請參閱「設定屬性參考資料」中的 ingressGateways[].name。
    • REPLICAS_MIN 和 REPLICAS_MAX 是安裝中 Apigee Ingress 閘道的副本數量下限和上限。如需更多資訊和預設設定，請參閱「設定屬性參考資料」中的 ingressGateways[].replicaCountMin 和 ingressGateways[].replicaCountMax。
    • CPU_COUNT_REQ 和 MEMORY_REQ 是安裝中每個 Apigee Ingress 閘道副本的 CPU 和記憶體要求。

      如要瞭解詳情和預設設定，請參閱「設定屬性參考資料」中的 ingressGateways[].resources.requests.cpu 和 ingressGateways[].resources.requests.memory。

    • CPU_COUNT_LIMIT 和 MEMORY_LIMIT：安裝中每個 Apigee Ingress 閘道副本的 CPU 和記憶體上限。

      如需更多資訊和預設設定，請參閱「設定屬性參考資料」中的 ingressGateways[].resources.limits.cpu 和 ingressGateways[].resources.limits.memory。

    • SVC_ANNOTATIONS_KEY SVC_ANNOTATIONS_VALUE (選用)： 。

      這是鍵/值組合，可為預設 Ingress 服務提供註解。雲端平台會使用註解來協助設定混合式安裝作業，例如將負載平衡器類型設為內部或外部。例如： 

      ingressGateways:
    svcAnnotations:
      networking.gke.io/load-balancer-type: "Internal"

      註解會因平台而異。如需必要和建議的註解，請參閱平台說明文件。

      請參閱「設定屬性參考資料」中的 ingressGateways[].svcAnnotations。
    • SVC_LOAD_BALANCER_IP (選用) 可為負載平衡器指派靜態 IP 位址。在支援指定負載平衡器 IP 位址的平台上，系統會使用這個 IP 位址建立負載平衡器。在不允許指定負載平衡器 IP 位址的平台上，系統會忽略這項屬性。

      如果沒有為負載平衡器分配靜態 IP 位址，請將這個屬性從覆寫檔案中排除。

      請參閱「設定屬性參考資料」中的 ingressGateways[].svcLoadBalancerIP。
  2. 執行下列指令，套用變更來安裝 Apigee 輸入閘道： 
    $APIGEECTL_HOME/apigeectl apply -f overrides/overrides.yaml
  3. 公開 Apigee 輸入閘道。按照「公開 Apigee Ingress 閘道」中的程序操作。
  4. 呼叫 Proxy，測試新的 Ingress 閘道。最好測試目前部署的所有重要 Proxy。
  5. 如要切換流量，請更新 DNS 記錄，使其指向新 Apigee Ingress Gateway 的 IP 位址。 視 DNS 供應商而定，您或許可以逐步將流量轉移至新端點。 提示： 您可以使用下列指令，找出 Apigee Ingress 閘道的外部 IP 位址： 
    kubectl get svc -n apigee -l app=apigee-ingressgateway

    輸出內容應如下所示： 

    NAME                                        TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)                                      AGE
apigee-ingressgateway-prod-hybrid-37a39bd   LoadBalancer   192.0.2.123   233.252.0.123   15021:32049/TCP,80:31624/TCP,443:30723/TCP   16h
  6. 請監控資訊主頁，確保所有執行階段流量都能正常運作。如果一切正常，請繼續下一個步驟。請確認沒有任何流量通過舊的 Ingress 閘道 (Anthos 服務網格)，因為 DNS 記錄更新可能需要一段時間才能傳播，這是 DNS 快取所致。
  7. 如要停止讓 Apigee 為 Anthos 服務網格提供設定，請按照「管理 Apigee Ingress 閘道」指南中的「停止為 ASM 提供設定」一節步驟操作。
  8. 重新測試及監控 API Proxy 流量。
  9. 按照 Anthos 服務網格說明文件的指示，從叢集解除安裝 Anthos 服務網格。

安裝 Hybrid 1.9.4 執行階段

  1. 請確認您位於混合式基本目錄 (apigeectl 可執行檔所在目錄的父項)： 
    cd $APIGEECTL_HOME/..

  2. 使用下列指令，下載適用於您作業系統的版本套件。 請務必在下表中選取您的平台：

    Linux

    Linux 64 位元：

    curl -LO \
  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.9.4/apigeectl_linux_64.tar.gz

    Mac OS

    Mac 64 位元：

    curl -LO \
  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.9.4/apigeectl_mac_64.tar.gz

    Windows

    Windows 64 位元：

    curl -LO ^
  https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.9.4/apigeectl_windows_64.zip
  3. 將目前的 apigeectl/ 目錄重新命名為備份目錄名稱。例如：

    Linux 

    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.8/

    Mac OS 

    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.8/

    Windows 

    rename %APIGEECTL_HOME% %APIGEECTL_HOME%-v1.8

  4. 將下載的 gzip 檔案內容解壓縮至混合式基本目錄。 混合式基礎目錄是重新命名的 apigeectl-v1.8 目錄所在位置：

    Linux 

    tar xvzf filename.tar.gz -C ./

    Mac OS 

    tar xvzf filename.tar.gz -C ./

    Windows 

    tar xvzf filename.zip -C ./

  5. 根據預設，tar 內容會展開至目錄中，且目錄名稱會包含版本和平台。例如：./apigeectl_1.9.4-xxxxxxx_linux_64。使用下列指令將該目錄重新命名為 apigeectl：

    Linux 

    mv apigeectl_1.9.4-xxxxxxx_linux_64 apigeectl

    Mac OS 

    mv apigeectl_1.9.4-xxxxxxx_mac_64 apigeectl

    Windows 

    rename apigeectl_1.9.4-xxxxxxx_windows_64 apigeectl
  6. 切換至 apigeectl 目錄： 
    cd ./apigeectl

    這個目錄是 apigeectl 主目錄。這是 apigeectl 可執行指令所在的位置。

  7. 這些操作說明會使用環境變數 $APIGEECTL_HOME，代表檔案系統中安裝 apigeectl 公用程式的目錄。如有需要，請將目錄變更為 apigeectl 目錄，並使用下列指令定義變數：

    Linux 

    export APIGEECTL_HOME=$PWD
     
    echo $APIGEECTL_HOME

    Mac OS 

    export APIGEECTL_HOME=$PWD
     
    echo $APIGEECTL_HOME

    Windows 

    set APIGEECTL_HOME=%CD%
     
    echo %APIGEECTL_HOME%
  8. 使用 version 指令驗證 apigeectl 版本： 
    ./apigeectl version
     
    Version: 1.9.4
  9. 移至 hybrid-base-directory/hybrid-files 目錄。hybrid-files 目錄包含覆寫檔案、憑證和服務帳戶等設定檔。例如： 
    cd $APIGEECTL_HOME/../hybrid-files
  10. 使用下列指令，確認 kubectl 已設為正確的環境。 目前的環境應設為要升級 Apigee Hybrid 的叢集。 
    kubectl config get-contexts | grep \*
  11. 在 hybrid-files 目錄中：
    1. 將下列符號連結更新為 $APIGEECTL_HOME。這些連結可讓您從 hybrid-files 目錄內執行新安裝的 apigeectl 指令： 
      ln -nfs $APIGEECTL_HOME/tools tools
ln -nfs $APIGEECTL_HOME/config config
ln -nfs $APIGEECTL_HOME/templates templates
ln -nfs $APIGEECTL_HOME/plugins plugins
    2. 如要確認符號連結是否建立正確，請執行下列指令，並確認連結路徑指向正確位置：
      ls -l | grep ^l
  12. 執行模擬初始化作業，檢查是否有錯誤： 
    ${APIGEECTL_HOME}/apigeectl init -f OVERRIDES_FILE --dry-run=client

    其中 OVERRIDES_FILE 是覆寫檔案的名稱，例如 ./overrides/overrides.yaml。

  13. 如果沒有任何錯誤，請初始化 Hybrid 1.9.4： 
    $APIGEECTL_HOME/apigeectl init -f OVERRIDES_FILE
  14. 檢查初始化狀態： 
    $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

    成功之後，輸出內容會顯示：All containers ready. 

    kubectl describe apigeeds -n apigee

    在輸出內容中，尋找 State: running。

  15. 使用 --dry-run 旗標執行 apply 指令的模擬測試，檢查是否有錯誤：
    $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --dry-run=client
  16. 如果沒有錯誤，請套用覆寫。請根據安裝環境，選取並按照正式環境或非正式環境的操作說明進行。

    正式環境

    在正式環境中，請個別升級每個混合式元件，並在升級下一個元件前，檢查升級元件的狀態。

    1. 請確認您位於 hybrid-files 目錄。
    2. 套用覆寫項目來升級 Cassandra： 
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --datastore
    3. 檢查完成： 
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

      只有在 Pod 準備就緒時，才繼續執行下一個步驟。

    4. 套用覆寫項目來升級遙測元件，並檢查是否完成： 
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --telemetry
       
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE
    5. 啟動 Redis 元件： 
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --redis
    6. 套用覆寫項目，升級機構層級元件 (MART、Watcher 和 Apigee Connect)，並檢查是否完成：
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --org
       
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE
    7. 套用覆寫內容來升級環境。你有兩種選擇：
      • 逐一環境：一次對一個環境套用覆寫，並檢查完成情況。針對每個環境重複這個步驟：
        $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --env ENV_NAME
         
        $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

        其中 ENV_NAME 是要升級的環境名稱。

      • 一次套用至所有環境：一次將覆寫值套用至所有環境，並檢查完成情況： 
        $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --all-envs
         
        $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE
    8. 套用覆寫項目來升級 virtualhosts 元件，並檢查是否完成： 
      $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE --settings virtualhosts
       
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

    非正式環境

    在大多數非正式環境、示範環境或實驗環境中，您可以一次將覆寫套用至所有元件。如果非正式環境規模龐大且複雜，或與正式環境非常相似，建議您按照升級正式環境的指示操作。

    1. 請確認您位於 hybrid-files 目錄。
    2. $APIGEECTL_HOME/apigeectl apply -f OVERRIDES_FILE
    3. 查看狀態： 
      $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE

安裝「1.9.4-hotfix.1」

請按照下列步驟安裝 Hotfix 版本 1.9.4-hotfix.1：

  1. 執行這些步驟前，請務必使用 Apigee Hybrid 1.9.4 以上版本。如果不是 1.9.4 以上版本，請先升級至 1.9.4，再繼續操作。
  2. 開啟 overrides.yaml 檔案。
  3. 在 istiod 節中，將映像檔標記的版本 (如有) 變更為 1.17.7 版。例如： 
    istiod:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-istiod"
    tag: "1.17.7-asm.0-distroless"
  4. 視您選擇安裝 Apigee Hybrid 的方式而定，您可能會有 ingressGateway 或 ingressGateways 節。 找出覆寫檔案中顯示的節，並將圖片標記版本 (如有) 變更為 1.17.7 版。舉例來說，如果有一個 ingressGateway 節： 
    ingressGateway:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
    tag: "1.17.7-asm.0-distroless"

    或者，如果您有 ingressGateways 節：

    ingressGateways:
  - name: gateway1
    image:
      url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
      tag: "1.17.7-asm.0-distroless"
    ...
  - name: gateway2
    image:
      url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
      tag: "1.17.7-asm.0-distroless"
    ...
  5. 儲存檔案。
  6. 執行下列指令，初始化 istiod 元件： 
    $APIGEECTL_HOME/apigeectl init -f OVERRIDES_FILE
     
    $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE
  7. 執行下列指令，將變更套用至 Apigee Ingress 元件。如果您有多個機構，請為每個機構重複執行這項指令： 
    $APIGEECTL_HOME/apigeectl apply --org -f OVERRIDES_FILE
     
    $APIGEECTL_HOME/apigeectl check-ready -f OVERRIDES_FILE
  8. 確認 Pod 的狀態： 
    kubectl get pods -n YOUR_APIGEE_NAMESPACE

升級 Kubernetes 版本

將 Kubernetes 平台升級至 Hybrid 1.9 支援的版本。 如需協助，請參閱相關平台的說明文件。

復原升級作業

如要復原先前的升級，請按照下列步驟操作：

  1. 清除混合式執行階段命名空間中已完成的工作，其中 NAMESPACE 是您在覆寫檔案中指定的命名空間 (如有指定)。否則預設命名空間為 apigee：
    kubectl delete job -n NAMESPACE \
  $(kubectl get job -n NAMESPACE \
  -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')
  2. 清除 apigee-system 命名空間中已完成的工作： 
    kubectl delete job -n apigee-system \
  $(kubectl get job -n apigee-system \
  -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')
  3. 變更 APIGEECTL_HOME 變數，指向包含舊版 apigeectl 的目錄。例如： 
    export APIGEECTL_HOME=PATH_TO_PREVIOUS_APIGEECTL_DIRECTORY
  4. 在要還原的安裝根目錄中，執行 apigeectl apply，檢查 Pod 的狀態，然後執行 apigeectl init。請務必使用要復原版本適用的原始覆寫檔案：
    1. 在 hybrid-files 目錄中，執行 apigeectl apply： 
      $APIGEECTL_HOME/apigeectl apply -f ORIGINAL_OVERRIDES_FILE

      其中 ORIGINAL_OVERRIDES_FILE 是舊版混合式安裝的覆寫檔案相對路徑和檔案名稱，例如 ./overrides/overrides1.8.yaml。

    2. 檢查 Pod 的狀態： 
      kubectl -n NAMESPACE get pods

      其中 NAMESPACE 是 Apigee Hybrid 命名空間。

    3. 檢查 apigeeds 的狀態： 
      kubectl describe apigeeds -n apigee

      輸出內容應如下所示： 

      Status:
  Cassandra Data Replication:
  Cassandra Pod Ips:
    10.8.2.204
  Cassandra Ready Replicas:  1
  Components:
    Cassandra:
      Last Successfully Released Version:
        Revision:  v1-f8aa9a82b9f69613
        Version:   v1
      Replicas:
        Available:  1
        Ready:      1
        Total:      1
        Updated:    1
      State:        running
  Scaling:
    In Progress:         false
    Operation:
    Requested Replicas:  0
  State:                 running

      只有在 apigeeds Pod 執行時，才能繼續下一個步驟。

    4. 執行下列指令，記下升級後訊息處理器的全新副本計數值。如果這些值與您先前設定的值不符，請變更覆寫檔案中的值，使其與先前的設定相符。 
      apigeectl apply -f ORIGINAL_OVERRIDES_FILE --dry-run=client --print-yaml --env ENV_NAME 2>/dev/null |grep "runtime:" -A 25 -B 1| grep "autoScaler" -A 2

      輸出內容應如下所示： 

            autoScaler:
        minReplicas: 2
        maxReplicas: 10
    5. 執行 apigeectl init： 
      $APIGEECTL_HOME/apigeectl init -f ORIGINAL_OVERRIDES_FILE