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 and configure your Vault Dedicated instance with AppRole authentication.

Install Vault Secrets Operator

Install the Vault Secrets Operator using Helm.

1. Add the HashiCorp Helm repository.

   helm repo add hashicorp https://helm.releases.hashicorp.com
   helm repo update
   

2. Install Vault Secrets Operator.

   helm install vault-secrets-operator \
     hashicorp/vault-secrets-operator \
     --namespace vault-secrets-operator-system \
     --create-namespace \
     --version 0.9.0
   

3. Verify the installation.

   kubectl get pods -n vault-secrets-operator-system
   

   Wait until all pods are in Running state.

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

   kubectl get crd | grep vault
   

   You should see CRDs like vaultauths, vaultconnections, vaultdynamicsecrets, and vaultstaticsecrets.

Configure VaultConnection and VaultAuth

Configure VSO to connect to your Vault Dedicated instance using VaultConnection and VaultAuth resources.

Create VaultStaticSecret

Create a VaultStaticSecret resource to sync secrets from Vault Dedicated to Kubernetes.

1. Create a vaultstaticsecret.yaml file.

   touch vaultstaticsecret.yaml
   

2. Add the following configuration.

   apiVersion: secrets.hashicorp.com/v1beta1
   kind: VaultStaticSecret
   metadata:
     name: vault-dedicated-app-secret
     namespace: default
   spec:
     vaultAuthRef: vault-dedicated-auth
     mount: kv
     type: kv-v2
     path: example_username_password
     refreshAfter: 1h
     destination:
       name: my-k8s-secret-vso
       create: true
   

   This configuration fetches the secret from kv/data/example_username_password in Vault Dedicated and creates a Kubernetes secret named my-k8s-secret-vso. The secret refreshes every hour.

3. Apply the VaultStaticSecret.

   kubectl apply -f vaultstaticsecret.yaml
   

4. Verify the secret was synced.

   kubectl get vaultstaticsecret vault-dedicated-app-secret -n default
   kubectl get secret my-k8s-secret-vso -n default -o json | jq '.data | map_values(@base64d)'
   

   Example output:

   {
       "password": "vso-secure-pass-123",
       "username": "vso-user"
   }
   

Deploy an app to the cluster

Deploy an application that uses the synced secrets from Vault Dedicated.

1. Create a test deployment.

   cat <<EOF | kubectl apply -f -
   apiVersion: v1
   kind: Pod
   metadata:
     name: test-app-vso
     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-vso
             key: username
       - name: PASSWORD
         valueFrom:
           secretKeyRef:
             name: my-k8s-secret-vso
             key: password
   EOF
   

2. Check the pod logs.

   kubectl logs test-app-vso -n default
   

   Expected output:

   Username: vso-user
   Password: vso-secure-pass-123
   

(Optional) Clean up resources

If you no longer need the resources, remove them from your account.

1. Delete the test namespace and resources.

   kubectl delete pod test-app-vso -n default
   kubectl delete vaultstaticsecret vault-dedicated-app-secret -n default
   kubectl delete vaultauth vault-dedicated-auth -n default
   kubectl delete vaultconnection vault-dedicated-connection -n default
   kubectl delete secret approle-secret -n default
   

2. Uninstall Vault Secrets Operator.

   helm uninstall vault-secrets-operator -n vault-secrets-operator-system
   kubectl delete namespace vault-secrets-operator-system
   

3. Delete your test cluster.

   ibmcloud ks cluster rm --cluster vso-test-cluster
   

4. Clean up Vault Dedicated test data.

   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

Key considerations when using Vault Secrets Operator:

1. Authentication methods: VSO does not support direct token authentication. You must use AppRole, Kubernetes, JWT, AWS, or GCP authentication methods.

2. SecretID key name: When creating a Kubernetes secret for AppRole authentication, the key must be named id, not secret-id or secretId.

3. Refresh interval: The refreshAfter field determines how often VSO checks for secret updates. Balance between freshness and API load.

4. Automatic rollouts: Use rolloutRestartTargets in your VaultStaticSecret to automatically restart deployments when secrets change.

5. Vault Dedicated mount path: Vault Dedicated uses kv/ as the default mount path for the KV secrets engine, not secret/.

6. Vault Dedicated namespaces: Vault Dedicated uses Vault Enterprise namespaces. The default namespace is admin. Always specify the correct namespace in your VaultAuth configuration.

7. TLS configuration: For production, configure proper TLS certificate validation instead of using skipTLSVerify.

Next steps

Great job! In this tutorial, you learned how to use Vault Secrets Operator to integrate Vault Dedicated with your Kubernetes cluster. Explore more VSO capabilities:

• Learn about VaultDynamicSecret for dynamic database credentials.
• Explore External Secrets Operator as an alternative multi-provider solution.
• Review the Vault Secrets Operator documentation.
• Learn more about Vault features and configurations.