feat: adding documentation describing how to configure Vault for mTLS

[rodrigorfk]

Preview: https://deploy-preview-1390--cert-manager-website.netlify.app/docs/configuration/vault/#accessing-a-vault-server-with-mtls-enforced

This is related to cert-manager/cert-manager#6614

[netlify]

✅ Deploy Preview for cert-manager-website ready!

Name	Link
🔨 Latest commit	d285b0e
🔍 Latest deploy log	https://app.netlify.com/sites/cert-manager-website/deploys/65cfa9e8061d07000879ce35
😎 Deploy Preview	https://deploy-preview-1390--cert-manager-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[wallrj]

Thanks @rodrigorfk

I like these new docs, but as an inexperienced vault user I really struggled to get everything setup. I'd like even more detail if possible and more links to official Hashicorp documentation.

Here's what I did:

• Create Vault serving certificate and CA

step certificate create "Example Server Root CA" server_ca.crt server_ca.key \
  --profile root-ca \
  --not-after=87600h \
  --no-password \
   --insecure
   

step certificate create vault.vault vault.crt vault.key \
  --profile leaf \
  --not-after=8760h \
  --ca ./server_ca.crt \
  --ca-key server_ca.key \
  --no-password \
  --insecure

• Create Vault client certificate and CA

step certificate create "Example Client Root CA" client_ca.crt client_ca.key \
  --profile root-ca \
  --not-after=87600h \
  --no-password \
   --insecure 

step certificate create client.vault vault_client.crt vault_client.key \
  --profile leaf \
  --not-after=8760h \
  --ca ./client_ca.crt \
  --ca-key client_ca.key \
  --no-password \
  --insecure

• Create Vault namespace

kubectl create ns vault

• Create Secret containing Vault serving certificate, Vault client certificate (for use by the readiness probe) and Vault client CA cert (the certificate that Vault will use to verify client certificates.

kubectl create secret generic vault-tls \
  --namespace vault \
  --from-file=server.key=vault.key \
  --from-file=server.crt=vault.crt \
  --from-file=client-ca.crt=client_ca.crt \
  --from-file=client.crt=vault_client.crt \
  --from-file=client.key=vault_client.key

• Deploy Vault

# vault-values.yaml
global:
   tlsDisable: false
injector:
  enabled: false
server:
  dataStorage:
    enabled: false
  standalone:
    enabled: true
    config: |
      listener "tcp" {
        address = "[::]:8200"
        cluster_address = "[::]:8201"
        tls_disable = false
        tls_client_ca_file = "/vault/tls/client-ca.crt"
        tls_cert_file = "/vault/tls/server.crt"
        tls_key_file = "/vault/tls/server.key"
        tls_require_and_verify_client_cert = true
      }
  extraArgs: "-dev-tls -dev-listen-address=[::]:8202"
  extraEnvironmentVars:
    VAULT_TLSCERT: /vault/tls/server.crt
    VAULT_TLSKEY: /vault/tls/server.key
    VAULT_CLIENT_CERT: /vault/tls/client.crt
    VAULT_CLIENT_KEY: /vault/tls/client.key
  volumes:
    - name: vault-tls
      secret:
        defaultMode: 420
        secretName: vault-tls
  volumeMounts:
    - mountPath: /vault/tls
      name: vault-tls
      readOnly: true

helm upgrade vault hashicorp/vault --install --namespace vault --create-namespace --values vault-values.yaml

• Configure Vault server for Kubernetes auth

kubectl -n vault exec pods/vault-0  -- \
        vault auth enable --tls-skip-verify kubernetes

kubectl -n vault exec pods/vault-0  -- \
        vault write --tls-skip-verify \
        auth/kubernetes/role/vault-issuer \
        bound_service_account_names=vault-issuer \
        bound_service_account_namespaces=application-1 \
        audience="vault://application-1/vault-issuer" \
        policies=vault-issuer \
        ttl=1m

kubectl -n vault exec pods/vault-0 -- \
        vault write --tls-skip-verify \
        auth/kubernetes/config \
        kubernetes_host=https://kubernetes.default

• Create application namespace

kubectl create ns application-1

• Create Service account

kubectl create serviceaccount -n application-1 vault-issuer

• Create Role and Binding

# rbac.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: vault-issuer
  namespace: application-1
rules:
  - apiGroups: ['']
    resources: ['serviceaccounts/token']
    resourceNames: ['vault-issuer']
    verbs: ['create']
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: vault-issuer
  namespace: application-1
subjects:
  - kind: ServiceAccount
    name: cert-manager
    namespace: cert-manager
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: vault-issuer

kubectl apply -f rbac.yaml

• Create Issuer

export CA_BUNDLE=$(base64 -w 0 server_ca.crt)

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vault-issuer
  namespace: application-1
spec:
  vault:
    path: pki_int/sign/application-1
    server: https://vault.vault:8200
    caBundle: ${CA_BUNDLE}
    clientCertSecretRef:
      name: vault-client-tls
      key: vault_client.crt
    clientKeySecretRef:
      name: vault-client-tls
      key: vault_client.key
    auth:
      kubernetes:
        role: vault-issuer
        mountPath: /v1/auth/kubernetes
        serviceAccountRef:
          name: vault-issuer

envsubst < vault-issuer.yaml | kubectl -f -

• Check Issuer status

kubectl describe issuer -n application-1

[rodrigorfk]

@wallrj , thanks for providing such detailed steps, I have merged it into the documentation, could you please have another look?

[wallrj]

Thanks.

I simplified some of the file names and used caBundleSecretRef to avoid having to base64 encode the ca and use envsubst.

Tested your branch again and it worked.

[wallrj]

Thanks!

/lgtm

[jetstack-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: wallrj

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [wallrj]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment