Skip to content

Commit 521b847

Browse files
PeefyPeefy
authored
Merge pull request #107 from Peefy/feat-ci-integration-guide
feat: add github ci-interagration guide
2 parents fbc29d0 + 66a43c0 commit 521b847

File tree

9 files changed

+273
-0
lines changed

9 files changed

+273
-0
lines changed

‎docs/user_docs/guides/ci-integration/1-github-actions.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
id: github-actions
3+
sidebar_label: Github Actions
4+
---
5+
# Github Actions 集成
6+
7+
## 简介
8+
9+
在 [GitOps](/docs/user_docs/guides/gitops/1-quick-start.md) 章节，我们介绍了如何将 KCL 与 GitOps 进行集成。在本文中，我们将继续提供 KCL 和 CI 集成的示例方案，希望通过使用容器、用于生成的持续集成 (CI) 和用于持续部署 (CD) 的 GitOps 来实现端到端应用程序开发流程。在此方案中，我们使用一个 Flask 应用和 Github Actions 将用作示例。
10+
11+
> 注意：你可以在此方案中使用任何容器化应用以及不同的 CI 系统如 Gitlab CI，Jenkins CI 等。
12+
13+
整体工作流程如下：
14+
15+
+ 应用代码开发并提交到提交到 GitHub 存储库
16+
+ GitHub Actions 从应用代码生成容器镜像，并将容器镜像推送到 docker.io 容器注册表
17+
+ GitHub Actions 根据 docker.io 容器注册表中容器镜像的版本号并同步更新 KCL 清单部署文件
18+
19+
## 具体步骤
20+
21+
### 1. 获得示例
22+
23+
我们将业务源码和部署清单放在不同仓库，可以分不同角色进行分别维护，实现关注点分离。
24+
25+
+ 获得业务源码
26+
27+
```shell
28+
git clone https://github.com/kcl-lang/flask-demo.io.git/
29+
cd flask-demo
30+
```
31+
32+
这是一个使用 Python 编写的 Web 应用，我们可以使用应用目录的 `Dockerfile` 来生成这个应用的容器镜像，同时可以通过 Github CI 自动构建 `flask_demo` 镜像，CI 配置如下
33+
34+
```yaml
35+
# This is a basic workflow to help you get started with Actions
36+
37+
name: CI
38+
39+
# Controls when the workflow will run
40+
on:
41+
# Triggers the workflow on push or pull request events but only for the main branch
42+
push:
43+
branches: [ main ]
44+
pull_request:
45+
branches: [ main ]
46+
47+
# Allows you to run this workflow manually from the Actions tab
48+
workflow_dispatch:
49+
50+
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
51+
jobs:
52+
# This workflow contains a single job called "build"
53+
build:
54+
# The type of runner that the job will run on
55+
runs-on: ubuntu-latest
56+
57+
# Steps represent a sequence of tasks that will be executed as part of the job
58+
steps:
59+
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
60+
- uses: actions/checkout@v2
61+
62+
- name: Docker Login
63+
uses: docker/login-action@v1.10.0
64+
with:
65+
username: ${{ secrets.DOCKER_USERNAME }}
66+
password: ${{ secrets.DOCKER_PASSWORD }}
67+
logout: true
68+
69+
# Runs a set of commands using the runners shell
70+
- name: build image
71+
run: |
72+
make image
73+
docker tag flask_demo:latest ${{ secrets.DOCKER_USERNAME }}/flask_demo:${{ github.sha }}
74+
docker push ${{ secrets.DOCKER_USERNAME }}/flask_demo:${{ github.sha }}
75+
76+
# Trigger KCL manifest
77+
- name: Trigger CI
78+
uses: InformaticsMatters/trigger-ci-action@1.0.1
79+
with:
80+
ci-owner: kcl-lang
81+
ci-repository: flask-demo-kcl-manifests
82+
ci-ref: refs/heads/main
83+
ci-user: kcl-bot
84+
ci-user-token: ${{ secrets.DEPLOY_ACCESS_TOKEN }}
85+
ci-name: CI
86+
ci-inputs: >-
87+
image=${{ secrets.DOCKER_USERNAME }}/flask_demo
88+
sha-tag=${{ github.sha }}
89+
```
90+
91+
我们需要源码仓库的工作流自动触发部署清单仓库中的工作流，此时需要创建具有 Github CI 操作权限的 `secrets.DEPLOY_ACCESS_TOKEN` 以及 Docker Hub 镜像推送的账号信息 `secrets.DOCKER_USERNAME` 和 `secrets.DOCKER_PASSWORD`, 这些可以在 Github 仓库的 `Secrets and variables` 设置中进行配置，如下图所示
92+
93+
![](/img/docs/user_docs/guides/ci-integration/github-secrets.png)
94+
95+
### 2. 提交应用代码
96+
97+
flask-demo 仓库提交代码后，Github 会自动构建容器镜像，并将制品推送到 Docker hub 中，会再触发 flask-demo-kcl-manifests 仓库的 Action，[通过 KCL 自动化 API](/docs/user_docs/guides/automation) 修改部署清单仓库中的镜像地址。现在让我们为 flask-demo 仓库创建一个提交，我们可以看到代码提交后触发业务仓库 Github CI 流程
98+
99+
![](/img/docs/user_docs/guides/ci-integration/app-ci.png)
100+
101+
### 3. 配置自动更新
102+
103+
当业务仓库 Github CI 流程执行完成后，会自动在存放 KCL 资源配置的仓库触发一个 CI 自动更新配置并提交到 flask-demo-kcl-manifests main 分支，commit 信息如下
104+
105+
![](/img/docs/user_docs/guides/ci-integration/image-auto-update.png)
106+
107+
+ 我们可以获得部署清单源码进行编译验证
108+
109+
```shell
110+
git clone https://github.com/kcl-lang/flask-demo-kcl-manifests.git/
111+
cd flask-demo-kcl-manifests
112+
git checkout main && git pull && kcl
113+
```
114+
115+
输出 YAML 为
116+
117+
```yaml
118+
apiVersion: apps/v1
119+
kind: Deployment
120+
metadata:
121+
name: flask_demo
122+
labels:
123+
app: flask_demo
124+
spec:
125+
replicas: 1
126+
selector:
127+
matchLabels:
128+
app: flask_demo
129+
template:
130+
metadata:
131+
labels:
132+
app: flask_demo
133+
spec:
134+
containers:
135+
- name: flask_demo
136+
image: "kcllang/flask_demo:6428cff4309afc8c1c40ad180bb9cfd82546be3e"
137+
ports:
138+
- protocol: TCP
139+
containerPort: 5000
140+
---
141+
apiVersion: v1
142+
kind: Service
143+
metadata:
144+
name: flask_demo
145+
labels:
146+
app: flask_demo
147+
spec:
148+
type: NodePort
149+
selector:
150+
app: flask_demo
151+
ports:
152+
- port: 5000
153+
protocol: TCP
154+
targetPort: 5000
155+
```
156+
157+
从上述配置可以看出资源的镜像确实自动更新为了新构建的镜像内容。此外，我们还可以使用 [Argo CD KCL 插件](/docs/user_docs/guides/gitops/1-quick-start.md) 自动从 Git 存储库同步或从中拉取数据并将应用部署到 Kubernetes 集群。
158+
159+
## 小结
160+
161+
通过将 KCL 和 Github CI 集成，我们能够将任意的业务代码的产出容器化镜像进行自动化修改并部署配置，以实现端到端应用程序开发流程并提升研发部署效率。

