将 Apigee Hybrid 升级到 1.14 版

此过程涉及从 Apigee Hybrid 1.13.x 版升级到 Apigee Hybrid 1.14.0 版。

相对于 Apigee Hybrid v1.13 的更改

请注意以下更改：

  • Apigee 命名空间中的 apigee-operator：从 1.13 版开始，apigee-operator 与其他 Apigee Hybrid 组件（默认情况下为 apigee）在同一 Kubernetes 命名空间中运行。您可以为命名空间提供任何名称。在以前的版本中，apigee-operator 需要在其自己的命名空间 apigee-system 中运行。
  • Anthos（on Bare Metal 或 VMware）现已更名为 Google Distributed Cloud（for Bare Metal 或 VMware）：如需了解详情，请参阅产品概览 Google Distributed Cloud for bare metal 和 Google Distributed Cloud for VMware。

前提条件

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

升级到 1.14.0 版概览

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

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

准备升级到 1.14 版

备份 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.13 版 $APIGEE_HELM_CHARTS_HOME/ 目录的备份副本。您可以使用任何备份过程。例如，您可以使用以下命令创建整个目录的 tar 文件： 
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.13-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. 按照 Cassandra 备份和恢复中的说明备份 Cassandra 数据库。
  4. 如果您使用替换文件中的服务证书文件 (.json) 对服务账号进行身份验证，请确保服务账号证书文件位于正确的 Helm 图表目录中。Helm 图表无法读取每个图表目录之外的文件。

    如果您使用 Kubernetes Secret 或 Workload Identity 对服务账号进行身份验证，则无需执行此步骤。

    下表展示了每个服务账号文件的目标位置，具体取决于您的安装类型：

    生产

    服务账号 默认文件名 Helm 图表目录
    apigee-cassandra PROJECT_ID-apigee-cassandra.json $APIGEE_HELM_CHARTS_HOME/apigee-datastore/
    apigee-logger PROJECT_ID-apigee-logger.json $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    apigee-mart PROJECT_ID-apigee-mart.json $APIGEE_HELM_CHARTS_HOME/apigee-org/
    apigee-metrics PROJECT_ID-apigee-metrics.json $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    apigee-runtime PROJECT_ID-apigee-runtime.json $APIGEE_HELM_CHARTS_HOME/apigee-env
    apigee-synchronizer PROJECT_ID-apigee-synchronizer.json $APIGEE_HELM_CHARTS_HOME/apigee-env/
    apigee-udca PROJECT_ID-apigee-udca.json $APIGEE_HELM_CHARTS_HOME/apigee-org/
    apigee-watcher PROJECT_ID-apigee-watcher.json $APIGEE_HELM_CHARTS_HOME/apigee-org/

    非生产

    创建以下每个目录中的 apigee-non-prod 服务账号文件的副本：

    服务账号 默认文件名 Helm 图表目录
    apigee-non-prod PROJECT_ID-apigee-non-prod.json $APIGEE_HELM_CHARTS_HOME/apigee-datastore/
    $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    $APIGEE_HELM_CHARTS_HOME/apigee-org/
    $APIGEE_HELM_CHARTS_HOME/apigee-env/
  5. 确保您的 TLS 证书和密钥文件（.crt、.key 和/或 .pem）位于 $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/ 目录中。

升级 Kubernetes 版本

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

安装 Hybrid 1.14.0 运行时

准备 Helm 图表升级

  1. 拉取 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.14.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
  2. 根据需要升级 cert-manager。

    如果您需要升级 cert-manager 版本，请使用以下命令安装新版本：

    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.1/cert-manager.yaml

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

  3. 如果 Apigee 命名空间不是 apigee，请修改 apigee-operator/etc/crds/default/kustomization.yaml 文件并将 namespace 值替换为您的 Apigee 命名空间。
    apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: APIGEE_NAMESPACE

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

  4. 安装更新后的 Apigee CRD：

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

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

    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
  5. 将 apigee-operator 从 apigee-system 命名空间迁移到 APIGEE_NAMESPACE。
    1. 使用新命名空间为 clusterIssuer 添加注解
      kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-namespace='APIGEE_NAMESPACE'
    2. 如果要更改 apigee-operator 的版本名称，请使用新版本名称为 clusterIssuer 添加注解。
      kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-name='APIGEE_OPERATOR_RELEASE_NAME'
  6. 将 apigee-system 命名空间中现有 Apigee Operator 部署的副本更新为 0（零），以避免两个控制器协调。
    kubectl scale deployment apigee-controller-manager -n apigee-system --replicas=0
  7. 将 apigee-system 命名空间中现有 Apigee Operator 部署的副本更新为 0（零），以避免两个控制器协调。
    kubectl delete mutatingwebhookconfiguration apigee-mutating-webhook-configuration
