通过应用交付管理应用

标准

本页面将引导您通过应用交付完成 NGINX 的部署配置。该部署在 staging 和 prod 两个环境中运行。 prod 环境使用常规配置，而 staging 使用略微修改的配置。

要求

如需完成此教程，您需要具有以下各项：

在本地安装的 Git 2.19.2 或更高版本。
具有创建私有代码库权限的 GitHub 或 GitLab 帐号。应用交付仅支持 GitHub 和 GitLab 代码库。
运行 GKE 1.15 或更高版本的集群。
拥有 clusterAdmin 特权的用户。
已在本地安装 Kustomize。您可以按照安装指南操作。
如果要在部署代码库中验证 Kubernetes 配置文件，您必须安装 Docker。

准备工作

在开始之前，请确保您已执行以下任务：

确保您已启用 Google Kubernetes Engine API。

启用 Google Kubernetes Engine API

确保您已安装 Cloud SDK。
使用以下方法之一为您的项目设置默认 gcloud 命令行工具设置：

使用 gcloud init（如果您想要在系统引导下完成项目默认设置）。
使用 gcloud config（如果您想要单独设置项目 ID、可用区和区域。

gcloud init

运行 gcloud init 并按照说明操作：
```
gcloud init
```
如果您要在远程服务器上使用 SSH，请使用 --console-only 标志来防止命令启动浏览器：
```
gcloud init --console-only
```
按照说明授权 gcloud 工具使用您的 Google Cloud 帐号。
创建新配置或选择现有配置。
选择 Google Cloud 项目。
选择默认的 Compute Engine 可用区。
选择默认的 Compute Engine 区域。

注意：您可以使用 --project、--zone 和 --region 标志在 gcloud 工具中替换这些默认设置。

gcloud config

设置默认项目 ID：
```
gcloud config set project PROJECT_ID
```
设置默认的 Compute Engine 区域（例如 us-central1）：
```
gcloud config set compute/region COMPUTE_REGION
```
设置默认的 Compute Engine 可用区（例如 us-central1-c）：
```
gcloud config set compute/zone COMPUTE_ZONE
```
将 gcloud 更新到最新版本：
```
gcloud components update
```

注意：您可以使用 --project、--zone 和 --region 标志在 gcloud 工具中替换这些默认设置。

通过设置默认位置，您可以避免 gcloud 工具中出现以下错误：One of [--zone, --region] must be supplied: Please specify location。

将 SSH 密钥添加到您的 GitHub 或 GitLab 帐号。
测试您的 ssh 密钥：

GitHub
sh ssh -T git@github.com

GitLab
sh ssh -T git@gitlab.com

系统可能会要求您确认连接详细信息或密钥密码。如果连接成功，终端上会输出一条消息。

设置应用交付

如需使用应用交付，您必须执行以下操作：

创建启用了应用交付的新集群，或在运行 1.15 或更高版本的现有 GKE 集群上启用应用交付。
安装应用交付命令行工具 appctl。

创建启用了应用交付的新集群

您可以使用 gcloud 工具或 Cloud Console 创建一个启用了应用交付的新集群。

gcloud

创建集群：

gcloud beta container clusters create CLUSTER_NAME \
      --cluster-version CLUSTER_VERSION\
      --addons ApplicationManager

请替换以下内容：

CLUSTER_NAME：新集群的名称。
CLUSTER_VERSION：新集群的版本。必须为 GKE 1.15 或更高版本。

控制台

转到 Cloud Console 中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
点击创建。
在标准部分中，点击配置。
为集群指定名称。
选择 1.15.x 或更高版本的控制层面版本。
根据需要配置集群。
在导航窗格的集群下，点击功能。
选中启用应用管理器复选框。
点击创建。

在现有集群上启用应用交付

您可以使用 gcloud 工具或 Cloud Console 在现有集群上启用应用交付。

gcloud

如需在现有集群上启用应用交付，请运行以下命令：

gcloud beta container clusters update CLUSTER_NAME \
      --update-addons ApplicationManager=ENABLED

将 CLUSTER_NAME 替换为 GKE 集群的名称。

控制台

转到 Cloud Console 中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
在集群列表中，点击您要修改的集群的名称。
在功能下，点击应用管理器字段旁边的 修改应用管理器。
选中启用应用管理器复选框。
点击保存更改。

确认安装

如需检查应用交付的安装状态，请执行以下操作：

检查 Deployment 状态：

kubectl get deployment application-controller-manager -n application-system

输出内容类似如下：

NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
application-controller-manager   2/2     2            2           1h

