將 Apigee Hybrid 升級至 1.3.6 版

如果您要從 Apigee hybrid 1.0 或 1.1 版本升級，請先升級至 hybrid 1.2 版，再升級至 1.3.6 版。請參閱將 Apigee Hybrid 升級至 1.2 版的操作說明。

升級至 1.3.6 版總覽。

升級 Apigee Hybrid 的程序分為以下幾個部分：

1. 準備
1. 建立及更新服務帳戶。
2. 規劃環境群組。
3. 複製及更新覆寫檔案。
2. 升級 Istio 和 cert-manager。
3. 安裝 Hybrid 執行階段 1.3 版。
4. 清除所用資源。

必修課

• Apigee Hybrid 1.2 版。如果您要從舊版更新，請參閱「將 Apigee Hybrid 升級至 1.2 版」一文的操作說明。

準備作業

1. (建議) 備份 1.2 版 $APIGEECTL_HOME/ 目錄。例如：

   tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME

2. (建議) 按照「Cassandra 備份與復原」一文中的指示備份 Cassandra 資料庫
3. 請按照下列步驟升級 Kubernetes 平台。如需協助，請按照平台的說明文件操作：

   平台	升級至版本
   GKE	1.15.x
   Anthos	1.5
   AKS	1.16.x 使用 Anthos 附加叢集

4. 如果您未在混合式安裝作業中使用 Apigee Connect，請啟用 Apigee Connect。
   1. 檢查是否已啟用 Apigee Connect API：

      gcloud services list | grep apigeeconnect
      
      apigeeconnect.googleapis.com         Apigee Connect API

   2. 如果沒有，請啟用 API：

      gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID

      其中，$PROJECT_ID 是您的 Google Cloud 專案 ID。

   3. 在指令列中取得 gcloud 驗證憑證，如以下範例所示：

      TOKEN=$(gcloud auth print-access-token)

      如要確認權杖是否已填入，請使用 echo，如以下範例所示：

      echo $TOKEN

      權杖應會以編碼字串的形式顯示。

      如需詳細資訊，請參閱 gcloud 指令列工具總覽。

   4. 確認貴機構是否已啟用 Apigee Connect：

      curl -H "Authorization: Bearer $TOKEN" \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

      其中 $ORG_NAME 是機構 ID。

      如果輸出內容包含：

            "name" : "features.mart.connect.enabled",
            "value" : "true"

      已啟用 Apigee Connect。

   5. 如果未啟用 Apigee Connect，請將 Apigee Connect 代理程式角色指派給 MART 服務帳戶：

      gcloud projects add-iam-policy-binding $PROJECT_ID \
        --member serviceAccount:apigee-mart@$PROJECT_ID.iam.gserviceaccount.com \
        --role roles/apigeeconnect.Agent

   6. 使用下列指令啟用 Apigee Connect：

      curl -H "Authorization: Bearer $TOKEN" -X PUT \
        -H "Content-Type: application/json" \
        -d '{
          "name" : "'"$ORG_NAME"'",
          "properties" : {
            "property" : [ {
              "name" : "features.hybrid.enabled",
              "value" : "true"
            }, {
              "name" : "features.mart.connect.enabled",
              "value" : "true"
            } ]
          }
        }' \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"
      

      如果輸出內容包含下列兩個屬性，表示已成功啟用 Apigee Connect：

            {
              "name": "features.mart.connect.enabled",
              "value": "true"
            },
            {
              "name": "features.hybrid.enabled",
              "value": "true"
            }
      

5. 建立 apigee-watcher 服務帳戶。Apigee Watcher 是 v1.3 中推出的新服務帳戶。它會監控組織層級變更的同步器，並套用這些變更來設定 Istio 入口。

   從主要混合式目錄：

   ./tools/create-service-account apigee-watcher ./service-accounts