‎docs/user_docs/guides/ci-integration/_2-gitlab-ci.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
id: gitlab-ci
3+
sidebar_label: Gitlab CI
4+
---
5+
6+
Comming Soon
7+
8+
## Introduction
9+
10+
## How to
11+
12+
## Summary

‎docs/user_docs/guides/ci-integration/_3-jenkins-ci.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
id: github-ci
3+
sidebar_label: Github CI
4+
---
5+
6+
Comming Soon
7+
8+
## Introduction
9+
10+
## How to
11+
12+
## Summary

‎docs/user_docs/guides/ci-integration/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "CI Integration",
3+
"position": 12
4+
}

‎examples/ci-integration/github-actions/app.yaml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# This is a basic workflow to help you get started with Actions
2+
3+
name: CI
4+
5+
# Controls when the workflow will run
6+
on:
7+
# Triggers the workflow on push or pull request events but only for the main branch
8+
push:
9+
branches: [ main ]
10+
pull_request:
11+
branches: [ main ]
12+
13+
# Allows you to run this workflow manually from the Actions tab
14+
workflow_dispatch:
15+
16+
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
17+
jobs:
18+
# This workflow contains a single job called "build"
19+
build:
20+
# The type of runner that the job will run on
21+
runs-on: ubuntu-latest
22+
23+
# Steps represent a sequence of tasks that will be executed as part of the job
24+
steps:
25+
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
26+
- uses: actions/checkout@v2
27+
28+
- name: Docker Login
29+
uses: docker/login-action@v1.10.0
30+
with:
31+
username: ${{ secrets.DOCKER_USERNAME }}
32+
password: ${{ secrets.DOCKER_PASSWORD }}
33+
logout: true
34+
35+
# Runs a set of commands using the runners shell
36+
- name: build image
37+
run: |
38+
make image
39+
docker tag flask_demo:latest ${{ secrets.DOCKER_USERNAME }}/flask_demo:${{ github.sha }}
40+
docker push ${{ secrets.DOCKER_USERNAME }}/flask_demo:${{ github.sha }}
41+
42+
- name: Trigger CI
43+
uses: InformaticsMatters/trigger-ci-action@1.0.1
44+
with:
45+
ci-owner: kcl-lang
46+
ci-repository: flask-demo-kcl-manifests
47+
ci-ref: refs/heads/main
48+
ci-user: peefy
49+
ci-user-token: ${{ secrets.DEPLOY_ACCESS_TOKEN }}
50+
ci-name: CI
51+
ci-inputs: >-
52+
image=${{ secrets.DOCKER_USERNAME }}/flask_demo
53+
sha-tag=${{ github.sha }}

