Help us learn about your current experience with the documentation. Take the survey.

升级部署以适配更新的 Auto Deploy 依赖

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Auto Deploy 是将你的应用程序部署到 Kubernetes 集群的功能。它包含几个依赖项：

Auto Deploy template 是一组使用 auto-deploy-image 的流水线作业和脚本。
auto-deploy-image 是与 Kubernetes 集群通信的可执行镜像。
auto-deploy-app chart 是用于部署应用程序的 Helm chart。

auto-deploy-image 和 auto-deploy-app chart 使用 Semantic Versioning。默认情况下，你的 Auto DevOps 项目会继续使用稳定且不破坏的版本。然而，这些依赖项可能会在 GitLab 的主要版本发布中升级，并包含破坏性更改，需要你升级部署。

本指南说明如何升级部署以使用更新或不同主要版本的 Auto Deploy 依赖项。

验证依赖版本

检查当前版本的过程取决于你使用的模板。首先验证正在使用哪个模板：

对于 GitLab Self-Managed 实例，使用的是 GitLab 包中捆绑的稳定 Auto Deploy template。
如果满足以下条件之一，则使用 GitLab.com 稳定 Auto Deploy template：
- 你的 Auto DevOps 项目没有 .gitlab-ci.yml 文件。
- 你的 Auto DevOps 项目有 .gitlab-ci.yml 文件，并且 includes 了 Auto-DevOps.gitlab-ci.yml 模板。
如果同时满足以下两个条件，则使用最新的 Auto Deploy template：
- 你的 Auto DevOps 项目有 .gitlab-ci.yml 文件，并且 includes 了 Auto-DevOps.gitlab-ci.yml 模板。
- 它还包含最新的 Auto Deploy template。

如果你知道正在使用哪个模板：

auto-deploy-image 版本在模板中（例如 auto-deploy-image:v1.0.3）。
auto-deploy-app chart 版本在 auto-deploy-image 仓库中（例如 version: 1.0.3）。

兼容性

下表说明了 GitLab 与 Auto Deploy 依赖项之间的版本兼容性：

GitLab 版本	`auto-deploy-image` 版本	说明
v10.0 到 v14.0	v0.1.0 到 v2.0.0	v0 和 v1 auto-deploy-image 向后兼容。
v13.4 及更高版本	v2.0.0 及更高版本	v2 auto-deploy-image 包含破坏性更改，如升级指南中所述。

你可以在 Auto Deploy 稳定模板中找到 auto-deploy-image 的当前稳定版本。

升级指南

使用 Auto DevOps 的项目必须使用由 GitLab 管理的未修改的 chart。自定义 chart 不受支持。

升级部署到 v1 `auto-deploy-image`

v1 chart 与 v0 chart 向后兼容，因此不需要配置更改。

升级部署到 v2 `auto-deploy-image`

v2 auto-deploy-image 包含多个依赖项和架构更改。如果你的 Auto DevOps 项目有使用 v1 auto-deploy-image 部署的活动环境，请按照以下升级指南进行操作。否则，你可以跳过此过程。

Kubernetes 1.16+

v2 auto-deploy-image 不再支持 Kubernetes 1.15 及更早版本。如果你需要升级 Kubernetes 集群，请遵循你的云提供商的说明。这里有一个 GKE 上的示例。

Helm v3

auto-deploy-image 使用 Helm 二进制文件来操作发布。之前，auto-deploy-image 使用 Helm v2，它在集群中使用 Tiller。在 v2 auto-deploy-image 中，它使用 Helm v3，不再需要 Tiller。

如果你的 Auto DevOps 项目有使用 v1 auto-deploy-image 部署的活动环境，请使用以下步骤升级到使用 Helm v3 的 v2：

包含 Helm 2to3 迁移 CI/CD 模板：
- 如果你在 GitLab.com 上，或使用 GitLab 14.0.1 或更高版本，此模板已包含在 Auto DevOps 中。
- 在其他版本的 GitLab 上，你可以修改 .gitlab-ci.yml 以包含模板：
```
include:
  - template: Auto-DevOps.gitlab-ci.yml
  - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Jobs/Helm-2to3.gitlab-ci.yml
```
设置以下 CI/CD 变量：
- MIGRATE_HELM_2TO3 设置为 true。如果此变量不存在，迁移作业不会运行。
- AUTO_DEVOPS_FORCE_DEPLOY_V2 设置为 1。
- 可选：BACKUP_HELM2_RELEASES 设置为 1。如果设置此变量，迁移作业会在名为 helm-2-release-backups 的作业工件中保存备份 1 周。如果你在准备好之前意外删除了 Helm v2 发布，你可以使用 kubectl apply -f $backup 从 Kubernetes 清单文件恢复此备份。
  
  如果你有公开的流水线，请不要使用此功能。此工件可能包含密钥，对任何可以查看你作业的用户都可见。
运行流水线并触发 <environment-name>:helm-2to3:migrate 作业。
像往常一样部署你的环境。此部署使用 Helm v3。
如果部署成功，你可以安全地运行 <environment-name>:helm-2to3:cleanup。这会从命名空间中删除所有 Helm v2 发布数据。
移除 MIGRATE_HELM_2TO3 CI/CD 变量或将其设置为 false。你可以使用环境范围逐个环境执行此操作。

集群内 PostgreSQL Channel 2

v2 auto-deploy-image 不再支持传统的集群内 PostgreSQL。如果你的 Kubernetes 集群仍然依赖它，请使用 v1 auto-deploy-image 升级并迁移你的数据。

金丝雀部署和渐进式发布的流量路由更改