此 application-controller-manager Deployment 中应该有两个 pod。

检查 StatefulSet 状态：

kubectl get statefulset kalm-controller-manager -n kalm-system

输出内容类似如下：

NAME                      READY   AGE
kalm-controller-manager   1/1     1h

此 kalm-controller-manager StatefulSet 中应包含一个准备就绪的 pod。

安装 appctl

如需安装应用交付命令行工具 appctl，请使用 gcloud 工具安装 pkg。

gcloud components install pkg

在集群上启用应用交付和安装 pkg 之后，您即可开始部署第一个应用了。

部署应用

如需部署应用，请执行以下操作：

创建新的 Git 代码库或初始化现有代码库。
创建库配置。
为您的部署创建一个或多个环境。
（可选）将配置叠加层应用到您的应用代码库中的环境。
以拉取请求或合并请求的形式创建候选版本。
部署版本。

创建新的代码库

在 GitHub 或 GitLab 上使用 appctl 创建代码库以用于应用交付。

切换要在其中创建应用目录的目录。
使用 appctl 创建您的应用交付代码库。
GitHub
运行以下命令：
```
appctl init APP_NAME \
    --app-config-repo=github.com/USERNAME/APP_NAME
```
请替换以下内容：
- APP_NAME：您的应用的名称。
- USERNAME：您的 GitHub 用户名。
例如，如果您的 GitHub 用户名是 octocat，并且您想要创建一个名为 myapp 的应用，请运行以下命令：
```
appctl init myapp \
    --app-config-repo=github.com/octocat/myapp
```
GitLab
运行以下命令：
```
appctl init APP_NAME \
    --app-config-repo=gitlab.com/USERNAME/APP_NAME
```
请替换以下内容：
- APP_NAME：您的应用的名称。
- USERNAME：您的 GitLab 用户名。
例如，如果您的 GitLab 用户名是 alice，并且您想要创建一个名为 myapp 的应用，请运行以下命令：
```
appctl init myapp \
    --app-config-repo=gitlab.com/alice/myapp
```
appctl 会提示您确认新的私有代码库。

注意：Git 可能会提示您提供其他登录信息。

appctl 会创建两个远程私有 Git 代码库：

应用代码库 github.com/USERNAME/APP_NAME。该代码库会克隆到当前目录。
部署代码库 github.com/USERNAME/APP_NAME-deployment。本地部署代码库存储在 ./APP_NAME/.deployment 中。

如需详细了解这些代码库的内容和结构，请参阅应用交付概念指南。

初始化现有代码库

如果您已有代码库，则可以在 GitHub 或 GitLab 上使用 appctl 初始化该代码库以用于应用交付。

切换到要在其中创建应用目录的目录。
运行 appctl init 命令，该命令会创建一个名为 APP_NAME 的目录并在其中克隆代码库。

appctl init 会在存储在代码库 ./config 目录的配置文件中初始化 Kustomize 库层。您可以使用 --config-path 标志指定其他配置路径。

默认情况下，appctl init 使用 github.com/USERNAME/APP_NAME-deployment 作为部署代码库的网址。您可以使用 --deployment-repo 标志指定其他网址。如果部署代码库不存在，则 appctl 命令会创建一个。

注意：如果本地路径中已存在 APP_NAME 目录，则 appctl 需要 APP_NAME 目录进行 Git 初始化，并进行与 app-config-repo 相匹配的远程引用。此外，如果 APP_NAME 目录包含子目录 .deployment，则 .deployment 目录将进行 Git 初始化，并进行与 deployment-repo 相匹配的远程引用。您可以使用 --deployment-repo 标志替换默认值。
GitHub
```
appctl init APP_NAME \
      --app-config-repo=github.com/USERNAME/APP_NAME \
      [--config-path=CONFIG_PATH]
```
请替换以下内容：
- APP_NAME：您的应用的名称。
- USERNAME：您的 GitHub 用户名。
- CONFIG_PATH：代码库配置目录的可选路径。如果省略，则默认为 ./config。
例如，如果现有应用配置代码库为 https://github.com/octocat/myapp 且您希望部署代码库为 https://github.com/octocat/myapp-deploy，请运行以下命令：
```
appctl init myapp \
    --app-config-repo=github.com/octocat/myapp
```
GitLab
```
appctl init APP_NAME \
    --app-config-repo=gitlab.com/USERNAME/APP_NAME \
    [--config-path=CONFIG_PATH]
```
请替换以下内容：
- APP_NAME：您的应用的名称。
- USERNAME：您的 GitLab 用户名。
- CONFIG_PATH：代码库配置目录的可选路径。如果省略，则默认为 ./config。
例如，如果现有应用配置代码库为 gitlab.com/alice/myapp，请运行以下命令：
```
appctl init myapp --app-config-repo=gitlab.com/alice/myapp
```

