将 Apigee Hybrid 升级到 1.17 版

此过程涉及从 Apigee Hybrid 1.16.x 版升级到 Apigee Hybrid 1.17.0 版。

相对于 Apigee Hybrid v1.16 的更改

请注意以下变化：

  • 支持 Model Context Protocol (MCP)： Apigee Hybrid 版本 1.17 新增了对 Model Context Protocol (MCP) 的支持。MCP 是一种开放式协议，可让智能体 AI 应用通过受管理的 MCP 端点将您的 API 用作工具。Apigee Hybrid 会以管理其他 API 的相同方式来路由、授权和保护这些 MCP 工具调用，因此您无需运行或维护自己的 MCP 服务器。如需了解详情，请参阅 Apigee 概览中的 Model Context Protocol (MCP) 和 MCP 快速入门。
  • 根 CA 证书轮替： Apigee Hybrid 版本 1.17 新增了对轮替根证书授权机构 (CA) 证书的支持，该证书可为运行时组件之间的 TLS 通信锚定信任。现在，您可以按照分阶段轮替程序在根 CA 过期之前替换它，而无需停机。如需了解详情，请参阅轮替根 CA 证书。
  • 支持 TLS 1.3： Apigee hybrid 1.17 版新增了对 TLS 1.3（传输层安全协议的最新版本）的支持。与之前的 TLS 版本相比，TLS 1.3 可提供更快的连接握手速度和更强的安全性。如需了解如何在入站流量网关上配置 TLS，请参阅在入站流量网关上配置 TLS 和 mTLS。
  • 为 AI 政策提供转发代理支持： Apigee Hybrid 1.17 版为 AI 政策（例如 Model Armor 和语义缓存政策）添加了转发代理支持。这些政策发出的出站调用现在可以通过 HTTP 转发代理进行路由，而这在早期版本的 Apigee Hybrid 中是不受支持的。如需了解详情，请参阅为 API 代理配置转发代理。
  • 语义缓存 Private Service Connect (PSC) 端点支持： Apigee Hybrid 版本 1.17 为语义缓存添加了 Private Service Connect (PSC) 端点支持。现在，语义缓存政策可以通过 Private Service Connect 端点访问其后备服务，从而确保流量在您的专用网络中传输。如需了解详情，请参阅语义缓存政策使用入门。

如需详细了解 Hybrid 1.17 版中的功能，请参阅 Apigee Hybrid v1.17.0 版本说明。

前提条件

升级到 Hybrid 1.17 版之前，请确保您的安装满足以下要求：

在升级到 1.17.0 之前 - 限制和重要注意事项

  • 升级到 Apigee Hybrid 1.17 版可能需要停机。

    将 Apigee 控制器升级到 1.17.0 版时，所有 Apigee 部署都将执行滚动式重启。为了最大限度地减少滚动重启期间生产混合环境中的停机时间，请确保您至少（在相同或不同的区域/数据中心）运行两个集群。将所有生产流量转移到单个集群并且让您要升级的集群下线，然后继续执行升级过程。对每个集群重复执行此过程。

    Apigee 建议您在开始升级后，应尽快升级所有集群，以降低影响生产的可能性。第一个集群升级后，其余所有集群必须在何时升级是没有限制的。但是，在所有剩余集群升级之前，Cassandra 备份和恢复不能使用混合版本。例如，Hybrid 1.16 的备份不能用于恢复 Hybrid 1.17 实例。

  • 在升级过程中，管理平面的更改无需完全暂停。下面的升级说明中列出了对管理平面更改的所有必需的临时暂停操作。

升级到 1.17.0 版概览

以下各部分介绍升级 Apigee Hybrid 的过程：

  1. 准备升级。
  2. 安装 Hybrid 运行时 1.17.0 版。

准备升级到 1.17 版

备份 Hybrid 安装

  1. 这些说明将环境变量 APIGEE_HELM_CHARTS_HOME 用于文件系统中安装了 Helm 图表的目录。如果需要，请切换到此目录，然后使用以下命令定义变量：

    Linux 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Mac OS 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Windows 

    set APIGEE_HELM_CHARTS_HOME=%CD%
echo %APIGEE_HELM_CHARTS_HOME%
  2. 创建 1.16 版 $APIGEE_HELM_CHARTS_HOME/ 目录的备份副本。您可以使用任何备份过程。例如，您可以使用以下命令创建整个目录的 tar 文件： 
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.16-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. 按照 Cassandra 备份和恢复中的说明备份 Cassandra 数据库。
  4. 确保您的 TLS 证书和密钥文件（.crt、.key 和/或 .pem）位于 $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/ 目录中。

升级 Kubernetes 版本

检查您的 Kubernetes 平台版本，并根据需要将 Kubernetes 平台升级到 Hybrid 1.16 和 Hybrid 1.17 均支持的版本。如需帮助，请参阅该平台的相关文档。