Auto Deploy 支持高级部署策略，如金丝雀部署和渐进式发布。

之前，auto-deploy-image 创建一个服务，通过更改副本比例在不稳定和稳定轨道之间平衡流量。在 v2 auto-deploy-image 中，它使用 Canary Ingress 控制流量。

有关更多详细信息，请参阅 v2 auto-deploy-app chart 资源架构。

如果你的 Auto DevOps 项目在 production 环境中有使用 v1 auto-deploy-image 部署的活动 canary 或 rollout 轨道发布，请使用以下步骤升级到 v2：

验证你的项目正在使用 v1 auto-deploy-image。如果不是，指定版本。
如果你正在部署 canary 或 rollout 部署，请先将它们提升到 production 以删除不稳定轨道。
验证你的项目正在使用 v2 auto-deploy-image。如果不是，指定版本。
在 GitLab CI/CD 设置中添加一个值为 true 的 AUTO_DEVOPS_FORCE_DEPLOY_V2 CI/CD 变量。
创建新的流水线并运行 production 作业，以使用 v2 auto-deploy-app chart 更新资源架构。
移除 AUTO_DEVOPS_FORCE_DEPLOY_V2 变量。

使用特定版本的 Auto Deploy 依赖项

要使用特定版本的 Auto Deploy 依赖项，指定包含所需 auto-deploy-image 和 auto-deploy-app 版本的先前 Auto Deploy 稳定模板。

例如，如果模板捆绑在 GitLab 16.10 中，将你的 .gitlab-ci.yml 更改为：

include:
  - template: Auto-DevOps.gitlab-ci.yml
  - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/v16.10.0-ee/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml

忽略警告并继续部署

如果你确定新的 chart 版本可以安全部署，可以添加 AUTO_DEVOPS_FORCE_DEPLOY_V<major-version-number> CI/CD 变量来强制部署继续进行。

例如，如果你想在之前使用 v0.17.0 chart 的部署上部署 v2.0.0 chart，添加 AUTO_DEVOPS_FORCE_DEPLOY_V2。

早期采用者

如果你想使用最新的 beta 或不稳定版本的 auto-deploy-image，将最新的 Auto Deploy template 包含到你的 .gitlab-ci.yml 中：

include:
  - template: Auto-DevOps.gitlab-ci.yml
  - template: Jobs/Deploy.latest.gitlab-ci.yml

使用 beta 或不稳定的 auto-deploy-image 可能对你的环境造成不可恢复的损害。不要在重要项目或环境中测试它。

`auto-deploy-app` chart 的资源架构

v0 和 v1 chart 资源架构

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD;
accTitle: v0 and v1 chart resource architecture
accDescr: Shows the relationships between the components of the v0 and v1 charts.

subgraph gl-managed-app
  Z[Nginx Ingress]
  end
  Z[Nginx Ingress] --> A(Ingress);
  Z[Nginx Ingress] --> B(Ingress);
  subgraph stg namespace
  B[Ingress] --> H(...);
end

subgraph prd namespace
  A[Ingress] --> D(Service);
  D[Service] --> E(Deployment:Pods:app:stable);
  D[Service] --> F(Deployment:Pods:app:canary);
  D[Service] --> I(Deployment:Pods:app:rollout);
  E(Deployment:Pods:app:stable)---id1[(Pods:Postgres)]
  F(Deployment:Pods:app:canary)---id1[(Pods:Postgres)]
  I(Deployment:Pods:app:rollout)---id1[(Pods:Postgres)]
end

v2 chart 资源架构

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD;
accTitle: v2 chart resource architecture
accDescr: Shows the relationships between the components of the v2 chart.

subgraph gl-managed-app
  Z[Nginx Ingress]
  end
  Z[Nginx Ingress] --> A(Ingress);
  Z[Nginx Ingress] --> B(Ingress);
  Z[Nginx Ingress] --> |If canary is present or incremental rollout/|J(Canary Ingress);
  subgraph stg namespace
  B[Ingress] --> H(...);
end

subgraph prd namespace

  subgraph stable track
    A[Ingress] --> D[Service];
    D[Service] --> E(Deployment:Pods:app:stable);
  end

  subgraph canary track
    J(Canary Ingress) --> K[Service]
    K[Service] --> F(Deployment:Pods:app:canary);
  end

E(Deployment:Pods:app:stable)---id1[(Pods:Postgres)]
F(Deployment:Pods:app:canary)---id1[(Pods:Postgres)]
end

故障排除

主要版本不匹配警告

如果部署的 chart 与之前的主要版本不同，新的 chart 可能无法正确部署。这可能是由于架构更改造成的。如果发生这种情况，部署作业会失败并显示类似以下消息：

*************************************************************************************
                                   [WARNING]
检测到当前部署的 chart (auto-deploy-app-v0.7.0) 与之前部署的 chart (auto-deploy-app-v1.0.0) 之间存在主要版本差异。
新的主要版本可能与当前发布（production）不向后兼容。部署可能会失败或陷入不可恢复的状态。
...

要清除此错误消息并恢复部署，你必须执行以下操作之一：

手动升级 chart 版本。
使用特定的 chart 版本。

错误：`missing key "app.kubernetes.io/managed-by": must be set to "Helm"`

如果你的集群有使用 v1 auto-deploy-image 部署的部署，你可能会遇到以下错误：

Error: rendered manifests contain a resource that already exists. Unable to continue with install: Secret "production-postgresql" in namespace "<project-name>-production" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "production-postgresql"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "<project-name>-production"

这是因为之前的部署是使用 Helm2 部署的，与 Helm3 不兼容。要解决问题，请按照升级指南操作。