将 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. 安装 Hybrid 运行时 1.9.4 版。

前提条件

  • 以下升级说明假定您已安装 Apigee Hybrid 1.8.x 版，并且希望升级到 1.9.4 版。如果您要从更低版本进行更新，请参阅将 Apigee Hybrid 升级到 1.8 版的说明。
  • 在 Apigee Hybrid 1.8 版中，我们引入了 Apigee 入站流量网关作为 Anthos Service Mesh 的备用入站流量层。从 1.9.0 版开始，Apigee Hybrid 要求使用 Apigee 入站流量网关，并且不再支持使用 Anthos Service Mesh 处理入站流量。如果要升级的安装使用 Anthos Service Mesh，则必须先改用 Apigee 入站流量网关，然后再升级到 1.9.4 版。

    Apigee 入站流量网关为入站流量网关使用一小部分 Anthos Service Mesh 功能。这些功能的管理和升级由 Apigee Hybrid 自动处理。 因此，您无需具备 Anthos Service Mesh 专业知识，即可安装、升级和管理 Apigee Hybrid 入站流量网关。

    如需查看相关说明，请参阅 Hybrid v1.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 Agent 角色添加到 Apigee 运行时的服务账号。（可选）

可选：如果您打算使用 Cloud Trace，并且尚未将 Cloud Trace Agent 角色添加到 Hybrid v1.8 安装，请确保 Apigee 运行时服务的服务账号具有 Cloud Trace Agent 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 Agent 角色分配给服务账号：

    生产 

    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 Service Mesh，请安装 Apigee 入站流量网关

从 1.9 版开始，Apigee Hybrid 不再支持使用 Anthos Service Mesh 处理入站流量。如果您的 Hybrid 安装使用的是 Anthos Service Mesh，则必须先将当前安装迁移到 Apigee 入站流量网关，然后才能安装 Hybrid 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. See Known issue 243599452.
      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（可选）：。

      这是一个键值对，用于为默认入站流量服务提供注解。云平台会使用注解来帮助您配置 Hybrid 安装，例如将 loadbalancer 类型设置为内部或外部。例如： 

      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 入站流量网关中的步骤操作。
  4. 通过调用代理来测试新的入站流量网关。理想情况下，应测试当前已部署的所有关键代理。
  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 Service Mesh)，因为 DNS 更新可能会因 DNS 缓存而传播缓慢。
  7. 如需让 Apigee 停止向 Anthos Service Mesh 提供配置，请按照“管理 Apigee 入站流量网关”指南中的停止向 ASM 提供配置部分所述步骤操作。
  8. 重新测试和监控 API 代理流量。
  9. 按照 Anthos Service Mesh 文档中的说明从集群中卸载 Anthos Service Mesh。

安装 Hybrid 1.9.4 运行时

  1. 确保您位于 Hybrid 基本目录中（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 文件内容解压缩到 Hybrid 基本目录中。 Hybrid 基本目录是重命名后的 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. 如果没有错误，则应用替换文件。选择生产环境或非生产环境的相关说明并按照这些说明操作，具体取决于您的安装。

    生产环境

    对于生产环境，请单独升级每个 Hybrid 组件，并检查升级后的组件的状态，再继续升级下一个组件。

    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 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 是先前 Hybrid 安装版本的替换文件的相对路径和文件名，例如 ./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