Skip to content

Commit 85a6310

Browse files
PeefyPeefy
committed
feat: add vault integration documents and secret management categories.
1 parent 02a59f2 commit 85a6310

File tree

22 files changed

+658
-6
lines changed

22 files changed

+658
-6
lines changed

‎docs/user_docs/guides/secret-management/1-vault.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
id: vault
3+
sidebar_label: Vault
4+
---
5+
# Vault
6+
7+
## Introduction
8+
9+
This guide will show you that KCL solves the secret management problem by integrating [Vault](https://developer.hashicorp.com/vault) and [Vals](https://github.com/helmfile/vals).
10+
11+
## Prerequisites
12+
13+
+ Install [KCL](/docs/user_docs/getting-started/install)
14+
+ Prepare a [Kubernetes Cluster](https://kubernetes.io/)
15+
+ Install [Vault](https://developer.hashicorp.com/vault/downloads)
16+
+ Install [Vals](https://github.com/helmfile/vals)
17+
18+
## How to
19+
20+
### 1. Get the Example
21+
22+
We put the application source code and infrastructure deployment code in different repos, which can be maintained by different roles to achieve the separation of concerns.
23+
24+
+ Get the application code
25+
26+
```shell
27+
git clone https://github.com/kcl-lang/kcl-lang.io.git/
28+
cd ./kcl-lang.io/examples/secret-management/vault
29+
```
30+
31+
+ Show the config
32+
33+
```shell
34+
cat main.k
35+
```
36+
37+
The output is
38+
39+
```python
40+
# Secret Management using Vault and Vals
41+
42+
apiVersion = "apps/v1"
43+
kind = "Deployment"
44+
metadata = {
45+
name = "nginx"
46+
labels.app = "nginx"
47+
annotations: {
48+
"secret-store": "vault"
49+
# Valid format:
50+
# "ref+vault://PATH/TO/KV_BACKEND#/KEY"
51+
"foo": "ref+vault://secret/foo#/foo"
52+
"bar": "ref+vault://secret/bar#/bar"
53+
}
54+
}
55+
spec = {
56+
replicas = 3
57+
selector.matchLabels = metadata.labels
58+
template.metadata.labels = metadata.labels
59+
template.spec.containers = [
60+
{
61+
name = metadata.name
62+
image = "${metadata.name}:1.14.2"
63+
ports = [{ containerPort = 80 }]
64+
}
65+
]
66+
}
67+
```
68+
69+
The main.k file extends the configuration of the Nginx application and customizes annotations. Among them, the value of annotation `foo` and `bar` follow secret reference format (`ref+vault://PATH/TO/KV_BACKEND#/KEY`):
70+
71+
+ `ref+vault`: indicates that this is a secret reference, and the external storage service is `Vault`.
72+
+ `PATH/TO/KV_BACKEND`: specifies the path where a secret is stored.
73+
+ `KEY`: specifies the key to reading secret.
74+
75+
The complete format is concatenated using a style similar to URI expressions, which can retrieve a secret stored externally.
76+
77+
### 2. Pre-store Secrets
78+
79+
Start the Vault Server
80+
81+
```shell
82+
vault server -dev
83+
export VAULT_ADDR='http://127.0.0.1:8200'
84+
# Note: Replace with your token
85+
export VAULT_TOKEN=yourtoken
86+
```
87+
88+
After Vault is started in development mode and unpacked, secrets are pre-stored, and the path and keys are consistent with `main.k`:
89+
90+
```shell
91+
vault kv put secret/foo foo=foo
92+
vault kv put secret/bar bar=bar
93+
```
94+
95+
### 3. Deploy Configuration
96+
97+
Using the following command to apply the deployment manifest.
98+
99+
```shell
100+
kcl main.k | vals eval -f - | kubectl apply -f -
101+
```
102+
103+
The expect output is
104+
105+
```shell
106+
deployment.apps/nginx created
107+
```
108+
109+
### 4. Verify Secrets
110+
111+
Next, verify that the secrets have been retrieved from Vault and replace the values of annotations of Nginx:
112+
113+
+ Verify the `foo` annotation
114+
115+
```shell
116+
kubectl get deploy nginx -o yaml | grep 'foo:'
117+
```
118+
119+
The output is
120+
121+
```yaml
122+
foo: foo
123+
```
124+
125+
+ Verify the `bar` annotation
126+
127+
```shell
128+
kubectl get deploy nginx -o yaml | grep 'bar:'
129+
```
130+
131+
The output is
132+
133+
```yaml
134+
bar: bar
135+
```
136+
137+
So far, we have retrieved the secrets hosted in `Vault` and put them into use.
138+
139+
## Summary
140+
141+
This guide introduces how KCL solves the secret management by integrating Vault and Vals. By following these steps, we can retrieve the secrets hosted in Vault and utilize them.

‎docs/user_docs/guides/secret-management/_category_.json‎

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

‎docs/user_docs/guides/working-with-kusion/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "KusionStack",
3-
"position": 13
3+
"position": 15
44
}

‎examples/secret-management/vault/kcl.mod‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[package]
2+
name = "vault"
3+
edition = "0.0.1"
4+
version = "0.0.1"
5+

‎examples/secret-management/vault/kcl.mod.lock‎

Whitespace-only changes.

‎examples/secret-management/vault/main.k‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Secret Management using Vault and Vals
2+
3+
apiVersion = "apps/v1"
4+
kind = "Deployment"
5+
metadata = {
6+
name = "nginx"
7+
labels.app = "nginx"
8+
annotations: {
9+
"secret-store": "vault"
10+
# Valid format:
11+
# "ref+vault://PATH/TO/KV_BACKEND#/KEY"
12+
"foo": "ref+vault://secret/foo#/foo"
13+
"bar": "ref+vault://secret/bar#/bar"
14+
}
15+
}
16+
spec = {
17+
replicas = 3
18+
selector.matchLabels = metadata.labels
19+
template.metadata.labels = metadata.labels
20+
template.spec.containers = [
21+
{
22+
name = metadata.name
23+
image = "${metadata.name}:1.14.2"
24+
ports = [{ containerPort = 80 }]
25+
}
26+
]
27+
}

‎i18n/en/docusaurus-plugin-content-docs/current.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -730,5 +730,13 @@
730730
"sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
731731
"message": "Mutate or Validate Kubernetes Manifests",
732732
"description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
733+
},
734+
"sidebar.docs.category.Secret Management": {
735+
"message": "Secret Management",
736+
"description": "The label for category Secret Management in sidebar docs"
737+
},
738+
"sidebar.user_docs.category.Secret Management": {
739+
"message": "Secret Management",
740+
"description": "The label for category Secret Management in sidebar user_docs"
733741
}
734742
}

‎i18n/en/docusaurus-plugin-content-docs/version-0.5.1.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -730,5 +730,13 @@
730730
"sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
731731
"message": "Mutate or Validate Kubernetes Manifests",
732732
"description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
733+
},
734+
"sidebar.docs.category.Secret Management": {
735+
"message": "Secret Management",
736+
"description": "The label for category Secret Management in sidebar docs"
737+
},
738+
"sidebar.user_docs.category.Secret Management": {
739+
"message": "Secret Management",
740+
"description": "The label for category Secret Management in sidebar user_docs"
733741
}
734742
}

