Integrate with Vault

Vault is a popular open source secret management tool that you can use to set up a secure, private key infrastructure (PKI) and manage TLS certificates. In this setup, you install a Vault instance in the Gloo management cluster that serves as the root certificate authority. The root CA certificate and private key that are stored in Vault are used to sign and issue Istio intermediate CA certificates.

To enable Gloo Mesh to automatically derive intermediate CA certificates from the root CA in Vault, istiod is injected with the istiod-agent sidecar that authenticates and sends certificate signing requests to Vault. Instead of writing the intermediate CA certificate and key to the cacerts Kubernetes secret, the istiod-agent stores the credentials in memory, which adds an additional security layer to this approach. When the istiod-agent sidecar is deleted, the private key is also deleted. Istiod reads the intermediate CA key from the istiod-agent memory directly when signing leaf certificates for the workloads in the service mesh.

For more information about this approach, see Option 4: Integrate with Vault.

Before you begin

1. Complete the multicluster getting started guide to set up the following testing environment.
   • Three clusters along with environment variables for the clusters and their Kubernetes contexts.
   • The Gloo Platform CLI, meshctl, along with other CLI tools such as kubectl and istioctl.
   • The Gloo management server in the management cluster, and the Gloo agents in the workload clusters.
   • Istio installed in the workload clusters.
   • A simple Gloo workspace setup.
2. Install Bookinfo and other sample apps.

3. The default openssl version that is included in macOS is LibreSSL, which does not work with these instructions.

   Make sure that you have the OpenSSL version of openssl, not LibreSSL. The openssl version must be at least 1.1.

   1. Check the openssl version that is installed. If you see LibreSSL in the output, continue to the next step.

      openssl version
      

   2. Install the OpenSSL version (not LibreSSL). For example, you might use Homebrew.

      brew install openssl
      

   3. Review the output of the OpenSSL installation for the path of the binary file. You can choose to export the binary to your path, or call the entire path whenever the following steps use an openssl command.
      • For example, openssl might be installed along the following path: /usr/local/opt/openssl@3/bin/
      • To run commands, you can append the path so that your terminal uses this installed version of OpenSSL, and not the default LibreSSL. /usr/local/opt/openssl@3/bin/openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650...
4. Save the kubeconfig contexts for your clusters. Run kubectl config get-contexts, look for your cluster in the CLUSTER column, and get the context name in the NAME column. Note: Do not use context names with underscores. The context name is used as a SAN specification in the generated certificate that connects workload clusters to the management cluster, and underscores in SAN are not FQDN compliant. You can rename a context by running kubectl config rename-context "<oldcontext>" <newcontext>.

   export MGMT_CLUSTER=<mgmt-cluster-name>
   export REMOTE_CLUSTER=<remote-cluster-name>
   export MGMT_CONTEXT=<management-cluster-context>
   export REMOTE_CONTEXT=<remote-cluster-context>
   

Install and set up Vault

1. If not added already, add the HashiCorp Helm repository to your management cluster.

   helm repo add hashicorp https://helm.releases.hashicorp.com --kube-context ${MGMT_CONTEXT}
   helm repo update
   

2. Generate a root CA certificate and key for Vault. You can update the subj field to your domain.

   openssl req -new -newkey rsa:4096 -x509 -sha256 \
       -days 3650 -nodes -out root-cert.pem -keyout root-key.pem \
       -subj "/O=solo.io"
   

3. In the management cluster, install Vault in dev mode and enable debugging logs. For more information about setting up Vault in Kubernetes, see the Vault docs.

   helm install -n vault vault hashicorp/vault --set "injector.enabled=false" --set "server.logLevel=debug" --set "server.dev.enabled=true" --set "server.service.type=LoadBalancer" --kube-context="${MGMT_CONTEXT}" --create-namespace
   kubectl --context $MGMT_CONTEXT wait --for condition=Ready -n vault pod/vault-0
   

   Example output:

   pod/vault-0 condition met
   

4. Enable Vault userpass.

   kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c 'vault auth enable userpass'
   kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c 'vault write auth/userpass/users/admin password=admin policies=admins'
   

   Example output:

   Success! Enabled userpass auth method at: userpass/
   Success! Data written to: auth/userpass/users/admin
   

5. Enable Vault authentication along a path for the workload cluster.

   kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault auth enable -path=kube-${REMOTE_CLUSTER1}-mesh-auth kubernetes"
   kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault auth enable -path=kube-${REMOTE_CLUSTER2}-mesh-auth kubernetes"
   

   Example output:

   Success! Enabled kubernetes auth method at: kube-cluster1-mesh-auth/
   