6. 將 Apigee 執行階段代理人角色指派給 Watcher 服務帳戶：

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member serviceAccount:apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com \
     --role roles/apigee.runtimeAgent

   其中 PROJECT_ID 是您的 Google Cloud 專案 ID。如果您的服務帳戶電子郵件地址與此模式不同，請據此進行替換。

   輸出內容應包含所有服務帳戶及其角色的清單，包括：

     ...
   - members:
     - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
     role: roles/apigee.runtimeAgent
     ...

7. 規劃用於路由的環境群組。 Apigee hybrid 1.3 會使用環境群組管理基本路徑路由，而非 routingRules。如果您在混合型配置中使用 routingRules，請設計環境群組來複製路由。

   您必須建立至少一個環境群組。

   請參閱「關於環境群組」。

   按一下這裡查看使用環境群組取代 routingRules 的範例

   在這個範例中，overrides.yaml 檔案中的以下 routingRules 會將要求路由至 foo 和 bar API 代理程式，並將 foo-test 代理程式路由至 test-env 環境：

   virtualhosts:
     - name: default
       hostAliases:
         - "*.acme.com"
       sslCertPath: ./certs/keystore.pem
       sslKeyPath: ./certs/keystore.key
       routingRules:
         - paths:
           - /foo
           - /bar
         - env: prod-env-1
         - paths:
           - foo-test
         -env: test-env

   如要在 Hybrid 1.3.6 版本中複製此功能，請按照下列步驟操作：

   1. 將 foo 和 bar Proxy 部署至 prod-env-1 環境。
   2. 將 foo-test 和 bar Proxy 部署至 test-env 環境。
   3. 建立環境群組，並為 Proxy 建立主機別名，例如 api.acme.com。。
   4. 將 overrides.yaml 中的 virtualhosts 節修訂為
      • 將 virtualhosts:name 替換為環境群組名稱。
      • 移除 virtualhosts:routingRules。

      例如：

      virtualhosts:
        - name: default # environment group name
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key

8. 更新覆寫檔案：
1. 複製覆寫檔案。
2. 更新 gcp 和 k8sCluster 節。

   下列設定屬性已在混合型 1.3 版中取代：

   • gcpRegion 已替換為 gcp:region
   • gcpProjectID 已替換為 gcp:projectID
   • gcpProjectIDRuntime 已替換為 gcp:gcpProjectIDRuntime
   • k8sClusterName 已替換為 k8s:clusterName
   • k8sClusterRegion 已替換為 k8s:clusterRegion

   例如，取代下列結構：

   gcpRegion: gcp region
   gcpProjectID: gcp project ID
   gcpProjectIDRuntime: gcp project ID
   
   k8sClusterName: name
   k8sClusterRegion: region

   with:

   gcp:
    projectID: gcp project ID
    region: gcp region
    gcpProjectIDRuntime: gcp project ID # optional. This is only required if you
                                          # want logger/metrics data to be sent in
                                          # different gcp project.
   
   k8sCluster:
    name: gcp project ID
    region: gcp region
   

3. 如果覆寫檔案中沒有不重複的例項 ID，請新增一個：

   # unique identifier for this installation. 63 chars length limit
   instanceID: ID

   其中 ID 是這類混合式安裝作業的專屬 ID，例如「my-hybrid-131-installation」或「acmecorp-hybrid-131」。

4. 將 Watcher (apigee-watcher) 服務帳戶新增至覆寫檔案：

   # Note: the SA should have the "Apigee Runtime Agent" role
   watcher:
    serviceAccountPath: "service account file"

5. 將指標 (apigee-metrics) 服務帳戶新增至覆寫檔案：

   metrics:
    serviceAccountPath: "service account file"

6. 更新 virtualhosts: 節，將 routingRules 替換為環境群組。
   1. -name: 請將名稱替換為環境群組的名稱。您可以有多個名稱項目，每個環境群組一個。
   2. hostAliases:[] 刪除這行。
   3. 保留 (或新增) sslCertPath: 和 sslKeyPath: 項目。
   4. 刪除所有 routingRules 項目。

   例如：

   virtualhosts:
     - name: default
       hostAliases:
         - "*.acme.com"
       sslCertPath: ./certs/keystore.pem
       sslKeyPath: ./certs/keystore.key
       routingRules:
         - paths:
           - /foo
           - /bar
         - env: my-environment

   變成：

   virtualhosts:
     - name: example-env-group
       sslCertPath: ./certs/keystore.pem
       sslKeyPath: ./certs/keystore.key

