Before you begin

Before you get started, be sure that you have Administrator platform access so that you can create account credentials and provision resources. You also need the following prerequisites:

• Download and install the IBM Cloud CLI.

• Install the Kubernetes CLI (kubectl).

• Install Helm 3.x.

• Download and install jq.

  jq helps you slice and filter JSON data. You use jq in this tutorial to grab and use stored environment variables.

• A Vault Dedicated Instance provisioned in your IBM Cloud account. For more information, see Setting up your Vault Dedicated instance.

Set up your environment

To work with Vault Dedicated and Kubernetes Service, you need to create a cluster in your IBM Cloud account and configure access to your Vault Dedicated instance.

Install External Secrets Operator

Install External Secrets Operator using Helm.

1. Add the External Secrets Helm repository.

   helm repo add external-secrets https://charts.external-secrets.io
   helm repo update
   

2. Install External Secrets Operator.

   helm install external-secrets \
     external-secrets/external-secrets \
     --namespace external-secrets \
     --create-namespace \
     --set installCRDs=true
   

3. Verify the installation.

   kubectl get pods -n external-secrets
   

   Wait until all pods are in Running state.

4. Verify the Custom Resource Definitions (CRDs) are installed.

   kubectl get crd | grep external-secrets
   

   You should see CRDs like secretstores, clustersecretstores, and externalsecrets.

Configure SecretStore for Vault Dedicated

Create a SecretStore resource that defines how External Secrets Operator connects to your Vault Dedicated instance.

1. Create a Kubernetes secret with your Vault token.

   kubectl create secret generic vault-token \
     --namespace external-secrets \
     --from-literal=token="$VAULT_TOKEN"
   

2. Create a secretstore.yaml file.

   touch secretstore.yaml
   

3. Add the following configuration to the file.

   apiVersion: external-secrets.io/v1beta1
   kind: SecretStore
   metadata:
     name: vault-dedicated-secretstore
     namespace: default
   spec:
     provider:
       vault:
         server: "<VAULT_DEDICATED_ADDR>"
         path: "kv"
         version: "v2"
         namespace: "admin"
         auth:
           tokenSecretRef:
             name: "vault-token"
             key: "token"
             namespace: "external-secrets"
   

   Replace <VAULT_DEDICATED_ADDR> with your Vault Dedicated instance address. Note that the path is set to kv, which is the default mount point for the KV secrets engine in Vault Dedicated.

4. Apply the SecretStore configuration.

   kubectl apply -f secretstore.yaml
   

5. Verify the SecretStore is valid.

   kubectl get secretstore vault-dedicated-secretstore -n default
   kubectl describe secretstore vault-dedicated-secretstore -n default
   

   The status should show Valid if the connection to Vault Dedicated is successful.

Create an ExternalSecret

Create an ExternalSecret resource that defines which secrets to fetch from Vault Dedicated.

1. Create an externalsecret.yaml file.

   touch externalsecret.yaml
   

2. Add the following configuration.

   apiVersion: external-secrets.io/v1beta1
   kind: ExternalSecret
   metadata:
     name: vault-dedicated-app-secret
     namespace: default
   spec:
     refreshInterval: 1h
     secretStoreRef:
       name: vault-dedicated-secretstore
       kind: SecretStore
     target:
       name: my-k8s-secret
       creationPolicy: Owner
     data:
     - secretKey: username
       remoteRef:
         key: example_username_password
         property: username
     - secretKey: password
       remoteRef:
         key: example_username_password
         property: password
   

   The refreshInterval determines how often External Secrets Operator polls Vault Dedicated for updates. The default and recommended value is 1 hour.

3. Apply the ExternalSecret configuration.

   kubectl apply -f externalsecret.yaml
   

4. Verify that the External Secrets Operator fetched the secret from Vault Dedicated.

   kubectl get secret my-k8s-secret -o json | jq '.data | map_values(@base64d)'
   

   Example output:

   {
       "password": "cloudy-rainy-coffee-book",
       "username": "user123"
   }
   

   Success! You're now able to fetch secret data from your Vault Dedicated instance and use it in your Kubernetes cluster.

Deploy an app to the cluster

Finally, you can deploy an application in your cluster that uses the Vault Dedicated secret. At application run time, the secret data that is fetched from Vault Dedicated is converted to a Kubernetes secret that can be used by your cluster.

1. Create a simple test deployment that uses the secret.

   cat <<EOF | kubectl apply -f -
   apiVersion: v1
   kind: Pod
   metadata:
     name: test-app
     namespace: default
   spec:
     containers:
     - name: app
       image: busybox
       command: ['sh', '-c', 'echo "Username: \$USERNAME"; echo "Password: \$PASSWORD"; sleep 3600']
       env:
       - name: USERNAME
         valueFrom:
           secretKeyRef:
             name: my-k8s-secret
             key: username
       - name: PASSWORD
         valueFrom:
           secretKeyRef:
             name: my-k8s-secret
             key: password
   EOF
   

2. Check the pod logs to verify the secret was injected.

   kubectl logs test-app -n default
   

   Expected output:

   Username: user123
   Password: cloudy-rainy-coffee-book
   

Looking for more examples on how to deploy an app? Check out Deploying Kubernetes-native apps in clusters to find out more about deploying applications.

(Optional) Clean up resources

If you no longer need the resources that you created in this tutorial, you can complete the following steps to remove them from your account.

1. Delete your test Kubernetes cluster.

   ibmcloud ks cluster rm --cluster eso-test-cluster
   

2. Clean up test secrets in Vault dedicated.

   curl -k -X DELETE \
     -H "X-Vault-Token: $VAULT_TOKEN" \
     -H "X-Vault-Namespace: $VAULT_DEDICATED_NAMESPACE" \
     $VAULT_DEDICATED_ADDR/v1/kv/metadata/example_username_password
   

Notes of interest

As you construct your YAML documents, keep in mind the following considerations:

1. Polling interval: By default, the polling interval is set to 1 hour (refreshInterval: 1h) and is the preferred value. You can change this value in the ExternalSecret template. The interval can be expressed in units of s, m, or h.

2. Vault Dedicated mount path: Vault Dedicated uses kv/ as the default mount path for the KV secrets engine, not secret/. Ensure you specify the correct path in your SecretStore configuration.

3. Vault Dedicated namespaces: Vault Dedicated uses Vault Enterprise namespaces. The default namespace is admin. Ensure you specify the correct namespace in your SecretStore configuration.

4. Authentication methods: This tutorial uses token authentication for simplicity. For production environments, consider using AppRole or Kubernetes authentication methods for better security.

5. TLS considerations: Vault Dedicated requires TLS connections. In production environments, ensure proper certificate validation is configured instead of using skipTLSVerify.

Next steps

Great job! In this tutorial, you learned how to set up Vault Dedicated to securely populate application secrets to your Kubernetes cluster using External Secrets Operator. Check out more resources to help you get started with Vault Dedicated.

• Learn about Vault Secrets Operator, HashiCorp's official operator for Kubernetes integration.
• Review the External Secrets Operator Vault provider documentation.
• Explore Vault Dedicated documentation for more advanced features and configurations.
• Learn more about HashiCorp Vault.