6. Get the API token for the istiod-service-account. Note that depending on your Kubernetes version, the token is automatically created for you or must be created manually.

   • Kubernetes 1.21 and earlier
   • Kubernetes 1.22 and later

   1. Get the secret that the istiod-service-account uses.

      VAULT_SA_NAME_C1=$(kubectl --context $REMOTE_CONTEXT1 get sa istiod-service-account -n istio-system -o jsonpath="{.secrets[*]['name']}")
      VAULT_SA_NAME_C2=$(kubectl --context $REMOTE_CONTEXT2 get sa istiod-service-account -n istio-system -o jsonpath="{.secrets[*]['name']}")
      

   2. Get the token values and save it as an environment variable.

      SA_TOKEN_C1=$(kubectl --context $REMOTE_CONTEXT1 get secret $VAULT_SA_NAME_C1 -n istio-system -o 'go-template={{ .data.token }}' | base64 --decode)
      SA_TOKEN_C2=$(kubectl --context $REMOTE_CONTEXT2 get secret $VAULT_SA_NAME_C2 -n istio-system -o 'go-template={{ .data.token }}' | base64 --decode)
      echo $SA_TOKEN_C1
      echo $SA_TOKEN_C2
      

   1. Create a token for the istiod-service-account service account and store this token in a secret.

      kubectl apply --context $REMOTE_CONTEXT1 -f - <<EOF 
      apiVersion: v1
      kind: Secret
      metadata:
        name: istiod-sa
        namespace: istio-system
        annotations:
          kubernetes.io/service-account.name: istiod-service-account
      type: kubernetes.io/service-account-token
      EOF
      

      kubectl apply --context $REMOTE_CONTEXT2 -f - <<EOF 
      apiVersion: v1
      kind: Secret
      metadata:
        name: istiod-sa
        namespace: istio-system
        annotations:
          kubernetes.io/service-account.name: istiod-service-account
      type: kubernetes.io/service-account-token
      EOF
      

   2. Verify that the token was created.

      kubectl get secret/istiod-sa --context $REMOTE_CONTEXT1 -n istio-system -o yaml 
      kubectl get secret/istiod-sa --context $REMOTE_CONTEXT2 -n istio-system -o yaml 
      

   3. Save the token in an environment variable.

      SA_TOKEN_C1=$(kubectl --context $REMOTE_CONTEXT1 get secret istiod-sa -n istio-system -o 'go-template={{ .data.token }}' | base64 --decode)
      SA_TOKEN_C2=$(kubectl --context $REMOTE_CONTEXT2 get secret istiod-sa -n istio-system -o 'go-template={{ .data.token }}' | base64 --decode)
      echo $SA_TOKEN_C1
      echo $SA_TOKEN_C2
      

      Example output:

      eyJh...
      eyJi...
      

7. Get the CA certificate for the service account.

   SA_CA_CRT_C1=$(kubectl config view --raw -o json | jq -r --arg wc $REMOTE_CONTEXT1 '. as $c | $c.contexts[] | select(.name == $wc) as $context | $c.clusters[] | select(.name == $context.context.cluster) | .cluster."certificate-authority-data"'| base64 -d)
   SA_CA_CRT_C2=$(kubectl config view --raw -o json | jq -r --arg wc $REMOTE_CONTEXT2 '. as $c | $c.contexts[] | select(.name == $wc) as $context | $c.clusters[] | select(.name == $context.context.cluster) | .cluster."certificate-authority-data"'| base64 -d)
   echo $SA_CA_CRT_C1
   echo $SA_CA_CRT_C2
   

   Example output:

   -----BEGIN CERTIFICATE-----
   ...
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   ...
   -----END CERTIFICATE-----
   

8. Get the address of your cluster.

   K8S_ADDR_C1=$(kubectl config view -o json | jq -r --arg wc $REMOTE_CONTEXT1 '. as $c | $c.contexts[] | select(.name == $wc) as $context | $c.clusters[] | select(.name == $context.context.cluster) | .cluster.server ')
   K8S_ADDR_C2=$(kubectl config view -o json | jq -r --arg wc $REMOTE_CONTEXT2 '. as $c | $c.contexts[] | select(.name == $wc) as $context | $c.clusters[] | select(.name == $context.context.cluster) | .cluster.server ')
   echo $K8S_ADDR_C1
   echo $K8S_ADDR_C2
   

   Example output:

   https://34.xxx.xxx.xxx
   https://35.xxx.xxx.xxx
   

