Customizing Auto DevOps

原文：https://docs.gitlab.com/ee/topics/autodevops/customize.html

• Custom buildpacks
  • Multiple buildpacks
• Custom Dockerfile
• Passing arguments to docker build
• Forward CI variables to the build environment
• Custom Helm Chart
• Customize values for Helm Chart
• Custom Helm chart per environment
• Customizing .gitlab-ci.yml
• Customizing the Kubernetes namespace
• Using components of Auto DevOps
• PostgreSQL database support
  • Upgrading PostgresSQL
  • Using external PostgreSQL database providers
• Environment variables
  • Build and deployment
  • Database
  • Disable jobs
  • Application secret variables
  • Advanced replica variables setup
  • Deploy policy for staging and production environments
  • Deploy policy for canary environments
  • Incremental rollout to production
  • Timed incremental rollout to production
• Auto DevOps banner

Customizing Auto DevOps

尽管Auto DevOps提供了很好的默认设置来帮助您入门，但是您可以自定义几乎所有内容以满足您的需求. Auto DevOps 提供了从自定义buildpacks到Dockerfiles和Helm 图表的所有内容 . 您甚至可以将完整的CI / CD 配置复制到您的项目中，以启用暂存和 Canary 部署等.

Custom buildpacks

如果您的项目无法自动检测到构建包，或者要使用自定义构建包，则可以在项目中使用项目变量或.buildpacks文件覆盖.buildpacks ：

• 项目变量 -使用要使用的 buildpack 的 URL 创建项目变量BUILDPACK_URL .
• .buildpacks文件 -在项目的存储库中添加一个名为.buildpacks的文件，并添加要在文件中一行使用的 buildpack 的 URL. 如果要使用多个 buildpack，请每行输入一个 buildpack.

buildpack URL 可以指向 Git 存储库 URL 或 tarball URL. 对于 Git 存储库，您可以通过将#<ref>附加到 Git 存储库 URL 来指向特定的 Git 引用（例如，提交 SHA，标记名称或分支名称）. 例如：

• 标签v142 ： https://github.com/heroku/heroku-buildpack-ruby.git#v142 : https://github.com/heroku/heroku-buildpack-ruby.git#v142 .
• 分支mybranch ： https://github.com/heroku/heroku-buildpack-ruby.git#mybranch : https://github.com/heroku/heroku-buildpack-ruby.git#mybranch .
• 提交 SHA f97d8a8ab49 ： https://github.com/heroku/heroku-buildpack-ruby.git#f97d8a8ab49 : https://github.com/heroku/heroku-buildpack-ruby.git#f97d8a8ab49 .

Multiple buildpacks

Auto DevOps 不完全支持使用多个 buildpack，因为在使用.buildpacks文件时，自动测试将不起作用. 在后端用于解析.buildpacks文件的 buildpack heroku-buildpack-multi没有提供必要的命令bin/test-compile和bin/test .

If your goal is to use only a single custom buildpack, you should provide the project variable BUILDPACK_URL instead.

Custom Dockerfile

在 GitLab 13.2中添加了对DOCKERFILE_PATH支持

如果您的项目在项目存储库的根目录中有一个Dockerfile ，则 Auto DevOps 会基于 Dockerfile 而不是使用 buildpacks 构建 Docker 映像. 这样可以更快，并产生较小的映像，尤其是在您的 Dockerfile 基于Alpine 的情况下 .

如果设置DOCKERFILE_PATH CI 变量，则”自动构建”将在其中查找 Dockerfile.

Passing arguments to docker build

可以使用AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS项目变量将参数传递给AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS docker build命令. 例如，要基于ruby:alpine而不是默认的ruby:latest构建 Docker 映像：

1. Set AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS to --build-arg=RUBY_VERSION=alpine.

2. 将以下内容添加到自定义Dockerfile ：

   ARG RUBY_VERSION=latest
   FROM ruby:$RUBY_VERSION
   # ... put your stuff here