7. 更新 mart 和 connectAgent: 節。
   1. 在 mart: 下方移除 hostAlias:、sslCertPath: 和 sslKeyPath: 項目。
   2. 新增 connectAgent: 節。
   3. 在 connectAgent: 下方新增 serviceAccountPath: 項目，並提供服務帳戶檔案的路徑，該檔案已指派 Apigee Connect Agent 角色 (通常是 MART 服務帳戶)。

   例如：

   mart:
     hostAlias: "mart.apigee-hybrid-docs.net"
     serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
     sslCertPath: ./certs/fullchain.pem
     sslKeyPath: ./certs/privkey.key

   變成：

   mart:
     serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
   
   connectAgent:
     serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json

升級 Istio 和 cert-manager

Apigee hybrid 1.3 版需要使用 cert-manager v0.14.2 來管理及驗證憑證，並使用 Anthos 服務網格 (ASM) 1.5.7 以上版本提供的 Istio 發行版本來建立及管理執行階段入口網關。

將 Istio 1.4.6 升級至 ASM 1.5.7 (或更新版本)

1. 為盡量減少停機時間，Istio 部署和 HPA 每個都必須至少有兩個副本。執行下列指令，判斷複本數量：

   kubectl -n istio-system get deployments # list of deployments
   kubectl -n istio-system get hpa # list of hpa

2. 編輯僅有一個複本的每個部署，並將 replicas: 增加至 2 以上：

   kubectl -n istio-system edit deployment name

   例如：

   spec:
     progressDeadlineSeconds: 600
     replicas: 2

3. 編輯僅有一個複本的每個 HPA，並將 minReplicas: 增加至 2 以上：

   kubectl -n istio-system edit hpa name

   例如：

   spec:
     maxReplicas: 5
     minReplicas: 2
   

4. 按照「下載及安裝 ASM」一文中的安裝說明，下載並安裝 ASM。
5. 安裝完成後，請執行版本指令，確認已正確安裝 1.5.x：

   ./bin/istioctl version
   
   client version: 1.5.8-asm.0
   apigee-mart-ingressgateway version:
   citadel version: 1.4.6
   galley version: 1.4.6
   ingressgateway version: 1.5.8-asm.0
   pilot version: 1.4.6
   policy version: 1.4.6
   sidecar-injector version: 1.4.6
   telemetry version: 1.4.6
   pilot version: 1.5.8-asm.0
   data plane version: 1.4.6 (1 proxies), 1.5.8-asm.0 (2 proxies)

升級 cert-manager

1. 刪除目前的 cert-manager 部署：

   kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook

2. 確認您的 Kubernetes 版本：

   kubectl version

3. 執行下列指令，從 Jetstack 安裝 cert-manager：

   kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml 

安裝 Hybrid 執行階段

1. 將最新版本號碼儲存在變數中：

   export VERSION=$(curl -s \
       https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)

2. 檢查變數是否已填入版本號碼。如果您想使用其他版本，可以改為將該版本儲存在環境變數中。例如：

   echo $VERSION
     1.3.6

3. 下載適用於您作業系統的版本套件：

   Mac 64 位元：

   curl -LO \
       https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_64.tar.gz

   Linux 64 位元：

   curl -LO \
       https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_64.tar.gz

   Mac 32 位元：

   curl -LO \
       https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_32.tar.gz

   Linux 32 位元：

   curl -LO \
       https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz

4. 將目前的 apigeectl/ 目錄重新命名為備份目錄名稱。例如：

   mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 

5. 將下載的 gzip 檔案內容解壓縮至混合式基礎目錄。例如：

   tar xvzf filename.tar.gz -C hybrid-base-directory

6. cd 至基礎目錄。