9. Set the Kubernetes auth config for Vault to the mounted service account token.

   kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault write auth/kube-${REMOTE_CLUSTER1}-mesh-auth/config \
   token_reviewer_jwt="$SA_TOKEN_C1" \
   kubernetes_host="$K8S_ADDR_C1" \
   kubernetes_ca_cert='$SA_CA_CRT_C1' \
   disable_local_ca_jwt="true" \
   issuer='https://kubernetes.default.svc.cluster.local'"
   

   kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault write auth/kube-${REMOTE_CLUSTER2}-mesh-auth/config \
   token_reviewer_jwt="$SA_TOKEN_C2" \
   kubernetes_host="$K8S_ADDR_C2" \
   kubernetes_ca_cert='$SA_CA_CRT_C2' \
   disable_local_ca_jwt="true" \
   issuer='https://kubernetes.default.svc.cluster.local'"
   

   Example output:

   Success! Data written to: auth/kube-${REMOTE_CLUSTER}-mesh-auth/config
   Success! Data written to: auth/kube-${REMOTE_CLUSTER}-mesh-auth/config
   

10. Bind the istiod service account to the Vault PKI policy.

    kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault write \
    auth/kube-${REMOTE_CLUSTER1}-mesh-auth/role/gen-int-ca-istio-${REMOTE_CLUSTER1}-mesh \
    bound_service_account_names=istiod-service-account \
    bound_service_account_namespaces=istio-system \
    policies=gen-int-ca-istio-${REMOTE_CLUSTER1}-mesh \
    ttl=720h"
    

    kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault write \
    auth/kube-${REMOTE_CLUSTER2}-mesh-auth/role/gen-int-ca-istio-${REMOTE_CLUSTER2}-mesh \
    bound_service_account_names=istiod-service-account \
    bound_service_account_namespaces=istio-system \
    policies=gen-int-ca-istio-${REMOTE_CLUSTER2}-mesh \
    ttl=720h"
    

    Example output:

    Success! Data written to: auth/kube-${REMOTE_CLUSTER1}-mesh-auth/role/gen-int-ca-istio-${REMOTE_CLUSTER1}-mesh
    Success! Data written to: auth/kube-${REMOTE_CLUSTER2}-mesh-auth/role/gen-int-ca-istio-${REMOTE_CLUSTER2}-mesh
    

11. Initialize the Vault PKI.

    kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c 'vault secrets enable pki'
    

    Example output:

    Success! Enabled the pki secrets engine at: pki/
    

12. Set the Vault CA to the pem_bundle.

    kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault write -format=json pki/config/ca pem_bundle=\"$(cat root-key.pem root-cert.pem)\""
    

    Example output:

    {
      "request_id": "2aa29fd6-9fa3-3edd-2f8b-2a0e4c007e8c",
      "lease_id": "",
      "lease_duration": 0,
      "renewable": false,
      "data": {
        "imported_issuers": null,
        "imported_keys": null,
        "mapping": {
          "aa877391-b4f2-045d-63da-33521c91dc68": "8257875c-4016-f28e-288b-ecca33065097"
        }
      },
      "warnings": null
    }
    

13. Enable the Vault intermediate cert path. Replace ${REMOTE_CLUSTER} with your cluster's name.

    kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault secrets enable -path=pki_int_${REMOTE_CLUSTER1} pki"
    kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault secrets enable -path=pki_int_${REMOTE_CLUSTER2} pki"
    

    Example output:

    Success! Enabled the pki secrets engine at: pki_int_${REMOTE_CLUSTER1}/
    Success! Enabled the pki secrets engine at: pki_int_${REMOTE_CLUSTER2}/
    

14. Set the policy for the intermediate cert path. Replace $REMOTE_CLUSTER1 and $REMOTE_CLUSTER2 with your cluster names.

    kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c 'vault policy write gen-int-ca-istio-${REMOTE_CLUSTER1}-mesh - <<EOF
    path "pki_int_${REMOTE_CLUSTER1}/*" {
    capabilities = ["create", "read", "update", "delete", "list"]
    }
    path "pki/cert/ca" {
    capabilities = ["read"]
    }
    path "pki/root/sign-intermediate" {
    capabilities = ["create", "read", "update", "list"]
    }
    EOF'
    

    kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c 'vault policy write gen-int-ca-istio-${REMOTE_CLUSTER2}-mesh - <<EOF
    path "pki_int_${REMOTE_CLUSTER2}/*" {
    capabilities = ["create", "read", "update", "delete", "list"]
    }
    path "pki/cert/ca" {
    capabilities = ["read"]
    }
    path "pki/root/sign-intermediate" {
    capabilities = ["create", "read", "update", "list"]
    }
    EOF'
    

    Example output:

    Success! Uploaded policy: gen-int-ca-istio-${REMOTE_CLUSTER1}-mesh
    Success! Uploaded policy: gen-int-ca-istio-${REMOTE_CLUSTER2}-mesh
    

