Skip to main content
Version: 0.9



This guide will show you that KCL solves the secret management problem by integrating Vault and 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
git clone
cd ./
  • Show the config
cat main.k

The output is

# Secret Management using Vault and Vals

apiVersion = "apps/v1"
kind = "Deployment"
metadata = {
name = "nginx" = "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 =
image = "${}: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

vault server -dev
export VAULT_ADDR=''
# 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:

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.

kcl main.k | vals eval -f - | kubectl apply -f -

The expect output is

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
kubectl get deploy nginx -o yaml | grep 'foo:'

The output is

foo: foo
  • Verify the bar annotation
kubectl get deploy nginx -o yaml | grep 'bar:'

The output is

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.