创建库配置

为您的 Kubernetes 工作负载创建配置。这可以是任何有效的 Kubernetes 部署。

以下配置定义了一个名为 nginx 的应用，该应用部署了 3 个 nginx 容器副本。将配置复制到 config/base/myapp.yaml 文件中。如果要启用 LoadBalancer，请取消对 type: LoadBalancer 行的注释。

#myapp/config/base/myapp.yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  # if your cluster supports it, uncomment the following to automatically create
  # an external load-balanced IP for the frontend service.
  # type: LoadBalancer
  ports:
    - port: 80
  selector:
    app: nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80

配置应用交付以将此配置应用到库。将以下内容粘贴到 config/base/kustomization.yaml 中。
```
#config/base/kustomization.yaml

resources:
  - myapp.yaml
```

测试并推送配置

在应用代码库目录中，使用 kustomize build 测试您的配置：
```
kustomize build config/base/
```
注意：appctl 使用内置的 Kusmomize 来避免版本冲突。它可以与本地 Kustomize 版本不同，也可以不同于通过 gcloud components install pkg 安装的 Kustomize。运行 appctl version 以查看内置的 Kustomize 版本，然后运行 kustomize version 以查看本地 Kustomize 版本。
如果配置有效，则 kustomize 将输出 YAML（在应用后会部署到集群）。

验证 YAML 之后，在应用代码库中创建并推送提交：

git add .
git commit -m "Creating APP_NAME"
git push origin master

添加版本环境

应用交付会将您的应用部署到环境中。您可以使用 appctl 为您的版本添加环境。

切换至您的应用代码库根目录。
使用 appctl 创建环境：
```
appctl env add ENVIRONMENT_NAME \
    --cluster=CLUSTER_NAME
```
请替换以下内容：
- ENVIRONMENT_NAME：新环境的名称。
- CLUSTER_NAME：您的集群的名称。
appctl 会创建一个包含支架结构式 Kustomize 配置的 Git 提交。

您可以使用 --namespace 为此应用的版本环境指定命名空间名称。如果不是，则默认命名空间名称为 APP_NAME-ENVIRONMENT_NAME。

例如，如需使用默认命名空间名称将 staging 和 prod 环境添加到集群 application-cluster 中，请运行以下命令：
```
appctl env add staging --cluster=application-cluster
appctl env add prod --cluster=application-cluster
```
如需将 test 命名空间中的 test 环境添加到集群application-cluster 中，请运行以下命令：
```
appctl env add test --cluster=application-cluster --namespace=test
```
添加环境时，您需要考虑此环境的部署代码库是否需要拉取请求和代码审核。默认情况下，系统会创建拉取请求。如果环境不是生产关键型且不需要代码审核，则可以跳过使用 --review-required=false 创建拉取请求。

例如，如需添加不需要拉取请求的 test 环境，请运行以下命令：
```
appctl env add test \
    --cluster=application-cluster \
    --review-required=false
```
注意：appctl 可能会提示您提供 Git 代码库的访问令牌。
（可选）使用 git log 查看应用交付在 Git 代码库中所做的更改：
```
git log -p *
```
将配置推送到您的应用代码库：
```
git push origin master
```

可选：检查部署代码库

打开部署代码库的 GitHub 或 GitLab 页面。例如，如果您的 GitHub 用户名是 octocat，并且您创建了一个名为 myapp 的应用，则网址为 https://github.com/octocat/myapp-deployment。在此页面上，您可以看到为每个环境创建的分支。

部署环境

如需部署带有应用交付的环境，请执行以下操作：

使用 git tag 创建一个版本，然后推送该标记：
```
git tag VERSION
git push origin VERSION
```
将 VERSION 替换为应用的版本号。

注意：我们建议您使用语义版本控制处理版本号。利用此版本控制系统，您可以轻松地在 GitHub 或 GitLab 页面上对版本进行排序。
例如，如需推送版本 v0.1.0，请运行以下命令：
```
git tag v0.1.0
git push origin v0.1.0
```
```
使用 appctl prepare 来指定当前标记的版本，并在部署代码库中生成拉取请求以供审核。

注意：appctl prepare 会重置 kubeconfig（包括默认上下文和命名空间）。如果您更改了默认上下文，则在使用 appctl 之后需要重新应用此更改。
```
appctl prepare ENVIRONMENT_NAME
```
例如，如需使用 staging 环境，请运行以下命令：
```
appctl prepare staging \
    --validate=true
