diff --git a/website/content/docs/platform/k8s/helm/examples/injector-tls-cert-manager.mdx b/website/content/docs/platform/k8s/helm/examples/injector-tls-cert-manager.mdx new file mode 100644 index 0000000000..19c5b058f7 --- /dev/null +++ b/website/content/docs/platform/k8s/helm/examples/injector-tls-cert-manager.mdx @@ -0,0 +1,149 @@ +--- +layout: 'docs' +page_title: 'Vault Agent Injector TLS with Cert-Manager' +sidebar_current: 'docs-platform-k8s-examples-injector-tls-cert-manager' +description: |- + Describes how to set up the Vault Agent Injector with certificates and keys generated by cert-manager. +--- + +# Vault Agent Injector TLS with Cert-Manager + +The following instructions demonstrate how to configure the Vault Agent Injector to use certificates generated by [cert-manager](https://cert-manager.io/). This allows you to run multiple replicas of the Vault Agent Injector in a Kubernetes cluster. + +## Prerequisites + +Install cert-manager if not already installed (see the [cert-manager documentation](https://cert-manager.io/docs/installation/)). For example, with helm: + +```shell +$ helm repo add jetstack https://charts.jetstack.io +$ helm repo update +$ helm install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set installCRDs=true +``` + +## Create a Certificate Authority (CA) + +For this example we will bootstrap a self-signed certificate authority (CA) [Issuer](https://cert-manager.io/docs/configuration/). If you already have a [ClusterIssuer](https://cert-manager.io/docs/concepts/issuer/) configured for your cluster, you may skip this step. + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned +spec: + selfSigned: {} +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: injector-selfsigned-ca +spec: + isCA: true + commonName: Agent Inject CA + secretName: injector-ca-secret + duration: 87660h # 10 years + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned + kind: Issuer + group: cert-manager.io +--- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: injector-ca-issuer +spec: + ca: + secretName: injector-ca-secret +``` + +Save that to a file named `ca-issuer.yaml`, and apply to your Kubernetes cluster: + +```console +$ kubectl apply -n vault -f ca-issuer.yaml +issuer.cert-manager.io/selfsigned created +certificate.cert-manager.io/injector-selfsigned-ca created +issuer.cert-manager.io/injector-ca-issuer created + +$ kubectl -n vault get issuers -o wide +NAME READY STATUS AGE +injector-ca-issuer True Signing CA verified 7s +selfsigned True 7s + +$ kubectl -n vault get certificates injector-selfsigned-ca -o wide +NAME READY SECRET ISSUER STATUS AGE +injector-selfsigned-ca True injector-ca-secret selfsigned Certificate is up to date and has not expired 32s +``` + +## Create the Vault Agent Injector Certificate + +Next we can create a request for cert-manager to generate a certificate and key +signed by the certificate authority above. This certificate and key will be used +by the Vault Agent Injector for TLS communications with the Kubernetes API. + +The Certificate request object references the CA issuer created above, and specifies the name of the Secret where the CA, Certificate, and Key will be stored by cert-manager. + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: injector-certificate +spec: + secretName: injector-tls + duration: 24h + renewBefore: 144m # roughly 10% of 24h + dnsNames: + - vault-agent-injector-svc + - vault-agent-injector-svc.vault + - vault-agent-injector-svc.vault.svc + issuerRef: + name: injector-ca-issuer + commonName: Agent Inject Cert +``` + +~> **Important Note:** The dnsNames for the certificate must be configured to use the name +of the Vault Agent Injector Kubernetes service and namespace where it is deployed. + +In this example the Vault Agent Injector service name is `vault-agent-injector-svc` in the `vault` namespace. +This uses the pattern `..svc`. + +Save the Certificate yaml to a file and apply to your cluster: + +```shell +$ kubectl -n vault apply -f injector-certificate.yaml +certificate.cert-manager.io/injector-certificate created + +$ kubectl -n vault get certificates injector-certificate -o wide +NAME READY SECRET ISSUER STATUS AGE +injector-certificate True injector-tls injector-ca-issuer Certificate is up to date and has not expired 41s + +$ kubectl -n vault get secret injector-tls +NAME TYPE DATA AGE +injector-tls kubernetes.io/tls 3 6m59s +``` + +## Configuration + +Now that a certificate authority and a signed certificate have been created, we can now configure +Helm and the Vault Agent Injector to use them. + +First, collect the base64-encoded CA from the Certificate secret: + +```shell +$ export CA_BUNDLE=$(kubectl -n vault get secrets injector-tls -o json | jq -r '.data."ca.crt"') +``` + +Next, install the Vault Agent Injector with the following custom values: + +```shell +$ helm install vault hashicorp/vault \ + --namespace=vault \ + --set injector.replicas=2 \ + --set injector.leaderElector.enabled=false \ + --set injector.certs.secretName=injector-tls \ + --set injector.certs.caBundle=${CA_BUNDLE?} +``` diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index c0a726ab78..90b382cf4d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1308,6 +1308,10 @@ { "title": "Vault Agent Injector TLS Configuration", "path": "platform/k8s/helm/examples/injector-tls" + }, + { + "title": "Vault Agent Injector TLS with Cert-Manager", + "path": "platform/k8s/helm/examples/injector-tls-cert-manager" } ] }