Yusong

Appearance

GitLab Kubernetes Agent ​

文档用途

说明如何通过 GitLab Kubernetes Agent 来简化服务在 k8s 中的部署流程.

参考链接 ​

准备工作 ​

  • 有可访问的 k8s 集群 (本地测试可以使用 Docker Desktop 中自带的).
  • 确保在自己部署的 GitLab 中启用了 KAS 功能 (默认是启用的).
  • 确保开发设备中可以使用 kubectl 和 helm 这两个命令.

Agent 配置文件 ​

文件路径 ​

需要在代码仓库中创建 Agent 配置文件:
.gitlab/agents/[agent-name]/config.yaml

这里需要取个名字作为 agent-name, 在这篇文档中我们取名 k8s-connection.
配置文件中可以什么都不写, 等之后有配置需求的时候再做修改.

向其他仓库授权 ​

编辑 config.yaml 用于 授权, 详见 Authorize the Agent - GitLab Docs.
被授权的代码仓库就可以使用这个 GitLab Kubernetes Agent 访问对应的 k8s 集群.

yaml
ci_access:
  groups:
    - id: GROUP_PATH # 向某个 group 中所有的代码仓库授权
  projects:
    - id: REPOSITORY_PATH # 向某个代码仓库授权

连接 Kubernetes ​

操作流程 ​

打开代码仓库的 Operate / Kubernetes clusters 页面:

点击右上角的 Connect a cluster 按钮:

在弹窗中选择我们之前创建好的 Agent 配置文件:

在接下来的弹窗中会出现一些命令, 用于部署 GitLab Kubernetes Agent 至目标 k8s 集群.
弹窗中会出现 Agent access token, 最好不要保留这个 token, 建议在部署完成后立即丢弃.

Agent 部署完成后, 刷新当前页面, 应该就能看到 Connection status 为 Connected:

Token 泄露风险 ​

DANGER

如果 Agent access token 泄露, 攻击者将有权限获取当前代码仓库的源代码.
因此务必避免 token 泄露. 另外也建议使用单独的代码仓库来注册 Agent, 用来隔离源代码.

CI/CD 访问集群 ​

Job 示例 ​

INFO

请确保已经创建好了 Agent 配置文件, 并注册完成,
已经在目标 k8s 中部署了 GitLab Kubernetes Agent.

当一切都配置好之后, 就可以使用 CI/CD job 来访问 k8s 集群.

yaml
# 需要配合 executor 类型为 docker 的 gitlab-runner
log-pods-k8s:
  stage: deploy
  variables:
    # 把 "path/to/agent-configuration-project" 替换成仓库的路径,
    # 也就是代码仓库的 URL 中 "https://gitlab-domain/" 后面那部分.
    # 把 "your-agent-name" 替换成 agent 配置文件的名称,
    # 例如这篇文档中的 "k8s-connection".
    KUBE_CONTEXT: path/to/agent-configuration-project:your-agent-name
  image:
    name: bitnami/kubectl
    # 默认的 entrypoint 是 kubectl 命令.
    # 这里覆盖掉默认的 entrypoint, 使得 script 更易阅读.
    entrypoint: [""]
  script:
    - kubectl config use-context $KUBE_CONTEXT
    - kubectl get pods -A

获得授权 ​

不只 "配置文件所在的代码仓库" 可以访问 k8s, 所有 被授权 的代码仓库也可以执行上述 Job.
在被授权的代码仓库的 Operate / Kubernetes cluster 页面中可以看到:

设计思路 ​

单仓库 ​

单仓库实现起来最简单, 但 不适合 生产环境, 生产环境中建议使用多仓库方案.
因为 "用于连接 k8s 集群的代码仓库" 应该被共享 (避免浪费 k8s 中的计算资源).
同时考虑到上文所述的 Agent access token 泄露风险, 最好将源代码放在不同的代码仓库.

双仓库 ​

对于不需要使用 helm 的工程而言, 推荐使用双仓库方案.
注意需要在 "用于连接 k8s 集群的代码仓库" (agent repo) 中授权.
另外要将用于操控 k8s 的 CI/CD job 设置为手动执行.

隐藏 agent repo 的示意图 (更一目了然)

三仓库 ​

对于需要使用 helm 的工程, 推荐使用三仓库方案.
相比于双仓库方案, 三仓库方案多了一个代码仓库专门用于编写 helm chart.
并使用 package registry 作为 Chart Museum (支持上传和下载 chart).

无论是双仓库方案还是三仓库方案, agent repo 都应该被多个项目共享.
不建议 为多个项目创建多个 agent repo.

隐藏 agent repo 的示意图 (更一目了然)