‎i18n/zh-CN/docusaurus-plugin-content-docs/current.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,5 +112,13 @@
112112
"sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
113113
"message": "编辑或验证 Kubernetes 资源",
114114
"description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
115+
},
116+
"sidebar.docs.category.Secret Management": {
117+
"message": "敏感信息管理",
118+
"description": "The label for category Secret Management in sidebar docs"
119+
},
120+
"sidebar.user_docs.category.Secret Management": {
121+
"message": "敏感信息管理",
122+
"description": "The label for category Secret Management in sidebar user_docs"
115123
}
116124
}

‎i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/secret-management/1-vault.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
id: vault
3+
sidebar_label: Vault
4+
---
5+
# Vault
6+
7+
## 简介
8+
9+
This guide will show you that KCL solves the secret management problem by integrating [Vault](https://developer.hashicorp.com/vault) and [Vals](https://github.com/helmfile/vals).
10+
11+
## 先决条件
12+
13+
+ Install [KCL](/docs/user_docs/getting-started/install)
14+
+ Prepare a [Kubernetes Cluster](https://kubernetes.io/)
15+
+ Install [Vault](https://developer.hashicorp.com/vault/downloads)
16+
+ Install [Vals](https://github.com/helmfile/vals)
17+
18+
## 具体步骤
19+
20+
### 1. 获得示例
21+
22+
We put the application source code and infrastructure deployment code in different repos, which can be maintained by different roles to achieve the separation of concerns.
23+
24+
+ Get the application code
25+
26+
```shell
27+
git clone https://github.com/kcl-lang/kcl-lang.io.git/
28+
cd ./kcl-lang.io/examples/secret-management/vault
29+
```
30+
31+
+ Show the config
32+
33+
```shell
34+
cat main.k
35+
```
36+
37+
The output is
38+
39+
```python
40+
# Secret Management using Vault and Vals
41+
42+
apiVersion = "apps/v1"
43+
kind = "Deployment"
44+
metadata = {
45+
name = "nginx"
46+
labels.app = "nginx"
47+
annotations: {
48+
"secret-store": "vault"
49+
# Valid format:
50+
# "ref+vault://PATH/TO/KV_BACKEND#/KEY"
51+
"foo": "ref+vault://secret/foo#/foo"
52+
"bar": "ref+vault://secret/bar#/bar"
53+
}
54+
}
55+
spec = {
56+
replicas = 3
57+
selector.matchLabels = metadata.labels
58+
template.metadata.labels = metadata.labels
59+
template.spec.containers = [
60+
{
61+
name = metadata.name
62+
image = "${metadata.name}:1.14.2"
63+
ports = [{ containerPort = 80 }]
64+
}
65+
]
66+
}
67+
```
68+
69+
The main.k file extends the configuration of the Nginx application and customizes annotations. Among them, the value of annotation `foo` and `bar` follow secret reference format (`ref+vault://PATH/TO/KV_BACKEND#/KEY`):
70+
71+
+ `ref+vault`: indicates that this is a secret reference, and the external storage service is `Vault`.
72+
+ `PATH/TO/KV_BACKEND`: specifies the path where a secret is stored.
73+
+ `KEY`: specifies the key to reading secret.
74+
75+
The complete format is concatenated using a style similar to URI expressions, which can retrieve a secret stored externally.
76+
77+
### 2. 预存敏感信息
78+
79+
Start the Vault Server
80+
81+
```shell
82+
vault server -dev
83+
export VAULT_ADDR='http://127.0.0.1:8200'
84+
# Note: Replace with your token
85+
export VAULT_TOKEN=yourtoken
86+
```
87+
88+
After Vault is started in development mode and unpacked, secrets are pre-stored, and the path and keys are consistent with `main.k`:
89+
90+
```shell
91+
vault kv put secret/foo foo=foo
92+
vault kv put secret/bar bar=bar
93+
```
94+
95+
### 3. 部署配置
96+
97+
Using the following command to apply the deployment manifest.
98+
99+
```shell
100+
kcl main.k | vals eval -f - | kubectl apply -f -
101+
```
102+
103+
The expect output is
104+
105+
```shell
106+
deployment.apps/nginx created
107+
```
108+
109+
### 4. 验证敏感信息
110+
111+
Next, verify that the secrets have been retrieved from Vault and replace the values of annotations of Nginx:
112+
113+
+ Verify the `foo` annotation
114+
115+
```shell
116+
kubectl get deploy nginx -o yaml | grep 'foo:'
117+
```
118+
119+
The output is
120+
121+
```yaml
122+
foo: foo
123+
```
124+
125+
+ Verify the `bar` annotation
126+
127+
```shell
128+
kubectl get deploy nginx -o yaml | grep 'bar:'
129+
```
130+
131+
The output is
132+
133+
```yaml
134+
bar: bar
135+
```
136+
137+
So far, we have retrieved the secrets hosted in `Vault` and put them into use.
138+
139+
## 小结
140+
141+
This guide introduces how KCL solves the secret management by integrating Vault and Vals. By following these steps, we can retrieve the secrets hosted in Vault and utilize them.

0 commit comments

Comments
 (0)