拉取 Apigee Helm 图表。

Apigee Hybrid 图表托管在 Google Artifact Registry 中：

oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts

使用以下 pull 命令将所有 Apigee Hybrid Helm 图表复制到您的本地存储空间： 

export CHART_REPO=oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts
export CHART_VERSION=1.17.0
helm pull $CHART_REPO/apigee-operator --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-datastore --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-env --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-ingress-manager --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-org --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-redis --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-telemetry --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-virtualhost --version $CHART_VERSION --untar

为自定义 apigee 命名空间修改 kustomization.yaml

如果您的 Apigee 命名空间不是 apigee，请修改 apigee-operator/etc/crds/default/kustomization.yaml 文件并将 namespace 值替换为您的 Apigee 命名空间。

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: APIGEE_NAMESPACE

如果您使用 apigee 作为命名空间，则无需修改该文件。

  • 安装更新后的 Apigee CRD：

    1. 通过运行以下命令使用 kubectl 试运行功能：

      kubectl apply -k  apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false --dry-run=server

    2. 使用试运行命令进行验证后，运行以下命令：

      kubectl apply -k  apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
    3. 使用 kubectl get crds 命令验证安装：
      kubectl get crds | grep apigee

      输出内容应如下所示：

      apigeedatastores.apigee.cloud.google.com                    2024-08-21T14:48:30Z
apigeedeployments.apigee.cloud.google.com                   2024-08-21T14:48:30Z
apigeeenvironments.apigee.cloud.google.com                  2024-08-21T14:48:31Z
apigeeissues.apigee.cloud.google.com                        2024-08-21T14:48:31Z
apigeeorganizations.apigee.cloud.google.com                 2024-08-21T14:48:32Z
apigeeredis.apigee.cloud.google.com                         2024-08-21T14:48:33Z
apigeerouteconfigs.apigee.cloud.google.com                  2024-08-21T14:48:33Z
apigeeroutes.apigee.cloud.google.com                        2024-08-21T14:48:33Z
apigeetelemetries.apigee.cloud.google.com                   2024-08-21T14:48:34Z
cassandradatareplications.apigee.cloud.google.com           2024-08-21T14:48:35Z

  • 检查集群节点上的标签。 默认情况下，Apigee 会将数据 pod 调度到带有 cloud.google.com/gke-nodepool=apigee-data 标签的节点上，并将运行时 pod 调度到带有 cloud.google.com/gke-nodepool=apigee-runtime 标签的节点上。您可以在 overrides.yaml 文件中自定义节点池标签。

    如需了解详情，请参阅配置专用节点池。

    • 升级 cert-manager

    Apigee Hybrid v1.17 支持 cert-manager 版本 1.16 到 1.19。cert-manager 1.18 中有一项变更可能会导致流量出现问题。在 cert-manager 版本 1.18 中，Certificate.Spec.PrivateKey.rotationPolicy 的默认值已从 Never 更改为 Always。对于升级后的 Apigee Hybrid 安装，这可能会导致流量出现问题。从较低版本升级到 Hybrid v1.17 时，您必须修改 apigee-ca 证书以弥补此变更，或者将 cert-manager 版本保持在 1.17.x 版或更低版本。

    在将 cert-manager 升级到 1.18 或 1.19 之前，请按照以下步骤修改 apigee-ca 证书，将 Certificate.Spec.PrivateKey.rotationPolicy 的值设置为 Never。

    1. 检查 apigee-ca 证书的内容，看看是否已设置 rotationPolicy： 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      在输出中查找 spec.privateKey 下的值：

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    # Note: rotationPolicy would appear here if it is set.
    size: 256
  secretName: apigee-ca
...
    2. 如果未设置 rotationPolicy 或将其设置为 Always，请修改 apigee-ca 证书，将 rotationPolicy 的值设置为 Never：
      1. 首先执行试运行： 
        kubectl patch Certificate \
  --dry-run=server \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
      2. 修补证书： 
        kubectl patch Certificate \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
    3. 验证 rotationPolicy 的值现在是否已设置为 Never： 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      输出应类似如下所示：

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    rotationPolicy: Never
    size: 256
  secretName: apigee-ca
...
    4. 升级 cert-manager。以下命令将下载并安装 cert-manager v1.19.2： 
      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

      如需查看受支持的版本列表，请参阅受支持的平台和版本：cert-manager。

    请参阅：

    安装 Hybrid 1.17.0 运行时

    1. 如果没有，请转到 APIGEE_HELM_CHARTS_HOME 目录。从该目录运行以下命令。
    2. 升级 Apigee Operator/Controller：

      试运行：

      helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      升级图表：

      helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      验证 Apigee Operator 安装：

      helm ls -n APIGEE_NAMESPACE

      NAME       NAMESPACE       REVISION   UPDATED                                STATUS     CHART                   APP VERSION
