Merge pull request #130 from Peefy/secret-management-guide

feat: add vault integration documents and secret management categories.

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

@@ -0,0 +1,141 @@
+---
+id: vault
+sidebar_label: Vault
+---
+# Vault
+
+## Introduction
+
+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).
+
+## Prerequisites
+
++ Install [KCL](/docs/user_docs/getting-started/install)
++ Prepare a [Kubernetes Cluster](https://kubernetes.io/)
++ Install [Vault](https://developer.hashicorp.com/vault/downloads)
++ Install [Vals](https://github.com/helmfile/vals)
+
+## How to
+
+### 1. Get the Example
+
+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.
+
++ Get the application code
+
+```shell
+git clone https://github.com/kcl-lang/kcl-lang.io.git/
+cd ./kcl-lang.io/examples/secret-management/vault
+```
+
++ Show the config
+
+```shell
+cat main.k
+```
+
+The output is
+
+```python
+# Secret Management using Vault and Vals
+
+apiVersion = "apps/v1"
+kind = "Deployment"
+metadata = {
+    name = "nginx"
+    labels.app = "nginx"
+    annotations: {
+        "secret-store": "vault"
+        # Valid format:
+        #  "ref+vault://PATH/TO/KV_BACKEND#/KEY"
+        "foo": "ref+vault://secret/foo#/foo"
+        "bar": "ref+vault://secret/bar#/bar"
+    }
+}
+spec = {
+    replicas = 3
+    selector.matchLabels = metadata.labels
+    template.metadata.labels = metadata.labels
+    template.spec.containers = [
+        {
+            name = metadata.name
+            image = "${metadata.name}:1.14.2"
+            ports = [{ containerPort = 80 }]
+        }
+    ]
+}
+```
+
+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`):
+
++ `ref+vault`: indicates that this is a secret reference, and the external storage service is `Vault`.
++ `PATH/TO/KV_BACKEND`: specifies the path where a secret is stored.
++ `KEY`: specifies the key to reading secret.
+
+The complete format is concatenated using a style similar to URI expressions, which can retrieve a secret stored externally.
+
+### 2. Pre-store Secrets
+
+Start the Vault Server
+
+```shell
+vault server -dev
+export VAULT_ADDR='http://127.0.0.1:8200'
+# Note: Replace with your token 
+export VAULT_TOKEN=yourtoken
+```
+
+After Vault is started in development mode and unpacked, secrets are pre-stored, and the path and keys are consistent with `main.k`:
+
+```shell
+vault kv put secret/foo foo=foo
+vault kv put secret/bar bar=bar
+```
+
+### 3. Deploy Configuration
+
+Using the following command to apply the deployment manifest.
+
+```shell
+kcl main.k | vals eval -f - | kubectl apply -f -
+```
+
+The expect output is
+
+```shell
+deployment.apps/nginx created
+```
+
+### 4. Verify Secrets
+
+Next, verify that the secrets have been retrieved from Vault and replace the values of annotations of Nginx:
+
++ Verify the `foo` annotation
+
+```shell
+kubectl get deploy nginx -o yaml | grep 'foo:'
+```
+
+The output is
+
+```yaml
+    foo: foo
+```
+
++ Verify the `bar` annotation
+
+```shell
+kubectl get deploy nginx -o yaml | grep 'bar:'
+```
+
+The output is
+
+```yaml
+    bar: bar
+```
+
+So far, we have retrieved the secrets hosted in `Vault` and put them into use.
+
+## Summary
+
+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

@@ -0,0 +1,4 @@
+{
+  "label": "Secret Management",
+  "position": 13
+}

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

@@ -1,4 +1,4 @@
 {
   "label": "KusionStack",
-  "position": 13
+  "position": 15
 }

examples/secret-management/vault/kcl.mod

@@ -0,0 +1,5 @@
+[package]
+name = "vault"
+edition = "0.0.1"
+version = "0.0.1"
+

examples/secret-management/vault/main.k

@@ -0,0 +1,27 @@
+# Secret Management using Vault and Vals
+
+apiVersion = "apps/v1"
+kind = "Deployment"
+metadata = {
+    name = "nginx"
+    labels.app = "nginx"
+    annotations: {
+        "secret-store": "vault"
+        # Valid format:
+        #  "ref+vault://PATH/TO/KV_BACKEND#/KEY"
+        "foo": "ref+vault://secret/foo#/foo"
+        "bar": "ref+vault://secret/bar#/bar"
+    }
+}
+spec = {
+    replicas = 3
+    selector.matchLabels = metadata.labels
+    template.metadata.labels = metadata.labels
+    template.spec.containers = [
+        {
+            name = metadata.name
+            image = "${metadata.name}:1.14.2"
+            ports = [{ containerPort = 80 }]
+        }
+    ]
+}

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

@@ -730,5 +730,13 @@
   "sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
     "message": "Mutate or Validate Kubernetes Manifests",
     "description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
+  },
+  "sidebar.docs.category.Secret Management": {
+    "message": "Secret Management",
+    "description": "The label for category Secret Management in sidebar docs"
+  },
+  "sidebar.user_docs.category.Secret Management": {
+    "message": "Secret Management",
+    "description": "The label for category Secret Management in sidebar user_docs"
   }
 }

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

@@ -730,5 +730,13 @@
   "sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
     "message": "Mutate or Validate Kubernetes Manifests",
     "description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
+  },
+  "sidebar.docs.category.Secret Management": {
+    "message": "Secret Management",
+    "description": "The label for category Secret Management in sidebar docs"
+  },
+  "sidebar.user_docs.category.Secret Management": {
+    "message": "Secret Management",
+    "description": "The label for category Secret Management in sidebar user_docs"
   }
 }

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

@@ -112,5 +112,13 @@
   "sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
     "message": "编辑或验证 Kubernetes 资源",
     "description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
+  },
+  "sidebar.docs.category.Secret Management": {
+    "message": "敏感信息管理",
+    "description": "The label for category Secret Management in sidebar docs"
+  },
+  "sidebar.user_docs.category.Secret Management": {
+    "message": "敏感信息管理",
+    "description": "The label for category Secret Management in sidebar user_docs"
   }
 }

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

@@ -0,0 +1,141 @@
+---
+id: vault
+sidebar_label: Vault
+---
+# Vault
+
+## 简介
+
+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).
+
+## 先决条件
+
++ Install [KCL](/docs/user_docs/getting-started/install)
++ Prepare a [Kubernetes Cluster](https://kubernetes.io/)
++ Install [Vault](https://developer.hashicorp.com/vault/downloads)
++ Install [Vals](https://github.com/helmfile/vals)
+
+## 具体步骤
+
+### 1. 获得示例
+
+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.
+
++ Get the application code
+
+```shell
+git clone https://github.com/kcl-lang/kcl-lang.io.git/
+cd ./kcl-lang.io/examples/secret-management/vault
+```
+
++ Show the config
+
+```shell
+cat main.k
+```
+
+The output is
+
+```python
+# Secret Management using Vault and Vals
+
+apiVersion = "apps/v1"
+kind = "Deployment"
+metadata = {
+    name = "nginx"
+    labels.app = "nginx"
+    annotations: {
+        "secret-store": "vault"
+        # Valid format:
+        #  "ref+vault://PATH/TO/KV_BACKEND#/KEY"
+        "foo": "ref+vault://secret/foo#/foo"
+        "bar": "ref+vault://secret/bar#/bar"
+    }
+}
+spec = {
+    replicas = 3
+    selector.matchLabels = metadata.labels
+    template.metadata.labels = metadata.labels
+    template.spec.containers = [
+        {
+            name = metadata.name
+            image = "${metadata.name}:1.14.2"
+            ports = [{ containerPort = 80 }]
+        }
+    ]
+}
+```
+
+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`):
+
++ `ref+vault`: indicates that this is a secret reference, and the external storage service is `Vault`.
++ `PATH/TO/KV_BACKEND`: specifies the path where a secret is stored.
++ `KEY`: specifies the key to reading secret.
+
+The complete format is concatenated using a style similar to URI expressions, which can retrieve a secret stored externally.
+
+### 2. 预存敏感信息
+
+Start the Vault Server
+
+```shell
+vault server -dev
+export VAULT_ADDR='http://127.0.0.1:8200'
+# Note: Replace with your token 
+export VAULT_TOKEN=yourtoken
+```
+
+After Vault is started in development mode and unpacked, secrets are pre-stored, and the path and keys are consistent with `main.k`:
+
+```shell
+vault kv put secret/foo foo=foo
+vault kv put secret/bar bar=bar
+```
+
+### 3. 部署配置
+
+Using the following command to apply the deployment manifest.
+
+```shell
+kcl main.k | vals eval -f - | kubectl apply -f -
+```
+
+The expect output is
+
+```shell
+deployment.apps/nginx created
+```
+
+### 4. 验证敏感信息
+
+Next, verify that the secrets have been retrieved from Vault and replace the values of annotations of Nginx:
+
++ Verify the `foo` annotation
+
+```shell
+kubectl get deploy nginx -o yaml | grep 'foo:'
+```
+
+The output is
+
+```yaml
+    foo: foo
+```
+
++ Verify the `bar` annotation
+
+```shell
+kubectl get deploy nginx -o yaml | grep 'bar:'
+```
+
+The output is
+
+```yaml
+    bar: bar
+```
+
+So far, we have retrieved the secrets hosted in `Vault` and put them into use.
+
+## 小结
+
+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.

i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/secret-management/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Secret Management",
+  "position": 13
+}

i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/working-with-kusion/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "KusionStack",
-  "position": 13
+  "position": 15
 }

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.5.0.json

@@ -115,5 +115,13 @@
   "sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
     "message": "编辑或验证 Kubernetes 资源",
     "description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
+  },
+  "sidebar.docs.category.Secret Management": {
+    "message": "敏感信息管理",
+    "description": "The label for category Secret Management in sidebar docs"
+  },
+  "sidebar.user_docs.category.Secret Management": {
+    "message": "敏感信息管理",
+    "description": "The label for category Secret Management in sidebar user_docs"
   }
 }