```
此命令会触发 kpt 验证函数 gcr.io/kustomize-functions/example-validator，以验证推送到部署代码库的更改。

kpt 由 gcloud components install pkg 安装。此验证函数在后台运行 kubeval，使用 Kubernetes OpenAPI 规范中的架构来验证 Kubernetes 配置文件。

如需运行 kpt prepare staging --validate，您必须在机器上安装 Docker。

默认情况下，--validate 标志处于停用状态。

注意：如果卸载了 kpt，则启用 --validate 标志会导致错误。
如果 appctl 完成了向部署代码库进行的提交，则它会输出一个拉取请求网址，如下所示：
```
Created a "Pull Request": "https://github.com/octocat/myapp-deployment/pull/[Pull_Request_ID]"
```
注意：如果环境是使用 --review-required=false 创建的，则 appctl prepare 将跳过创建拉取请求并将更改推送到部署代码库。您没有看到拉取请求链接。
使用 GitHub 或 GitLab 审核并批准拉取请求。

警告：在 GitHub 或 GitLab 上合并拉取请求时，请使用合并提交。应用交付无法识别“压缩并合并”或“变基并合并”提交。
拉取请求获得批准后，使用 appctl apply 完成部署：
```
appctl apply ENVIRONMENT_NAME
```
请将 ENVIRONMENT_NAME 替换为您的环境名称：

例如，如需将更改部署到 staging 环境，请运行以下命令：
```
appctl apply staging
```
使用 kubectl 或在 Cloud Console 中确认您的应用正在运行。
kubectl
使用 kubectl describe 查看应用的状态：
```
kubectl get releasetracks.app.gke.io APP_NAME \
    --n NAMESPACE \
    -w
```
替换以下内容：
- APP_NAME：您的应用代码库的名称。
- NAMESPACE：您在创建环境时指定的命名空间名称。如果未指定命名空间名称，则默认为 APP_NAME-ENVIRONMENT_NAME。
例如，如需检查 myapp 应用的 staging 环境的状态，请运行以下命令：
```
kubectl get releasetracks.app.gke.io myapp -n myapp-staging
```
如需检查 env add --namespace test 之前添加的 test 环境的状态，请运行以下命令：
```
kubectl get releasetracks.app.gke.io myapp -n test
```
控制台
如需查看通过应用交付部署的应用的状态和版本信息，请参阅 Cloud Console 上的 GKE 应用页面。

提升版本

如需将候选版本从一个环境提升到另一个环境，请运行以下命令：
```
appctl prepare TARGET_ENVIRONMENT \
    --from-env=SOURCE_ENVIRONMENT
