将 Apigee Hybrid 升级到 1.13 版

此过程涉及从 Apigee Hybrid 1.12.x 版升级到 Apigee Hybrid 1.13.0 版。

相对于 Apigee Hybrid v1.12 的更改

请注意以下更改:

  • 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 metalGoogle Distributed Cloud for VMware

前提条件

升级到 Hybrid 1.13 版之前,请确保您的安装满足以下要求:

  • 如果 Hybrid 安装运行的版本低于 v1.12,则在升级到 v1.13 之前,您必须先升级到 1.12 版。请参阅将 Apigee Hybrid 升级到 1.12 版
  • Helm v3.10+ 版。
  • kubectl 1.27、1.28 或 1.29 版(推荐)。
  • cert-manager v1.15.1 版。如果需要,您会在下面的准备升级到版本部分中升级 cert-manager。

升级到 1.13.0 版概览

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

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

准备升级到 1.13 版

备份 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.12 版 $APIGEE_HELM_CHARTS_HOME/ 目录的备份副本。您可以使用任何备份过程。例如,您可以使用以下命令创建整个目录的 tar 文件:
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.12-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.12 和 Hybrid 1.13 均支持的版本。如需帮助,请参阅该平台的相关文档。

安装 Hybrid 1.13.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.13.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
    
  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=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
      
  5. apigee-operatorapigee-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
    

    升级图表:

    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.13.0   1.13.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
    

    升级图表:

    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
    

    升级图表:

    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
    

    升级图表:

    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
    

    升级图表:

    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
    

    升级图表:

    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
    
    • ENV_RELEASE_NAME 是您之前安装 apigee-env 图表时使用的名称。在 Hybrid v1.10 中,该名称通常是 apigee-env-ENV_NAME。在 Hybrid v1.11 及更高版本中,该名称通常是 ENV_NAME
    • ENV_NAME 是您要升级的环境的名称。
    • OVERRIDES_FILE 是 v.1.13.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
      

      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.12.x) 中的图表。

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

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

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

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

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

    helm upgrade ORG_NAME apigee-org/ \
      --install \
      --namespace apigee \
      --atomic \
      -f 1.12_OVERRIDES_FILE
    
    helm upgrade ingress-manager apigee-ingress-manager/ \
      --install \
      --namespace apigee \
      --atomic \
      -f 1.12_OVERRIDES_FILE
    
    helm upgrade redis apigee-redis/ \
      --install \
      --namespace apigee \
      --atomic \
      -f 1.12_OVERRIDES_FILE
    
    helm upgrade telemetry apigee-telemetry/ \
      --install \
      --namespace apigee \
      --atomic \
      -f 1.12_OVERRIDES_FILE
    
    helm upgrade datastore apigee-datastore/ \
      --install \
      --namespace apigee \
      --atomic \
      -f 1.12_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.12_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.12_OVERRIDES_FILE