operator   apigee   3          2024-08-21 00:42:44.492009 -0800 PST   deployed   apigee-operator-1.17.0   1.17.0

      通过检查可用性来验证它已启动并正在运行：

      kubectl -n APIGEE_NAMESPACE get deploy apigee-controller-manager

      NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
apigee-controller-manager   1/1     1            1           7d20h
    3. 升级 Apigee 数据存储区：

      试运行：

      helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      升级图表：

      helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      通过检查 apigeedatastore 的状态来验证它已启动并正在运行：

      kubectl -n APIGEE_NAMESPACE get apigeedatastore default

      NAME      STATE       AGE
default   running    2d
    4. 升级 Apigee 遥测：

      试运行：

      helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      升级图表：

      helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      通过检查状态来验证它已启动并正在运行：

      kubectl -n APIGEE_NAMESPACE get apigeetelemetry apigee-telemetry

      NAME               STATE     AGE
apigee-telemetry   running   2d
    5. 升级 Apigee Redis：

      试运行：

      helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      升级图表：

      helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      通过检查状态来验证它已启动并正在运行：

      kubectl -n APIGEE_NAMESPACE get apigeeredis default

      NAME      STATE     AGE
default   running   2d
    6. 升级 Apigee 入站流量管理器：

      试运行：

      helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      升级图表：

      helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      通过检查可用性来验证它已启动并正在运行：

      kubectl -n APIGEE_NAMESPACE get deployment apigee-ingressgateway-manager

      NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
apigee-ingressgateway-manager   2/2     2            2           2d
    7. 升级 Apigee 组织：

      试运行：

      helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      升级图表：

      helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      通过检查相应组织的状态来验证它已启动并正在运行：

      kubectl -n APIGEE_NAMESPACE get apigeeorg

      NAME                      STATE     AGE
apigee-my-org-my-env      running   2d
    8. 升级环境。

      一次只能安装一个环境。使用 --set env=ENV_NAME 指定环境。

      试运行：

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server
      • ENV_RELEASE_NAME 是用于跟踪 apigee-env 图表的安装和升级情况的名称。此名称必须与安装中的其他 Helm 版本名称不同。 通常，这与 ENV_NAME 相同。但是，如果环境与环境组具有相同的名称，则您必须为环境和环境组使用不同的版本名称，例如 dev-env-release 和 dev-envgroup-release。如需详细了解 Helm 中的版本，请参阅 Helm 文档中的三大概念。
      • ENV_NAME 是您要升级的环境的名称。
      • OVERRIDES_FILE 是 v.1.17.0 的新替换文件

      升级图表：

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE

      通过检查相应环境的状态来验证它已启动并正在运行：

      kubectl -n APIGEE_NAMESPACE get apigeeenv

      NAME                          STATE       AGE   GATEWAYTYPE
apigee-my-org-my-env          running     2d
    9. 升级环境组 (virtualhosts)。
      1. 一次只能升级一个环境组 (virtualhost)。使用 --set envgroup=ENV_GROUP_NAME 指定环境组。对 override.yaml 文件中提到的每个环境组重复运行以下命令：

        试运行：

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server

        ENV_GROUP_RELEASE_NAME 是您之前安装 apigee-virtualhost 图表时使用的名称。通常为 ENV_GROUP_NAME。

        升级图表：

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE
      2. 检查 ApigeeRoute (AR) 的状态。

        安装 virtualhosts 会创建 ApigeeRouteConfig (ARC)，它会在 Apigee Watcher 从控制平面拉取环境组相关详细信息后在内部创建 ApigeeRoute (AR)。因此，请检查相应 AR 的状态是否为正在运行： 

        kubectl -n APIGEE_NAMESPACE get arc

        NAME                                STATE   AGE
apigee-org1-dev-egroup                       2d
         
        kubectl -n APIGEE_NAMESPACE get ar

        NAME                                        STATE     AGE
apigee-org1-dev-egroup-123abc               running   2d

    回滚到先前的版本

    如需回滚到先前版本，请使用较早的图表版本以相反的顺序回滚升级过程。从 apigee-virtualhost 开始，然后返回 apigee-operator，接着还原 CRD。

    1. 还原图表。以下命令假定您使用的是先前版本 (v1.16.x) 中的图表。

      1. 对每个环境组运行以下命令：

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set envgroup=ENV_GROUP_NAME \
  -f 1.16_OVERRIDES_FILE

      2. 对每个环境运行以下命令：

        helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=ENV_NAME \
  -f 1.16_OVERRIDES_FILE

      3. apigee-org：

        helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      4. apigee-ingress-manager：

        helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      5. apigee-redis：

        helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      6. apigee-telemetry：

        helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      7. apigee-datastore：

        helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      8. apigee-operator：

        helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE
    2. 通过重新安装较旧的 CRD 来还原 CRD。
      kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false