capi docs: add intermediate ca how-to

We're adding a guide that shows how intermediate CAs can be
generated using HashiCorp Vault and passed to CAPI using
management cluster secrets.

docs/src/capi/howto/index.md

@@ -22,6 +22,7 @@ Perform an in-place upgrade <in-place-upgrades>
 Upgrade the providers of a management cluster <upgrade-providers>
 Migrate the management cluster <migrate-management>
 Refresh workload cluster certificates <refresh-certs>
+How to use intermediate CAs with Vault <intermediate-ca>
 Troubleshooting <troubleshooting>
 ```
 

docs/src/capi/howto/intermediate-ca.md

@@ -0,0 +1,46 @@
+# How to use intermediate CAs with Vault
+
+By default, the ClusterAPI provider will generate self-signed CA certificates
+for the workload clusters.
+
+Follow this guide to prepare an intermediate Certificate Authority (CA) using
+HashiCorp Vault and then configure ClusterAPI to use the generated certificates.
+
+## Preparing Vault
+
+For the purpose of this guide, we are going to install HashiCorp Vault using
+snap and start a Vault server in development mode.
+
+```bash
+sudo snap install vault
+vault server -dev &
+```
+
+Specify the vault address through an environment variable:
+
+```bash
+export VAULT_ADDR=http://localhost:8200
+```
+
+Enable the PKI secrets engine and set the maximum lease time to 10 years
+(87600 hours):
+
+```bash
+vault secrets enable pki
+vault secrets tune -max-lease-ttl=87600h pki
+```
+
+## Generating the CA certificates
+
+Generate the root CA certificate:
+
+```bash
+vault write -format=json pki/root/generate/internal \
+    common_name=vault \
+    ttl=87600h \
+    > root_ca.json
+```
+
+Generate the intermediate CA certificate. We need the resulting Certificate
+Signing Request (CSR) and private key, so for convenience we'll use JSON
+formatting.