注意：如果需要传递复杂的值（例如换行符和空格）， 请使用 Base64 编码. 由于 Auto DevOps 如何使用自变量，此类未经编码的复杂值可能导致转义问题.警告：尽可能避免将秘密作为 Docker 构建参数传递，因为它们可能会保留在映像中. 有关详细信息，请参见有关最佳实践的讨论 .

Forward CI variables to the build environment

在 GitLab 12.3 中引入 ，但在 11.9 及更高版本中可用.

可以使用AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES CI 变量将 CI 变量转发到构建环境中. 转发的变量应在逗号分隔的列表中按名称指定. 例如，要转发变量CI_COMMIT_SHA和CI_ENVIRONMENT_NAME ，请将AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES设置为CI_COMMIT_SHA,CI_ENVIRONMENT_NAME .

• 使用 Buildpacks 时，转发的变量将自动用作环境变量.

• 使用Dockerfile ，需要执行以下附加步骤：

  1. 通过将以下代码添加到文件顶部来激活实验性Dockerfile语法：

     # syntax = docker/dockerfile:experimental

  2. 要在任何可用的秘密RUN $COMMAND在Dockerfile ，秘密文件和源安装运行之前，它$COMMAND ：

     RUN --mount=type=secret,id=auto-devops-build-secrets . /run/secrets/auto-devops-build-secrets && $COMMAND

注意：设置AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES ，Auto DevOps 会启用实验性Docker BuildKit功能以使用--secret标志.

Custom Helm Chart

Auto DevOps 使用Helm将您的应用程序部署到 Kubernetes. 您可以通过将图表捆绑到项目存储库中或通过指定项目变量来覆盖使用的 Helm 图表：

• 捆绑图 -如果您的项目中有一个带有Chart.yaml文件的./chart目录，则 Auto DevOps 将检测到该图并使用它代替默认图 ，从而使您能够精确地控制应用程序的部署方式.
• 项目变量 -创建一个项目变量 AUTO_DEVOPS_CHART有一个自定义图表的 URL 来使用，或创建两个项目变量： AUTO_DEVOPS_CHART_REPOSITORY有一个自定义图表库的 URL，并AUTO_DEVOPS_CHART与路径图.

Customize values for Helm Chart

介绍在 GitLab 12.6， .gitlab/auto-deploy-values.yaml将默认为头盔升级使用.

您可以通过以下任一方式覆盖默认 Helm 图表中 values.yaml文件中的默认值 ：

• 将名为.gitlab/auto-deploy-values.yaml的文件添加到您的存储库，如果找到，该文件将自动使用.
• 将具有不同名称或路径的文件添加到存储库，并使用路径和名称设置HELM_UPGRADE_VALUES_FILE 环境变量 .

注：对于 GitLab 12.5 和更早的版本，使用HELM_UPGRADE_EXTRA_ARGS环境变量设置以覆盖默认图表值HELM_UPGRADE_EXTRA_ARGS到--values <my-values.yaml>

Custom Helm chart per environment

您可以通过将环境变量定义为所需环境来指定每个环境使用自定义 Helm 图表. 请参阅限制变量的环境范围 .

Customizing .gitlab-ci.yml

Auto DevOps 是完全可自定义的，因为Auto DevOps 模板只是.gitlab-ci.yml文件的实现，并且仅使用任何.gitlab-ci.yml实现的.gitlab-ci.yml .

要修改 Auto DevOps 使用的 CI / CD 管道，请include模板 ，并根据需要通过向包含以下内容的存储库的根目录中添加.gitlab-ci.yml文件来自定义它：

include:
  - template: Auto-DevOps.gitlab-ci.yml

添加您的更改，您的添加将使用include所描述的行为与Auto DevOps 模板合并.

如果您需要专门删除文件的一部分，还可以将Auto DevOps 模板的内容复制并粘贴到您的项目中，并根据需要进行编辑.

