本頁面由 Cloud Translation API 翻譯而成。

將 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 的程序分為下列幾節：

準備

建立及更新服務帳戶。
規劃環境群組。
複製並更新覆寫檔案。

升級 Istio 和 cert-manager。
安裝 Hybrid 執行階段 1.3 版。
清除所用資源。

必要條件

Apigee Hybrid 1.2 版。如要從舊版更新，請參閱將 Apigee Hybrid 升級至 1.2 版的操作說明。

準備

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

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

(建議) 按照「Cassandra 備份與復原」一文中的說明，備份 Cassandra 資料庫。

請按照下列步驟升級 Kubernetes 平台。如需協助，請參閱相關平台的說明文件：

平台	升級至
GKE	1.15.x
Anthos	1.5
AKS	1.16.x，方法是使用 Anthos 附加叢集

如果您在混合式安裝中未使用 Apigee Connect，請啟用 Apigee Connect。

檢查 Apigee Connect API 是否已啟用：

gcloud services list | grep apigeeconnect

apigeeconnect.googleapis.com         Apigee Connect API

如果沒有，請啟用 API：
```
gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID
```
其中 $PROJECT_ID 是您的 Google Cloud 專案 ID。
在指令列中取得 gcloud 驗證憑證，如下列範例所示：
```
TOKEN=$(gcloud auth print-access-token)
```
如要確認權杖是否已填入，請使用 echo，如下列範例所示：
```
echo $TOKEN
```
這時應該會以編碼字串的形式顯示權杖。

詳情請參閱 gcloud 指令列工具總覽。

確認貴機構是否已啟用 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。

如果未啟用 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

使用下列指令啟用 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"
      }

建立 apigee-watcher 服務帳戶。Apigee Watcher 是 v1.3 中推出的新服務帳戶。這個控制器會監控同步器是否有機構層級的變更，並套用這些變更來設定 Istio Ingress。
從主要混合式目錄：
```
./tools/create-service-account apigee-watcher ./service-accounts
```
將 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。如果服務帳戶電子郵件地址與這個模式不同，請視情況替換。
提示：如要取得監控服務帳戶的電子郵件地址，請執行下列指令：
```
gcloud iam service-accounts list | grep watcher
```
輸出內容應包含所有服務帳戶及其角色的清單，包括：
```
  ...
- members:
  - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
  role: roles/apigee.runtimeAgent
  ...
```
規劃用於轉送的環境群組。 Apigee Hybrid 1.3 會使用環境群組管理基本路徑路由，而非 routingRules。如果您在混合式設定中使用 routingRules，請設計環境群組來複製路由。
您必須建立至少一個環境群組。

請參閱「關於環境群組」。
按一下即可查看使用環境群組取代 routingRules 的範例

在本範例中，overrides.yaml 檔案中的下列 routingRules 會將要求路由至 prod-env-1 環境的 foo 和 bar API Proxy，以及 test-env 環境的 foo-test Proxy：
```
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。
  提示：建立環境群組時，請使用與 1.2 版中虛擬主機名稱相同的名稱。
4. 在 overrides.yaml 中修訂 virtualhosts 詩節，如下所示：
  - 將 virtualhosts:name 替換為環境群組名稱。
  - 移除 virtualhosts:routingRules。
  例如：
```
virtualhosts:
  - name: default # environment group name
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
```
更新覆寫檔案：

複製覆寫檔案。

更新 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

如果覆寫檔案中沒有專屬的執行個體 ID，請新增一個：
```
# unique identifier for this installation. 63 chars length limit
instanceID: ID
```
其中 ID 是這個混合式安裝的專屬 ID，例如「my-hybrid-131-installation」或「acmecorp-hybrid-131」。

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

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

將指標 (apigee-metrics) 服務帳戶新增至覆寫檔案：
```
metrics:
 serviceAccountPath: "service account file"
