docs: vault-k8s and cert-manager (#12281)

Adding an example of configuring vault-k8s to use cert-manager for
managing the webhook certs.

Co-authored-by: Calvin Leung Huang <1883212+calvn@users.noreply.github.com>
Co-authored-by: Ben Ash <32777270+benashz@users.noreply.github.com>

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 `<k8s service name>.<k8s namespace>.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?}
+```

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"
                   }
                 ]
               }