Customizing the Kubernetes namespace

在 GitLab 12.6 中引入 .

对于不受 GitLab 管理的集群，可以通过指定environment:kubernetes:namespace来自定义.gitlab-ci.yml的environment:kubernetes:namespace . 例如，以下配置将覆盖用于production部署的名称空间：

include:
  - template: Auto-DevOps.gitlab-ci.yml
production:
  environment:
    kubernetes:
      namespace: production

使用 Auto DevOps 部署到自定义名称空间时，群集随附的服务帐户至少需要名称空间内的edit角色.

• 如果服务帐户可以创建名称空间，则可以按需创建名称空间.
• 否则，名称空间必须在部署之前存在.

Using components of Auto DevOps

如果仅需要 Auto DevOps 提供的功能的子集，则可以将各个 Auto DevOps 作业包括在自己的.gitlab-ci.yml . 每个组件作业都依赖于一个阶段，该阶段应该在包含模板的.gitlab-ci.yml中定义.

例如，要使用自动构建 ，可以将以下内容添加到.gitlab-ci.yml ：

stages:
  - build
include:
  - template: Jobs/Build.gitlab-ci.yml

有关可用作业的信息，请参见Auto DevOps 模板 .

弃用：从GitLab 13.0开始，使用only或except语法的 Auto DevOps 模板将切换到rules语法. 如果您.gitlab-ci.yml扩展了这些汽车的 DevOps 模板和覆盖only或except关键字，您必须迁移模板使用rules语法的基本模板被迁移到使用后rules语法. 对于尚不能迁移的用户，您可以选择将模板固定到基于 GitLab 12.10 的模板 .

PostgreSQL database support

为了支持需要数据库的应用程序，默认情况下配置PostgreSQL . 访问数据库的凭据已预先配置，但可以通过设置关联变量进行自定义. 您可以使用这些凭据来定义DATABASE_URL ：

postgres://user:password@postgres-host:postgres-port/postgres-database

Upgrading PostgresSQL

弃用：用于控制默认AUTO_DEVOPS_POSTGRES_CHANNEL配置 PostgreSQL 的变量AUTO_DEVOPS_POSTGRES_CHANNEL在GitLab 13.0 中已更改为2 . 要继续使用旧的 PostgreSQL，请将AUTO_DEVOPS_POSTGRES_CHANNEL变量设置为1 .

用于配置 PostgreSQL 的图表的版本：

• 在 GitLab 13.0 和更高版本中为 8.2.1，但如果需要可以将其设置回 0.7.1.
• 可以在 GitLab 12.9 和 12.10 中设置为 0.7.1 至 8.2.1.
• 在 GitLab 12.8 及更早版本中为 0.7.1.

GitLab 鼓励用户将其数据库迁移到较新的 PostgreSQL.

Using external PostgreSQL database providers

尽管 Auto DevOps 为生产环境提供了对 PostgreSQL 容器的开箱即用支持，但在某些情况下，它可能不够安全或没有弹性，您可能要使用外部托管提供程序（例如 AWS Relational Database）服务）（适用于 PostgreSQL）.

您必须在项目的 CI / CD 设置中为POSTGRES_ENABLED和DATABASE_URL定义环境范围的变量：

1. 使用范围内的环境变量针对所需环境禁用内置 PostgreSQL 安装. 对于此用例，可能只需要将production添加到此列表中. 用于 Review Apps 和登台的内置 PostgreSQL 设置就足够了.

   

2. Define the DATABASE_URL CI variable as a scoped environment variable that will be available to your application. This should be a URL in the following format:

   postgres://user:password@postgres-host:postgres-port/postgres-database

您必须确保您的 Kubernetes 集群可以访问托管 PostgreSQL 的任何地方的网络.

Environment variables

以下变量可用于设置 Auto DevOps 域，提供自定义 Helm 图表或缩放应用程序. PostgreSQL 也可以自定义，您可以使用自定义 buildpack .