kubectl delete validatingwebhookconfiguration apigee-validating-webhook-configuration

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

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

安装 Apigee Hybrid Helm 图表

  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.14.0   1.14.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-org1-xxxxx          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 图表时使用的名称。在 Hybrid v1.10 中，该名称通常是 apigee-env-ENV_NAME。在 Hybrid v1.11 及更高版本中，该名称通常是 ENV_NAME。
    • ENV_NAME 是您要升级的环境的名称。
    • OVERRIDES_FILE 是 v.1.14.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-org1-dev-xxx            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 图表时使用的名称。在 Hybrid v1.10 中，该名称通常是 apigee-virtualhost-ENV_GROUP_NAME。在 Hybrid v1.11 及更高版本中，该名称通常是 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-xxxxxx                running   2d
  10. 确认所有安装都已成功升级后，从 apigee-system 命名空间中删除较旧的 apigee-operator 版本。
    1. 卸载旧的 operator 版本：
      helm delete operator -n apigee-system
    2. 删除 apigee-system 命名空间： 
      kubectl delete namespace apigee-system
  11. 再次在 Apigee 命名空间中升级 operator，以重新安装已删除的集群级资源：
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml

回滚到先前的版本

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

由于 apigee-operator 的命名空间发生了变化，您需要执行额外的步骤来删除验证和更改准入钩子。这样，当您将 apigee-operator 安装回 apigee-system 命名空间时，系统会重新创建它们以指向正确的 Apigee Operator 端点。

  1. 将 Apigee 中现有 Apigee Operator 部署的副本更新为 0（零），以避免两个控制器对自定义资源进行协调，从而避免在 apigee-system 命名空间中回滚时发生冲突。
    kubectl scale deployment apigee-controller-manager -n APIGEE_NAMESPACE --replicas=0

kubectl delete mutatingwebhookconfiguration \
  apigee-mutating-webhook-configuration-APIGEE_NAMESPACE

kubectl delete validatingwebhookconfiguration \
  apigee-validating-webhook-configuration-APIGEE_NAMESPACE
  2. 将所有图表从 apigee-virtualhost 还原为 apigee-datastore。以下命令假定您使用的是旧版 (v1.13.x) 中的图表。

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

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

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

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

    还原除 apigee-operator 以外的其余图表。

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

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

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

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

    helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace apigee \
  --atomic \
  -f 1.13_OVERRIDES_FILE
  3. 创建 apigee-system 命名空间。 
    kubectl create namespace apigee-system
  4. 将资源注解重新修补到 apigee-system 命名空间。
    kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-namespace='apigee-system'
  5. 如果您也更改了版本名称，请使用 operator 版本名称更新注释。
    kubectl annotate --overwrite cluseterIssuer apigee-ca-issuer meta.helm.sh/release-name='operator'
  6. 将 apigee-operator 重新安装到 apigee-system 命名空间中。
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace apigee-system \
  --atomic \
  -f 1.13_OVERRIDES_FILE
  7. 通过重新安装较旧的 CRD 来还原 CRD。
    kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
  8. 清理 APIGEE_NAMESPACE 命名空间中的 apigee-operator 版本以完成回滚过程。
    helm uninstall operator -n APIGEE_NAMESPACE
  9. 当 operator 被卸载时，某些集群级资源（例如 clusterIssuer）会被删除。使用以下命令重新安装它们：
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace apigee-system \
  --atomic \
  -f 1.13_OVERRIDES_FILE