‎examples/ci-integration/github-actions/manifests.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: CI
2+
on:
3+
push:
4+
branches: [ main ]
5+
pull_request:
6+
branches: [ main ]
7+
workflow_dispatch:
8+
inputs:
9+
image:
10+
required: true
11+
description: 'docker image name'
12+
sha-tag:
13+
required: true
14+
description: 'docker image tag'
15+
jobs:
16+
update-manifests:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- uses: actions/checkout@v2
20+
if: ${{ github.event.inputs.image }}
21+
- name: KCL config edit
22+
if: ${{ github.event.inputs.image }}
23+
run: |
24+
wget -q https://kcl-lang.io/script/install.sh -O - | /bin/bash
25+
/usr/local/kclvm/bin/kcl -d -O config.containers.flask_demo.image="${{ github.event.inputs.image }}:${{ github.event.inputs.sha-tag }}"
26+
- name: Git Commit/Push Changes
27+
uses: EndBug/add-and-commit@v9
28+
if: ${{ github.event.inputs.image }}
29+
with:
30+
default_author: github_actions
31+
message: "kcl code set image to ${{ github.event.inputs.image }}:${{ github.event.inputs.sha-tag }}"

‎static/img/docs/user_docs/guides/ci-integration/app-ci.png‎

373 KB
Loading

‎static/img/docs/user_docs/guides/ci-integration/github-secrets.png‎

272 KB
Loading

‎static/img/docs/user_docs/guides/ci-integration/image-auto-update.png‎

422 KB
Loading

0 commit comments

Comments
 (0)