Build and deployment

下表列出了与构建和部署应用程序有关的变量.

提示：使用项目变量设置副本变量后 ，可以通过重新部署来缩放应用程序.注意：您不应该直接扩展使用 Kubernetes 您的应用程序. 这可能会导致 Helm 无法检测到更改而造成混乱，随后使用 Auto DevOps 进行的部署可能会撤消您的更改.

Database

下表列出了与数据库有关的变量.

Disable jobs

下表列出了用于禁用作业的变量.

Application secret variables

在 GitLab 11.7 中引入 .

某些应用程序需要定义可由部署的应用程序访问的秘密变量. Auto DevOps 会检测以K8S_SECRET_开头的变量，并将这些带前缀的变量作为环境变量提供给已部署的应用程序.

要配置您的应用程序变量：

1. Go to your project’s 设置> CI / CD, then expand the Variables section.

2. 创建一个 CI / CD 变量，确保密钥以K8S_SECRET_为前缀. 例如，您可以使用键K8S_SECRET_RAILS_MASTER_KEY创建一个变量.

3. 通过手动创建新管道或将代码更改推送到 GitLab 来运行 Auto DevOps 管道.

Auto DevOps 管道将使用您的应用程序秘密变量来填充 Kubernetes 秘密. 这个秘密在每个环境中都是唯一的. 部署应用程序时，机密将作为环境变量加载到运行应用程序的容器中. 在上面的示例之后，您可以在下面看到包含RAILS_MASTER_KEY变量的机密.

$ kubectl get secret production-secret -n minimal-ruby-app-54 -o yaml
apiVersion: v1
data:
  RAILS_MASTER_KEY: MTIzNC10ZXN0
kind: Secret
metadata:
  creationTimestamp: 2018-12-20T01:48:26Z
  name: production-secret
  namespace: minimal-ruby-app-54
  resourceVersion: "429422"
  selfLink: /api/v1/namespaces/minimal-ruby-app-54/secrets/production-secret
  uid: 57ac2bfd-03f9-11e9-b812-42010a9400e4
type: Opaque

通常认为环境变量在 Kubernetes 容器中是不可变的. 如果在不更改任何代码的情况下更新应用程序机密，然后手动创建新管道，则会发现任何正在运行的应用程序吊舱都不会具有更新后的机密. 要更新机密，请执行以下任一操作：

• 将代码更新推送到 GitLab，以强制 Kubernetes 部署重新创建 Pod.
• 手动删除正在运行的 Pod，以使 Kubernetes 创建具有更新机密的新 Pod.

注意：由于当前 Auto DevOps 脚本环境的限制，当前不支持具有多行值的变量.

Advanced replica variables setup

除了上面提到的两个与副本相关的生产变量之外，您还可以将其他变量用于不同的环境.

Kubernetes 的标签名为track ，GitLab CI / CD 环境名称和副本环境变量被组合为TRACK_ENV_REPLICAS格式，使您能够定义自己的变量来扩展 Pod 的副本：

• TRACK ：Helm Chart 应用程序定义中track Kubernetes 标签的大写值. 如果未设置，则不会考虑到变量名.
• ENV ：部署作业的大写环境名称，在.gitlab-ci.yml设置.

在下面的示例中，环境的名称为qa ，并且部署了轨道foo ，这将导致一个名为FOO_QA_REPLICAS的环境变量：

QA testing:
  stage: deploy
  environment:
    name: qa
  script:
    - deploy foo

还必须在应用程序的 Helm 图表中定义被引用的foo轨道，例如：

replicaCount: 1
image:
  repository: gitlab.example.com/group/project
  tag: stable
  pullPolicy: Always
  secrets:
    - name: gitlab-registry
application:
  track: foo
  tier: web
service:
  enabled: true
  name: web
  type: ClusterIP
  url: http://my.host.com/
  externalPort: 5000
  internalPort: 5000

