将 Apigee Hybrid 升级到 1.3.6 版

升级到 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 关联的集群

如果您在安装 Hybrid 的过程中未使用 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 Agent 角色分配给 MART 服务账号：

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

提示：如果您需要获取 MART 服务账号的电子邮件地址，请运行以下命令：

gcloud iam service-accounts list | grep mart

使用以下命令启用 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 入站流量。
从您的以下主混合目录中：
```
./tools/create-service-account apigee-watcher ./service-accounts
```
将 Apigee Runtime Agent 角色分配给 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。如果您的服务账号电子邮件地址与此格式不同，请相应地替换该电子邮件地址。
提示：如果您需要获取 watcher 服务账号的电子邮件地址，请运行以下命令：
```
gcloud iam service-accounts list | grep watcher
```
输出应列出所有服务账号及其角色，其中包括：
```
  ...
- members:
  - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
  role: roles/apigee.runtimeAgent
  ...
```
规划您的环境组以进行路由。Apigee Hybrid 1.3 使用环境组而不是 routingRules 来管理基本路径路由。如果您在 Hybrid 配置中使用 routingRules，请设计环境组以复制路由。
您必须至少创建一个环境组。

请参阅环境组简介。
点击查看使用环境组替换 routingRules 的示例

在下面的示例中，overrides.yaml 文件中的以下 routingRules 将对 foo 和 bar API 代理的请求路由到 prod-env-1 环境，将 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 代理部署到 prod-env-1 环境。
2. 将 foo-test 和 bar 代理部署到 test-env 环境。
3. 使用代理的主机别名（例如 api.acme.com）创建环境组。
  提示：创建一个与 1.2 版中使用的 virtualhosts 名称相同的环境组。
4. 修改 overrides.yaml 中的 virtualhosts 节
  - 将 virtualhosts:name 替换为环境组的名称。
  - 移除 virtualhosts:routingRules。
  例如：
```
virtualhosts:
  - name: default # environment group name
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
```
更新替换文件：

创建替换文件的副本。

更新 gcp 和 k8sCluster 节。

Hybrid 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

替换为：

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

如果您的替换文件中还没有唯一的实例标识符，请添加一个：
```
# unique identifier for this installation. 63 chars length limit
instanceID: ID
```
其中 ID 是此 Hybrid 安装的唯一标识符，例如“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 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 Service Mesh (ASM) 1.5.7 版（或更高版本）一起提供的证书和 Istio 发行版，以创建和管理运行时入站流量网关。

将 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 文件内容解压缩到 Hybrid 基本目录中。例如：
```
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 集群。只有从 Hybrid 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 是修改后的 override.yaml 文件。
2. 在 Hybrid 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. 应用替换文件：选择生产环境或演示/实验环境的相关说明并按照这些说明操作，具体取决于您的安装。
  在升级过程中，每个组件都会执行滚动式重启。因此，对于生产环境，最好每次将升级应用于一个组件。
  生产
  
  对于生产环境，您应该单独升级每个 Hybrid 组件，并检查升级后的组件的状态，再继续升级下一个组件。
  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. 在设置并运行 Hybrid 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
```
  如果 Cassandra 节点不在同一个集群中，请检查 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 组件均正常运行，请运行以下命令删除 Hybrid 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 Ingress 已替换为 Apigee Connect。
1. 运行以下命令以删除最新的 Istio v.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 版资源

点击查看使用环境组替换 `routingRules` 的示例