7. 根據預設，tar 內容會解壓縮為名稱中含有版本和平台的目錄。例如：./apigeectl_1.0.0-f7b96a8_linux_64。將該目錄重新命名為 apigeectl：

   mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl

8. 從 apigee-system 中刪除 apigee-resources-install 工作：

   kubectl -n apigee-system delete job apigee-resources-install

9. 刪除舊版 CRD：

   kubectl delete crd apigeetelemetries.apigee.cloud.google.com

10. 使用 externalSeedHost 屬性更新覆寫檔案中的 cassandra: 節。這個屬性有助於確保新安裝的混合式 1.3.6 版本會使用與 1.2 版本相同的 Kubernetes 叢集。這是從混合型 1.2 版升級至 1.3.6 以上版本 (或更高版本) 時必須採取的一次性步驟。
    1. 在您要升級 1.2.0 安裝版本的相同 Kubernetes 叢集中，找出現有 Cassandra 的其中一個 IP 位址。

       kubectl -n namespace get pods -o wide

       其中 namespace 是 Apigee 混合式命名空間。

       記下 Cassandra 節點的 IP 位址。例如：

       kubectl -n apigee get pods -o wide
       NAME                  READY   STATUS    RESTARTS   AGE   IP          NODE
       apigee-cassandra-0    1/1     Running   0          33d   10.68.8.24   gke-example-cluster-rc5-apigee-data-c8bf1234-09kc
       apigee-cassandra-1    1/1     Running   0          16d   10.68.8.33   gke-example-cluster-rc5-apigee-data-c9221ee7-10kc
       apigee-cassandra-2    1/1     Running   0          23h   10.68.9.11   gke-example-cluster-rc5-apigee-data-d123e456-11kc

    2. 新增 externalSeedHost 屬性的值：

       cassandra:
        externalSeedHost: Cassandra_node_IP

       其中 Cassandra_node_IP 是 Cassandra 節點的 IP (前述範例中的 10.68.8.24)。

11. 在新 apigeectl/ 目錄中，執行 apigeectl init、apigeectl apply 和 apigeectl check-ready：
    1. 初始化 Hybrid 1.3.6：

       apigeectl init -f overrides_1.3.yaml

       其中 overrides_1.3.yaml 是您編輯過的 overrides.yaml 檔案。

    2. 在混合式 1.3 版中，--dry-run 標記的語法取決於您執行的 kubectl 版本。查看 kubectl 的版本：

       gcloud version

    3. 使用模擬測試檢查錯誤：

       kubectl 1.17 以下版本：

       apigeectl apply -f overrides_1.3.yaml --dry-run=true

       kubectl 1.18 以上版本：

       apigeectl apply -f overrides_1.3.yaml --dry-run=client

    4. 套用覆寫值。請視安裝方式，選取並遵循正式環境或示範/實驗環境的操作說明。

       生產

       在實際環境中，您應個別升級每個混合型元件，並在繼續處理下一個元件之前，檢查已升級元件的狀態。

       1. 套用覆寫值來升級 Cassandra：

          apigeectl apply -f overrides_1.3.yaml --datastore

       2. 檢查完成情況：

          kubectl -n namespace get pods

          其中 namespace 是 Apigee 混合式命名空間。

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

       3. 套用覆寫值來升級遙測元件，並檢查完成情況：

          apigeectl apply -f overrides_1.3.yaml --telemetry

          kubectl -n namespace get pods

       4. 套用覆寫值來升級機構層級元件 (MART、Watcher 和 Apigee Connect)，並檢查完成情況：

          apigeectl apply -f overrides_1.3.yaml --org

          kubectl -n namespace get pods

       5. 套用覆寫值來升級環境。您有兩種選擇：
          • 一次只對一個環境套用覆寫值，並檢查是否完成。針對每個環境重複執行這個步驟：

            apigeectl apply -f overrides_1.3.yaml --env env_name

            kubectl -n namespace get pods

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

          • 一次將覆寫值套用至所有環境，並檢查是否完成：

            apigeectl apply -f overrides_1.3.yaml --all-envs

            kubectl -n namespace get pods

       示範/實驗

       在大多數的示範或實驗環境中，您可以一次將覆寫值套用至所有元件。如果您的示範/實驗環境龐大且複雜，或與實際執行環境相似，建議您參考升級實際執行環境的操作說明

       1. apigeectl apply -f overrides_1.3.yaml

       2. 查看狀態：

          apigeectl check-ready -f overrides_1.3.yaml

       如需更多操作說明，請參閱「GKE Hybrid 設定 - 第 5 步驟：在 GKE 上安裝 Hybrid」。

    5. 完成混合型 1.3 的設定並啟用後，請確認所有 Cassandra 節點 (舊版和新版) 都屬於同一個 Cassandra 叢集。在其中一個 Cassandra 節點上執行下列指令：

       kubectl -n namespace get pods
       kubectl -n namespace exec old Cassandra pod -- nodetool status

       在以下範例輸出內容中，10.68.8.24 來自 1.2.0 版，是您用於 externalSeedHost 的節點 IP。10.68.7.11 來自 1.3.6 版：

       Datacenter: dc-1
       ================
       Status=Up/Down
       |/ State=Normal/Leaving/Joining/Moving
       --  Address     Load        Tokens       Owns (effective)  Host ID                               Rack
       UN  10.68.8.24  379.41 KiB  256          50.8%             11bbd43b-af64-464b-a96d-0d6dd0521de1  ra-1
       UN  10.68.7.11  1.35 MiB    256          49.2%             0b4d9e08-f353-413a-b4a9-7d18a8d07e58  ra-1

       如果不屬於同一個叢集，請檢查 externalSeedHost 值。

    6. 所有 Pod 都已啟動並執行後，請從覆寫檔案中移除 externalSeedHost，然後使用 --datastore 選項再次執行 apigeectl apply：

       apigeectl apply --datastore -f overrides_1.3.6.yaml

    清除

    確認所有 Pod 都已啟動且運作正常，且 ASM 端點適用於新安裝作業後，您就可以進行清理作業：

    • Hybrid 1.2 資源。
    • 較舊的 Cassandra 執行個體
    • Istio 1.4.6 資源。

    刪除 Hybrid 1.2.0 資源

    1. 移除 1.2.0 虛擬主機轉送詳細資料：

       $APIGEECTL_HOME-v1.2/apigeectl delete -s virtualhost -f 1.2.0_overrides.yaml

       其中 $APIGEECTL_HOME-v1.2 是您備份 apigeectl 1.2 版目錄的目錄。

    2. 如果端點仍可正常運作，且您已確認所有 1.3.0 元件皆可正常運作，請執行下列指令來刪除混合式 1.2.0 資源：

       $APIGEECTL_HOME-v1.2/apigeectl delete -c "mart,connect-agent,synchronizer,runtime,udca,metrics,logger" \
         -f 1.2.0_overrides.yaml

    停用舊版 Cassandra 執行個體

    1. cd 到新安裝的 apigeectl 目錄中。
    2. 執行 tools/cas_cleanup.sh 指令碼。

       這個指令碼會從 Cassandra 環中停用舊的 Cassandra pod、刪除舊的 STS，以及刪除 PVC。

       bash cas_cleanup.sh Apigee namespace

    刪除 Istio 1.4.6 版資源

    1. 執行下列指令，刪除最新的 Istio 1.4.6 版資源：

       kubectl delete all -n istio-system --selector \
         'app in (apigee-mart-istio-ingressgateway, galley, security, istio-nodeagent, istio-mixer, sidecarInjectorWebhook, istio-mixer)'

    2. 執行下列指令，從 Istio 1.4.6 安裝中刪除較舊的工作：

       kubectl -n istio-system delete job istio-init-crd-10-1.4.6
       kubectl -n istio-system delete job istio-init-crd-11-1.4.6
       kubectl -n istio-system delete job istio-init-crd-14-1.4.6

    恭喜！您已成功升級至 Apigee Hybrid 1.3.6 版。