Deploy policy for staging and production environments

在 GitLab 10.8 中引入 .

提示：您也可以在项目的设置中进行设置 .

Auto DevOps 的正常行为是使用连续部署，每次在默认分支上运行新管道时，都会自动推送到production环境. 但是，在某些情况下，您可能需要使用暂存环境并手动部署到生产环境. 对于这种情况，引入了STAGING_ENABLED环境变量.

如果您定义STAGING_ENABLED ，例如将STAGING_ENABLED设置为1作为 CI / CD 变量，则 GitLab 会自动将应用程序部署到staging环境，并在准备好手动部署到生产环境时为您创建production_manual作业.

Deploy policy for canary environments

在 GitLab 11.0 中引入 .

在将任何更改部署到生产之前，可以使用Canary 环境 .

如果您在项目中定义CANARY_ENABLED ，例如将CANARY_ENABLED设置为1作为 CI / CD 变量，则会创建两个手动作业：

• canary -将应用程序部署到金丝雀环境.
• production_manual手动将应用程序部署到生产环境.

Incremental rollout to production

在 GitLab 10.8 中引入 .

提示：您也可以在项目的设置中进行设置 .

当您准备将新版本的应用程序部署到生产环境时，您可能希望使用增量部署将最新的代码替换为少数 Pod，以检查应用程序的行为，然后手动将部署率提高到 100％ .

如果在项目中将INCREMENTAL_ROLLOUT_MODE设置为manual ，则将创建 4 个不同的手动作业，而不是标准production作业：

1. rollout 10%
2. rollout 25%
3. rollout 50%
4. rollout 100%

该百分比基于REPLICAS变量，并定义了您要用于部署的 Pod 数量. 如果该值为10 ，并且您运行10%部署作业，那么将有1新容器+ 9个旧容器.

要开始工作，请点击播放图标（ ）旁边的职位名称. 您不需要从10%增加到100% ，您可以跳到所需的任何工作. 您也可以在达到100%之前通过执行较低百分比的作业来缩小规模. 一旦达到100% ，您将无法缩小规模，并且必须通过使用环境页面中的” 回滚”按钮重新部署旧版本来进行回滚 .

在下面，您可以看到如果定义了发布或登台变量，管道的外观.

没有INCREMENTAL_ROLLOUT_MODE和STAGING_ENABLED ：

没有INCREMENTAL_ROLLOUT_MODE和STAGING_ENABLED ：

在将INCREMENTAL_ROLLOUT_MODE设置为manual且没有STAGING_ENABLED情况STAGING_ENABLED ：

将INCREMENTAL_ROLLOUT_MODE设置为manual ，并将STAGING_ENABLED

注意：在 GitLab 11.4 之前， INCREMENTAL_ROLLOUT_ENABLED环境变量的存在启用了此功能. 此配置已弃用，以后将被删除.

Timed incremental rollout to production

在 GitLab 11.4 中引入 .

提示：您也可以在项目的设置中进行设置 .

此配置基于向生产的增量部署 .

除以下内容外，其他所有行为均相同：

• 要启用它，请将INCREMENTAL_ROLLOUT_MODE变量设置为timed .

• Instead of the standard production job, the following jobs are created with a 5 minute delay between each:

  1. timed rollout 10%
  2. timed rollout 25%
  3. timed rollout 50%
  4. timed rollout 100%

Auto DevOps banner

在未启用自动 DevOps 的情况下，对新项目具有维护者或更高权限的用户将显示以下 Auto DevOps 标语：

可以为以下内容禁用横幅：

• 用户，当他们自己关闭它时.
• 通过显式禁用 Auto DevOps 的项目 .

• 整个 GitLab 实例：

  • 由管理员在 Rails 控制台中运行以下命令：

     Feature . enable ( :auto_devops_banner_disabled )

  • 通过带有管理员访问令牌的 REST API：

     curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled