將 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 入口網關做為入口層。

升級至 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 入口網關，且不再支援使用 Anthos 服務網格做為入口。如果您要升級的已安裝環境使用 Anthos 服務網格，則必須先遷移至使用 Apigee 入口網關，再升級至 1.9.4 版。

    Apigee 入口閘道會使用 Anthos 服務網格功能的一小部分，用於入口閘道。Apigee hybrid 會自動處理這些功能的管理和升級作業。因此，您不需要具備 Anthos 服務網格專業知識，即可安裝、升級及管理 Apigee 混合式入口網關。

    如需操作說明，請參閱 hybrid 1.8 版說明文件中的「遷移至 Apigee 入口網關」一節。

準備升級至 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 角色新增至混合式 v1.8 安裝，請確認 Apigee 執行階段服務的服務帳戶具有 Cloud Trace 代理程式 Google Cloud IAM 角色 (roles/cloudtrace.agent)。

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

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

  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 入口網關

自 1.9 版起，Apigee hybrid 不再支援使用 Anthos 服務網格進行入口。如果混合式安裝作業使用的是 Anthos 服務網格，則必須先將目前的安裝作業遷移至 Apigee 入口網關，才能安裝混合式 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 是入口部署作業的名稱。這個名稱可以是符合下列規定的任何名稱：
      • 長度上限為 17 個半形字元
      • 只能包含小寫英數字元、連字號 (-) 或「.」。
      • 開頭必須是英數字元
      • 結尾須為英數字元
      請參閱設定屬性參考資料中的 ingressGateways[].name。
    • REPLICAS_MIN 和 REPLICAS_MAX 分別是 Apigee 入口網關在安裝作業中的複本數量下限和上限。如需詳細資訊和預設設定，請參閱設定資源參考資料中的 ingressGateways[].replicaCountMin 和 ingressGateways[].replicaCountMax。
    • CPU_COUNT_REQ 和 MEMORY_REQ 是安裝環境中 Apigee 入口網關每個副本的 CPU 和記憶體要求。

      如需詳細資訊和預設設定，請參閱設定屬性參考資料中的 ingressGateways[].resources.requests.cpu 和 ingressGateways[].resources.requests.memory。

    • CPU_COUNT_LIMIT 和 MEMORY_LIMIT 是安裝環境中 Apigee 入口網關每個副本的 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 Ingress Gateway：
    $APIGEECTL_HOME/apigeectl apply -f overrides/overrides.yaml
  3. 公開 Apigee 輸入閘道。請按照「公開 Apigee 入口閘道」中的程序操作。
  4. 請呼叫 Proxy，測試新的入口網頁閘道。建議您測試目前已部署的所有重要 Proxy。
  5. 如要切換流量，請更新 DNS 記錄，讓其指向新的 Apigee 入口閘道 IP 位址。視 DNS 供應商而定，您可能可以逐步將流量轉移至新端點。提示： 您可以使用下列指令找出 Apigee 輸入閘道的外部 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. 監控資訊主頁，確保所有執行階段流量都能正常運作。只有在一切運作正常時，才能繼續進行下一個步驟。請確認沒有任何流量會透過舊的入口閘道 (Anthos 服務網格)，因為 DNS 快取可能會導致 DNS 更新傳播速度變慢。
  7. 如要停止 Apigee 向 Anthos 服務網格提供設定，請按照「管理 Apigee 入口閘道」指南中的「停止向 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」

請按照下列步驟安裝 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 入口元件。如果您有多個機構，請針對每個機構重複執行這項指令：
    $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 混合式命名空間。

    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