Now that Vault is set up in your clusters, you can use Vault as an intermediate CA provider. If you see any errors, review the troubleshooting section.

Update Gloo RBAC permissions

The istio-agent sidecar in each cluster needs to read and modify Gloo resources. To enable the necessary RBAC permissions, update the gloo-agent Helm release. You can update the Helm release by adding the following snippet to the YAML configuration file in your GitOps pipeline or directly with the helm upgrade command.

1. Follow the steps to Get your Helm chart values for the Gloo agent deployment.

2. Add the following code to your Helm values file.

   • Istio lifecycle manager
   • Manual Istio deployments

   istiodSidecar:
       createRoleBinding: true
       istiodServiceAccount:
           name: istiod-1-16-vault
           namespace: istio-system
   

   istiodSidecar:
       createRoleBinding: true
       istiodServiceAccount:
           name: istiod
           namespace: istio-system
   

3. Set the Gloo version as an environment variable.

   export GLOO_VERSION=2.4.1
   

4. Make sure that you have the Helm repo for the Gloo agent. Note that you might have a different name for the Helm repo, such as gloo-mesh-agent.

   helm repo add gloo-agent https://storage.googleapis.com/gloo-mesh-enterprise/gloo-mesh-agent --kube-context ${REMOTE_CONTEXT1}
   helm repo update --kube-context ${REMOTE_CONTEXT1}
   

5. Upgrade the Gloo agent Helm chart with the required RBAC permissions. Note that you might have a different name for the Helm repo, such as gloo-mesh-agent.

   helm upgrade -n gloo-mesh gloo-agent gloo-mesh-agent/gloo-mesh-agent --kube-context="${REMOTE_CONTEXT1}" --version=$GLOO_VERSION -f values-data-plane-env.yaml
   

6. Repeat these steps for each workload cluster.

Modify istiod

So far, you set up the Gloo agent on each cluster to use Vault to obtain the intermediate CA. Now, you can modify your Istio installation to support fetching and dynamically reloading the intermediate CA from Vault.

These steps vary based on your Istio installation method.

Enable Vault as an intermediate CA provider

Now, federate the two meshes together by using Gloo with Vault to establish trusted communication across the service meshes.

1. Get the endpoint for the Vault service in the management cluster.

   export VAULT_ENDPOINT="http://$(kubectl get svc/vault -n vault -o wide --context $MGMT_CONTEXT -o jsonpath='{.status.loadBalancer.ingress[0].*}')"
   echo $VAULT_ENDPOINT
   

   Example output:

   http://35.xxx.xxx.xxx
   

2. Get the name of your Istio mesh.

   export MESH=$(kubectl get meshes -n gloo-mesh --context $REMOTE_CONTEXT -o jsonpath='{.items[*].metadata.name}')
   echo $MESH
   

3. Create a root trust policy for the workload cluster so that the istiod agent on the workload cluster knows how to communicate with Vault on the management cluster. For more information about root trust policies, see the API docs.

   kubectl apply --context ${REMOTE_CONTEXT} -f - << EOF
   apiVersion: admin.gloo.solo.io/v2
   kind: RootTrustPolicy
   metadata:
     name: ${REMOTE_CLUSTER}
     namespace: gloo-mesh
   spec:
     applyToMeshes:
     - istio:
         clusterSelector:
           mesh: ${MESH}
         namespace: istio-system
         selector:
           app: istiod
           vault: ${REMOTE_CLUSTER}
     config:
       agentCa:
         vault:
           caPath: pki/root/sign-intermediate
           csrPath: pki_int_${REMOTE_CLUSTER}/intermediate/generate/exported
           server: $VAULT_ENDPOINT:8200
           kubernetesAuth:
             mountPath: /v1/auth/kube-${REMOTE_CLUSTER}-mesh-auth
             role: gen-int-ca-istio-${REMOTE_CLUSTER}-mesh
   EOF
   

4. Restart the istiod deployment. Note that you cannot update Istio resources until istiod is running again.

   kubectl rollout restart deployment -l app=istiod -n istio-system --context ${REMOTE_CONTEXT}
   

5. Repeat the previous steps for each workload cluster with Istio.

Verify traffic uses the root CA

Now that the Istio control plane is patched with the gloo-mesh-istiod-agent sidecar, you can verify that all of the service mesh traffic is secured by using the root CA that you generated for Vault in the previous section.