```
请替换以下内容：
- TARGET_ENVIRONMENT：要向其部署候选版本的环境的名称。
- SOURCE_ENVIRONMENT：当前环境的名称。
例如，如需将 staging 提升为 prod，请运行以下命令：
```
appctl prepare prod --from-env=staging
```
使用 GitHub 或 GitLab 审核并批准拉取请求。
如需将候选版本部署到目标环境，请运行以下命令：
```
appctl apply TARGET_ENVIRONMENT
```
例如，如需部署到 prod 环境，请运行以下命令：
```
appctl apply prod
```

在 Cloud Console 中查看环境

部署环境的应用后，您可以在“GKE 应用”页面上查看该环境。此页面包含其环境使用英文括号括住的应用清单。下面是一个应用 myapp 的屏幕截图，其中包含两个环境 staging 和 prod。此页面还显示了每个环境的命名空间、集群和版本。

应用页面的屏幕截图。

如需查看应用的详细信息（例如 Git 标记、组件和环境列表），请点击应用名称。以下屏幕截图显示了 myapp 的详细信息。

应用详细信息页面的屏幕截图。

更改环境配置

该部分假定您已按照先前步骤配置了一个 staging 环境。您可能需要根据您的用途调整这些说明。

在该部分中，您将使用 kustomize 叠加层更改 staging 环境的参数。完成更改后，您将在 Git 中推送和标记您所做的更改。应用交付将更新您的集群。

创建名为 config/envs/staging/patch-replicas.yaml 的文件，并将以下文本复制到其中.这会将 staging 环境中的配置更新为运行一个副本而不是三个副本。
```
#config/envs/staging/patch-replicas.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
```
注意：您必须提供 apiVersion 值、kind 值和 metadata.name 值。

修改 config/envs/staging/kustomization.yaml 文件并将 patch-replicas.yaml 添加到名为 patchesStrategicMerge 的新集合中。

#config/envs/staging/kustomization.yaml
namespace: myapp-staging
bases:
   - ../../base
patchesStrategicMerge:
   - patch-replicas.yaml

您还可以在此叠加层中添加特定于环境的注释。以下示例添加了一个名为 oncall-team 的注释来添加此环境下的所有资源。如需了解详情，请参阅 Kustomize 文件字段。

#config/envs/staging/kustomization.yaml

#Don't change the namespace field
namespace: myapp-staging
bases:
   - ../../base
patchesStrategicMerge:
   - patch-replicas.yaml
commonAnnotations:
  oncall-team: staging-oncall@foo.bar

使用 kustomize build 测试您的配置：
```
kustomize build config/envs/staging/
```
添加并提交您的更改。
```
git add .
git commit -m "<var>COMMIT_MESSAGE</var>"
git push origin master
```
将 COMMIT_MESSAGE 替换为描述您的更改的消息。
使用 git tag 创建一个版本并推送该版本。
```
git tag VERSION
git push origin VERSION
```
将 VERSION 替换为所需的版本号。
使用 appctl prepare 在部署代码库中生成拉取请求以供审核：
```
appctl prepare ENVIRONMENT_NAME
```
点击相应链接，创建 GitHub 或 GitLab 拉取请求。
查看拉取请求的内容。应用交付进行涉及一行的更改，将 replicas 的值设置为 1。
使用 GitHub 或 GitLab 批准拉取请求。
使用 appctl apply 应用更改：
```
appctl apply staging
```

回滚配置更改

如需回滚到以前的版本，请运行以下命令：

appctl apply TARGET_ENVIRONMENT \
    --from-tag GIT_TAG

请替换以下内容：

TARGET_ENVIRONMENT：要在其中部署版本的环境的名称。
GIT_TAG：版本的标记的名称。

在脚本中使用 `appctl`

appctl 工具是交互式的，默认情况下要求用户输入。如果要在脚本、容器或流水线中运行 appctl，请将环境变量 APPCTL_INTERACTIVE 设置为 false。

例如，在 bash shell 中运行以下命令：

export APPCTL_INTERACTIVE=false

appctl help command 可提供有关特定 appctl 命令的信息。例如，如需获取有关 appctl prepare 的帮助，请运行 appctl help prepare。

卸载应用管理器

如需移除在集群中运行的应用，请删除使用新环境创建的所有 Namespace。

对于您的所有环境和集群，请重复以下命令：

切换到指定环境的集群：
```
kubectl config use-context ENVIRONMENT_CLUSTER_NAME
```
将 ENVIRONMENT_CLUSTER_NAME 替换为所选环境中的集群的名称。
删除此环境的应用运行的命名空间：
```
kubectl delete ns NAMESPACE
```
将 NAMESPACE 替换为您要删除的命名空间名称。默认值为 APP_NAME-ENVIRONMENT_NAME。
在 GitHub 或 GitLab，删除由 appctl 创建的两个 Git 代码库。
删除本地应用目录：
```
rm -rf myapp/
```
您可以通过 gcloud 或 Cloud Console 在集群中停用应用交付：
gcloud
```
gcloud beta container clusters update CLUSTER_NAME \
    --update-addons ApplicationManager=DISABLED
```
控制台
1. 转到 Cloud Console 中的 Google Kubernetes Engine 页面：
  
  转到 Google Kubernetes Engine
2. 在集群列表中，点击您要修改的集群的名称。
3. 在功能下，点击应用管理器字段旁边的 修改应用管理器。
4. 清除启用应用管理器复选框。
5. 点击保存更改。

后续步骤

详细了解 Kustomize。

通过应用交付管理应用

要求

准备工作

gcloud init

gcloud config

GitHub

GitLab

设置应用交付

创建启用了应用交付的新集群

gcloud

控制台

在现有集群上启用应用交付

gcloud

控制台

确认安装

安装 appctl

部署应用

创建新的代码库

GitHub

GitLab

初始化现有代码库

GitHub

GitLab

创建库配置

测试并推送配置

添加版本环境

可选：检查部署代码库

部署环境

kubectl

控制台

提升版本

在 Cloud Console 中查看环境

更改环境配置

回滚配置更改

在脚本中使用 appctl

卸载应用管理器

gcloud

控制台

后续步骤

在脚本中使用 `appctl`