```

更新 virtualhosts: 節，將 routingRules 替換為您的環境群組。

-name: 將名稱替換為環境群組的名稱。您可以有多個名稱項目，每個環境群組各有一個。
hostAliases:[] 刪除這一行。
保留 (或新增) sslCertPath: 和 sslKeyPath: 項目。
刪除所有 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

更新 mart 和 connectAgent: 節。
注意：如果您不打算在 Hybrid 1.3 安裝作業中使用 Apigee Connect，請略過這個步驟，並在升級後按照「Apigee Connect」的步驟 5 中的提示操作。
1. 在 mart: 下方，移除 hostAlias:、sslCertPath: 和 sslKeyPath: 項目。
2. 新增 connectAgent: 節。
3. 在 connectAgent: 下方新增 serviceAccountPath: 項目，並提供已指派 Apigee Connect 代理程式角色的服務帳戶檔案路徑 (通常是 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 發行版本，建立及管理執行階段 Ingress 閘道。

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

為盡量減少停機時間，Istio 部署作業和 HPA 各自至少要有兩個副本。執行下列指令，判斷副本數量：
```
kubectl -n istio-system get deployments # list of deployments
kubectl -n istio-system get hpa # list of hpa
```

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

kubectl -n istio-system edit deployment name

例如：

spec:
  progressDeadlineSeconds: 600
  replicas: 2

編輯每個只有一個副本的 HPA，並將 minReplicas: 增加至 2 以上：
```
kubectl -n istio-system edit hpa name
```
例如：
```
spec:
  maxReplicas: 5
  minReplicas: 2
```
按照「下載並安裝 ASM」一文的安裝說明，下載並安裝 ASM。

安裝完成後，請執行版本指令，確認您已正確安裝 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

刪除目前的 cert-manager 部署：

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

確認 Kubernetes 版本：
```
kubectl version
```

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

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

安裝 Hybrid 執行階段

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

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

確認變數已填入版本號碼。如要使用其他版本，可以改為將版本儲存在環境變數中。例如：
```
echo $VERSION
  1.3.6
```

根據所用的作業系統下載發布套件：

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

將目前的 apigeectl/ 目錄重新命名為備份目錄名稱。例如：
```
mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 
```
將下載的 gzip 檔案內容解壓縮至混合式基本目錄。例如：
```
tar xvzf filename.tar.gz -C hybrid-base-directory
```
cd 至基本目錄。
根據預設，tar 內容會展開至目錄中，且目錄名稱會包含版本和平台。例如：./apigeectl_1.0.0-f7b96a8_linux_64。將該目錄重新命名為 apigeectl：
```
mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
```

從 apigee-system 刪除 apigee-resources-install 工作：

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

刪除舊版 CRD：

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

在覆寫檔案中，使用 externalSeedHost 屬性更新 cassandra: 節。這項屬性可確保新安裝的 Hybrid 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 Hybrid 命名空間。
  
  記下 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)。
  
  注意：新版 Cassandra 執行並完成驗證後，您會在後續步驟中移除 externalSeedHost 屬性。
在新 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 Hybrid 命名空間。
    
    只有在 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 資源
注意：這項程序需要備份目錄中的 apigeectl 1.2 版指令。如需下載另一個 apigeectl 1.2 版副本，可以使用下列指令：
```
curl -LO \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/1.2.0/apigeectl_your_system.tar.gz
```
其中 your_system 是 linux_32、linux_64、mac_32 或 mac_64。
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 版資源

注意：刪除 Istio 1.4.6 版資源時，系統也會一併刪除 MART Ingress。在 Apigee Hybrid 1.3 版中，MART 傳入流量已由 Apigee Connect 取代。
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 版。

將 Apigee Hybrid 升級至 1.3.6 版 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

升級至 1.3.6 版的總覽。

必要條件

準備

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

升級 Istio 和 cert-manager

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

升級 cert-manager

安裝 Hybrid 執行階段

正式環境

示範/實驗

清除

刪除 Hybrid 1.2.0 資源

停用舊版 Cassandra 執行個體

刪除 Istio 1.4.6 版資源

將 Apigee Hybrid 升級至 1.3.6 版

按一下即可查看使用環境群組取代 `routingRules` 的範例