To verify, you can check the root-cert.pem in the istio-ca-root-cert config map that Istio propagates for the initial TLS connection. The following example checks the propagated root-cert.pem against the local certificate that you supplied to Vault in the previous section.

1. Check the Vault version that the management cluster runs.

   kubectl --context="${MGMT_CONTEXT}" exec -n vault vault-0 -- /bin/sh -c "vault version"
   

   Example output:

   Vault v1.11.3 (17250b25303c6418c283c95b1d5a9c9f16174fe8), built 2022-08-26T10:27:10Z
   

2. Check the root trust policy for errors.

   kubectl describe RootTrustPolicy ${REMOTE_CLUSTER} -n gloo-mesh --context ${REMOTE_CONTEXT}
   

3. Check the mesh for errors.

   kubectl describe mesh ${MESH} -n gloo-mesh --context ${REMOTE_CONTEXT}
   

4. From your terminal, navigate to the same directory as the root-cert.pem file that you previously created. Or, if you are using an existing Vault deployment, save the root certificate as root-cert.pem.

5. Check the difference between the root certificate that istiod uses and the Vault root certificate. If installed correctly, the files are the same.

   kubectl --context=$REMOTE_CONTEXT get cm -n bookinfo istio-ca-root-cert -ojson | jq -r  '.data["root-cert.pem"]' | diff -q root-cert.pem -
   

6. If you see that the files differ, check the istiod logs.

   kubectl logs -n istio-system --context ${REMOTE_CONTEXT} $(kubectl get pods -n istio-system -l app=istiod --context ${REMOTE_CONTEXT} | cut -d" " -f1 | tail -1) > istiod-logs.txt
   

7. Check the issued certificates for errors.

   kubectl describe issuedcertificates -n istio-system --context ${REMOTE_CONTEXT}
   

For more troubleshooting steps, see Troubleshoot errors with the Vault setup or Debug Istio.

Rotating certificates for Istio workloads

When certificates are issued, pods that are managed by Istio must be restarted to ensure they pick up the new certificates. The certificate issuer creates a PodBounceDirective, which contains the namespaces and labels of the pods that must be restarted. For more information about how certificate rotation works in Istio, review the video series in this blog post.

Note: To avoid potential downtime for your apps in production, disable the PodBounceDirective feature by setting autoRestartPods to false. Then, control pod restarts in another way, such as a rolling update.

1. Get your root trust policies.

   kubectl get roottrustpolicy --context ${MGMT_CONTEXT} -A
   

2. In the root trust policy, remove or set the autoRestartPods field to false.

   kubectl edit roottrustpolicy --context ${MGMT_CONTEXT} -n <namespace> <root-trust-policy>
   

   apiVersion: admin.gloo.solo.io/v2
   kind: RootTrustPolicy
   metadata:
     name: istio-ingressgateway
     namespace: gloo-mesh
   spec:
     config:
       autoRestartPods: false
       ...
   

3. To ensure pods pick up the new certificates, restart the istiod pod in each remote cluster.

   kubectl --context {$REMOTE_CONTEXT} -n istio-system patch deployment istiod \
       -p "{\"spec\":{\"template\":{\"metadata\":{\"labels\":{\"date\":\"`date +'%s'`\"}}}}}"
   

4. Restart your app pods that are managed by Istio, such as by using a rolling update strategy.

Troubleshoot errors with the Vault setup

If you have errors with the steps to install Vault, review the following table.

Example script

You can review or adapt the following example script for your own use.

Environment details:

• 3 cluster setup: 1 management cluster and 2 workload clusters
• Gloo installed on all clusters
• Istio installed on the workload clusters, including the httpbin sample app

The script organizes the functions into the following commands that you can run.

1. Copy the GitHub Gist, also rendered after these steps.

2. Make sure to update the environment variables at the beginning of the script for the Gloo version, management, and workload cluster contexts that you want to use.

3. Read and execute the Vault script.

   source ~/Downloads/lib.sh
   

4. Execute the Vault functions in order. If you notice errors, try running them one at a time, or refer to the troubleshooting section.

   • Run all functions at once:

     vault-install-all
     

   Run functions separately, one at a time:

   1. Install Vault on the management cluster.

      vault-install
      

   2. Enable Vault authentication for Kubernetes.

      vault-enable-kube-auth
      

   3. Set up the CA in Vault.

      vault-setup-ca
      

5. Verify Vault. Note that this verification assumes you have httpbin on each workload cluster in the httpbin namespace.

   vault-verify
   

Example script gist

GitHub Gist