Skip to content

Commit b192a8f

Browse files
PeefyPeefy
authored
Merge pull request #290 from zong-zhe/add-flux-doc
feat: add user guide for flux-kcl-controller
2 parents 9855ada + 4236caf commit b192a8f

File tree

5 files changed

+227
-2
lines changed

5 files changed

+227
-2
lines changed

docs/user_docs/guides/gitops/1-quick-start.md renamed to docs/user_docs/guides/gitops/1-argocd.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: gitops-quick-start
3-
sidebar_label: Quick Start
3+
sidebar_label: Implement GitOps with KCL and ArgoCD
44
---
55

66
# Quick Start

‎docs/user_docs/guides/gitops/2-fluxcd.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
id: gitops-with-fluxcd
3+
sidebar_label: Implement GitOps with KCL and FluxCD
4+
---
5+
6+
# Quick Start
7+
8+
## Introduction
9+
10+
### What is GitOps
11+
12+
GitOps is a modern way to do continuous delivery. Its core idea is to have a Git repository which contains environmental and application configurations. An automated process is also needed for sync the config to cluster.
13+
14+
By changing the files in repository, developers can apply the applications automatically. The benefits of applying GitOps include:
15+
16+
- Increased productivity. Continuous delivery can speed up the time of deployment.
17+
- Lower the barrier for developer to deploy. By pushing code instead of container configuration, developers can easily deploy Kubernetes without knowing its internal implementation.
18+
- Trace the change records. Managing the cluster with Git makes every change traceable, enhancing the audit trail.
19+
- Recover the cluster with Git's rollback and branch.
20+
21+
### GitOps with KCL and FluxCD
22+
23+
Benefits of Using KCL and FluxCD Together:
24+
25+
- KCL can help us **simplify complex Kubernetes deployment configuration files**, reduce the error rate of manually writing YAML files, and improve code readability and maintainability.
26+
- FluxCD can **automate** the deployment of Kubernetes applications, achieve continuous deployment, and provide comprehensive monitoring and control functions.
27+
- By combining KCL and FluxCD, deployment efficiency can be improved, errors reduced, and management and monitoring of Kubernetes applications strengthened.
28+
- The combination of KCL and FluxCD can also help us achieve **Infrastructure as Code (IaC)**, simplify application deployment and management, and better implement DevOps principles.
29+
30+
With GitOps, developer and operation teams can manage application deployment and configuration by modifying KCL code and generating YAML files. The GitOps toolchain will automatically synchronize the changes to the Kubernetes cluster, enabling continuous deployment and ensuring consistency. If there are issues, the GitOps toolchain can be used to quickly rollback.
31+
32+
### Flux-KCL-Controller
33+
34+
flux-kcl-controller is a component that integrates [KCL](https://github.com/kcl-lang/kcl) and [Flux](https://github.com/fluxcd/flux2), which is mainly used to define infrastructure and workloads based on KCL programs stored in git/oci repositories, and to achieve continuous delivery of infrastructure and workloads through [source-controller](
35+
36+
![](/img/docs/user_docs/guides/cd-integration/kcl-flux.png)
37+
38+
## Prerequisite
39+
40+
- Install [KCL](https://kcl-lang.io/docs/user_docs/getting-started/install)
41+
42+
## Quick Start
43+
44+
### 1. Install Kubernetes and GitOps Tools
45+
46+
#### Configure Kubernetes Cluster and FluxCD Controller
47+
48+
- Install [K3d](https://github.com/k3d-io/k3d) to create a default cluster.
49+
50+
```bash
51+
k3d cluster create mycluster
52+
```
53+
54+
- Install Flux KCL Controller
55+
56+
```bash
57+
git clone https://github.com/kcl-lang/flux-kcl-controller.git && cd flux-kcl-controller && make deploy
58+
```
59+
60+
- Check if the fluxcd controller container is initialized and running by using the `kubectl get` command.
61+
62+
```bash
63+
kubectl get pod -n source-system -l app=kcl-controller
64+
```
65+
66+
### 2. Write Flux-KCL-Controller Configuration File
67+
68+
Create a `GitRepository` object for `flux-kcl-controller` to monitor the KCL program stored in the git repository. For example, we use the flask demo in [“Implementing GitOps using Github, Argo CD, and KCL to Simplify DevOps”](https://kcl-lang.io/blog/2023-07-31-kcl-github-argocd-gitops/#3-get-the-application-code) as an example. We create a `GitRepository` object in the `flux-kcl-controller` repository to monitor the KCL program stored in the git repository. Save the following content in the file `gitrepo.yaml`.
69+
70+
```yaml
71+
apiVersion: source.toolkit.fluxcd.io/v1
72+
kind: GitRepository
73+
metadata:
74+
name: kcl-deployment
75+
namespace: default
76+
spec:
77+
interval: 10s # Check every 10 seconds
78+
url: https://github.com/kcl-lang/flask-demo-kcl-manifests.git
79+
ref:
80+
branch: main # Monitor the main branch
81+
---
82+
apiVersion: krm.kcl.dev.fluxcd/v1alpha1
83+
kind: KCLRun
84+
metadata:
85+
name: kcl-git-controller
86+
namespace: default
87+
spec:
88+
sourceRef:
89+
kind: GitRepository
90+
name: kcl-deployment
91+
```
92+
93+
Apply the `GitRepository` object to the cluster by running the `kubectl apply -f gitrepo.yaml` command.
94+
95+
### 3. Check the Deployment Result
96+
97+
Check the deployment result by running the `kubectl get deployments` command.
98+
99+
```
100+
kubectl get deployments
101+
```
102+
103+
You can see the result, and the deployment is successful.
104+
105+
```
106+
NAME READY UP-TO-DATE AVAILABLE AGE
107+
flask-demo 1/1 1 1 17d
108+
```
109+
110+
### 4. More
111+
112+
- [FluxCD](https://toolkit.fluxcd.io/)
113+
- [Flux Source Controller](https://fluxcd.io/flux/components/source/)
114+
- [GitRepositrory](https://fluxcd.io/flux/components/source/gitrepositories/)

i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/gitops/1-quick-start.md renamed to i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/gitops/1-argocd.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: gitops-quick-start
3-
sidebar_label: 快速开始
3+
sidebar_label: 使用 ArgoCD 支持 KCL 实现 GitOps
44
---
55

66
# 快速开始

‎i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/gitops/2-fluxcd.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
id: gitops-with-fluxcd
3+
sidebar_label: 使用 flux-kcl-controller 支持 KCL 与 FluxCD 实现 GitOps
4+
---
5+
6+
# 快速开始
7+
8+
## 简介
9+
10+
### 什么是 GitOps
11+
12+
GitOps 是一种实现持续交付的现代方式。它的核心思想是拥有一个包含环境和应用程序配置的 Git 存储库。通过更改应用存储库中的文件，可以自动部署应用程序。应用 GitOps 的好处包括：
13+
14+
- 提高生产力，持续交付可以加快部署时间。
15+
- 降低开发人员部署的障碍。通过推送代码而不是容器配置，开发人员可以在不知道其内部实现的情况下轻松部署 Kubernetes 集群和应用。
16+
- 追踪变更记录。使用 Git 管理配置使每一项更改都具有可跟踪性，从而增强审计跟踪。
17+
18+
### 将 KCL 与 FluxCD 一起使用
19+
20+
将 [KCL](https://github.com/kcl-lang/kcl) 与 [FluxCD](https://github.com/fluxcd/flux2) 等 GitOps 工具一起使用具有如下好处:
21+
22+
- 通过 KCL 语言的[抽象能力](/docs/user_docs/guides/abstraction)和可编程能力可以帮助我们**简化复杂的 Kubernetes 部署配置文件**，降低手动编写 YAML 文件的错误率，消除多余的配置模版，提升多环境多租户的配置扩展能力，同时提高配置的可读性和可维护性。
23+
- KCL 允许开发人员以声明式的方式定义应用程序所需的资源，通过将 KCL 和 FluxCD 相结合可以帮助我们更好地实现**基础设施即代码（IaC）**，提高部署效率，简化应用程序的配置管理。
24+
- FluxCD 可以**自动化**地实现应用程序的连续部署，并提供友好的可视化界面。
25+
26+
使用 GitOps，开发人员和运维团队可以通过分别修改应用和配置代码来管理应用程序的部署，GitOps 工具链将自动同步对配置的更改，从而实现持续部署并确保一致性。如果出现问题，可以使用 GitOps 工具链快速回滚。
27+
28+
### Flux-KCL-Controller
29+
30+
kcl-controller 是一个组件，用于集成 [KCL](https://github.com/kcl-lang/kcl) 和 [Flux](https://github.com/fluxcd/flux2), 主要用来根据存储在 git/oci 仓库中的 KCL 程序定义的基础设施和工作负载，通过 [source-controller](https://github.com/fluxcd/source-controller) 获取 KCL 程序，实现基础设施和工作负载的持续交付。
31+
32+
![](/img/docs/user_docs/guides/cd-integration/kcl-flux.png)
33+
34+
## 先决条件
35+
36+
- 安装 [KCL](https://kcl-lang.io/docs/user_docs/getting-started/install)
37+
38+
## 快速开始
39+
40+
### 1. 安装 Kubernetes 和 GitOps 工具
41+
42+
#### 配置 Kubernetes 集群和 FluxCD 控制器
43+
44+
- 安装 [K3d](https://github.com/k3d-io/k3d) 并创建一个集群
45+
46+
```bash
47+
k3d cluster create mycluster
48+
```
49+
50+
> 注意：你可以在此方案中使用其他方式创建您自己的 Kubernetes 集群，如 kind, minikube 等。
51+
52+
- 安装 Flux KCL Controller
53+
54+
```bash
55+
git clone https://github.com/kcl-lang/flux-kcl-controller.git && cd flux-kcl-controller && make deploy
56+
```
57+
58+
- 通过 `kubectl get` 命令查看 fluxcd 控制器容器是否初始化完成进入运行（Running）状态。
59+
60+
```bash
61+
kubectl get pod -n source-system -l app=kcl-controller
62+
```
63+
64+
### 2. 编写 Flux-KCL-Controller 配置文件
65+
66+
以[《使用 Github、Argo CD 和 KCL 实现 GitOps 以简化 DevOps》](https://kcl-lang.io/zh-CN/blog/2023-07-31-kcl-github-argocd-gitops/) 中的 flask demo 为例，我们在 `flux-kcl-controller` 仓库中创建一个 `GitRepository` 对象，用于监控存储在 git 仓库中的 KCL 程序。将一下内容保存在文件 `gitrepo.yaml` 中。
67+
68+
```yaml
69+
apiVersion: source.toolkit.fluxcd.io/v1
70+
kind: GitRepository
71+
metadata:
72+
name: kcl-deployment
73+
namespace: default
74+
spec:
75+
interval: 10s # 每隔 10 秒检查
76+
url: https://github.com/kcl-lang/flask-demo-kcl-manifests.git
77+
ref:
78+
branch: main # 监控 main 分支
79+
---
80+
apiVersion: krm.kcl.dev.fluxcd/v1alpha1
81+
kind: KCLRun
82+
metadata:
83+
name: kcl-git-controller
84+
namespace: default
85+
spec:
86+
sourceRef:
87+
kind: GitRepository
88+
name: kcl-deployment
89+
```
90+
91+
通过命令 `kubectl apply -f gitrepo.yaml` 部署对象到集群。
92+
93+
### 3. 查看部署结果
94+
95+
通过 `kubectl get deployments` 命令查看 python flask demo 部署结果。
96+
97+
```
98+
kubectl get deployments
99+
```
100+
101+
可以看到结果，部署成功
102+
```
103+
NAME READY UP-TO-DATE AVAILABLE AGE
104+
flask-demo 1/1 1 1 17d
105+
```
106+
107+
### 4. 更多内容
108+
109+
- [FluxCD 官方文档](https://toolkit.fluxcd.io/)
110+
- [Flux Source Controller 官方文档](https://fluxcd.io/flux/components/source/)
111+
- [GitRepositrory](https://fluxcd.io/flux/components/source/gitrepositories/)

‎static/img/docs/user_docs/guides/cd-integration/kcl-flux.png‎

58 KB
Loading

0 commit comments

Comments
 (0)