Set up the cert-manager issuer
Enterprise
Appropriate Vault EnterpriseĀ license required
Configure a VaultIssuer or VaultClusterIssuer resource so that cert-manager
Certificate resources receive certificates signed by the Vault
PKI secrets engine. Refer to
Issue certificates with cert-manager
to learn how the issuers work.
The examples on this page use the following names. Replace them with values that match your environment:
app- The Kubernetes namespace where your application requests certificates.vault-secrets-operator- The Kubernetes namespace where the Vault Secrets Operator runs.pki- The Vault PKI secrets engine mount path.example-dot-com- The Vault PKI role that signs certificates.
Before you start
Use Vault Enterprise. The issuers only work with a licensed Vault Enterprise server.
Configure the PKI secrets engine with at least one issuer. The examples on this page use a PKI mount at
pki. To create a certificate authority in Vault, refer to Quick start: root CA setup and Quick start: intermediate CA setup.Install cert-manager in your Kubernetes cluster.
Install Helm 3.7 or later.
Use Vault Secrets Operator 2.0.0 or later. Replace
<VSO_VERSION>in the Helm commands on this page with the version you install.Create the application namespace if it does not already exist. The examples use the
appnamespace.Configure a Vault auth method for Kubernetes workloads. The examples on this page use the Kubernetes auth method mounted at
kubernetes. Refer to Vault authentication in detail for the other methods that the Vault Secrets Operator supports.Check your permissions. You must have permission to:
- Create Vault policies, auth roles, and PKI roles.
- Create namespaced and cluster-scoped resources in Kubernetes.
Optional: install
cmctl. The cert-manager CLI lets you approve certificate requests manually and inspect certificate status.
Step 1: Create a PKI role
Create a PKI role that defines which certificates Vault can sign for the issuer. The role controls which names Vault allows, the key types Vault accepts, and the certificate lifetime:
$ vault write pki/roles/example-dot-com \
allowed_domains=example.com \
allow_subdomains=true \
key_type=any \
ttl=24h \
max_ttl=72h
The role's ttl applies when a Certificate omits spec.duration. Vault
shortens a requested duration that exceeds max_ttl, and rejects a request when
the certificate would expire after the issuing CA certificate. key_type=any
accepts the key algorithms that cert-manager generates. Refer to
Create/Update role for all role
parameters.
Step 2: Create a Vault policy and auth role
The Vault Secrets Operator authenticates to Vault as itself, not as cert-manager. Create a policy and an auth role for the Vault Secrets Operator to use when it signs certificates.
Create a policy that grants access to the PKI
signendpoint and to the Vault Enterprise license status endpoint:$ vault policy write pki-issuer - <<EOF path "pki/sign/example-dot-com" { capabilities = ["create", "update"] } path "sys/license/status" { capabilities = ["read"] } EOFWhen you set
issuerRefon the issuer, the Vault Secrets Operator uses thepki/issuer/<issuerRef>/sign/<role>path instead. Grant the path that matches your issuer configuration, for examplepki/issuer/example-issuer/sign/example-dot-com.Create a Kubernetes auth role that binds the policy to a service account. Use a dedicated service account named
pki-issuer, which you create in Step 4. Do not use this account for application Pods. The namespace of the service account depends on the issuer type:A
VaultIssuerauthenticates with a service account in the issuer's namespace:$ vault write auth/kubernetes/role/pki-issuer \ bound_service_account_names=pki-issuer \ bound_service_account_namespaces=app \ token_policies=pki-issuer \ audience=vault \ token_ttl=1h
Step 3: Install the Vault Secrets Operator with approval enabled
cert-manager must approve each CertificateRequest before the Vault Secrets
Operator signs it. Set certManager.approverRBAC.enabled=true to let the
cert-manager built-in approver approve requests for the Vault Secrets Operator
issuers.
Add the HashiCorp Helm repository:
$ helm repo add hashicorp https://helm.releases.hashicorp.comInstall the Vault Secrets Operator:
$ helm install \ --version <VSO_VERSION> \ --create-namespace \ --namespace vault-secrets-operator \ --set certManager.approverRBAC.enabled=true \ vault-secrets-operator \ hashicorp/vault-secrets-operator
When you enable this setting, cert-manager approves every request for the Vault Secrets Operator issuers. Use approver-policy instead when you need to restrict which certificates each namespace can request. Refer to Certificate request approval for the available approval options.
If the cert-manager controller runs with a service account other than
cert-manager in the cert-manager namespace, also set
certManager.approverRBAC.serviceAccountName and
certManager.approverRBAC.serviceAccountNamespace.
Step 4: Create the connection and auth resources
Create the dedicated service account, a VaultConnection resource that points
to your Vault server, and a VaultAuth resource that uses the auth role from
Step 2.
Create the resources in the application namespace:
apiVersion: v1
kind: ServiceAccount
metadata:
name: pki-issuer
namespace: app
automountServiceAccountToken: false
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultConnection
metadata:
name: vault-connection
namespace: app
spec:
address: https://vault.example.com:8200
---
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuth
metadata:
name: pki-issuer
namespace: app
spec:
vaultConnectionRef: vault-connection
method: kubernetes
mount: kubernetes
kubernetes:
role: pki-issuer
serviceAccount: pki-issuer
audiences:
- vault
The service account does not need automatic token mounting. Restrict who can use this service account in Pods or request its tokens.
Save the resources to a file named vault-auth.yaml. Apply the file and
confirm that the READY column shows True for the VaultAuth:
$ kubectl apply --filename vault-auth.yaml
$ kubectl get vaultauth --all-namespaces
Refer to the
VaultConnection
and VaultAuth API
reference for TLS settings and other authentication methods.
Step 5: Create the issuer
Create the issuer that references the VaultAuth resource and the PKI role.
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultIssuer
metadata:
name: vault-issuer
namespace: app
spec:
vaultAuthRef: pki-issuer
mount: pki
role: example-dot-com
You can also set the following optional fields:
issuerRef- Signs certificates with a specific issuer in the PKI mount.namespace- Sets the Vault Enterprise namespace of the PKI mount.excludeCNFromSans- Set tofalseto let Vault add the common name to the certificate SANs. Defaults totrue.
Save the issuer to a file named vault-issuer.yaml. Apply the file and wait
until the READY column shows True:
$ kubectl apply --filename vault-issuer.yaml
$ kubectl get vaultissuer --namespace app
$ kubectl get vaultclusterissuer
When the issuer does not become ready, inspect the status.error field and the
issuer events. Refer to
Troubleshoot the cert-manager issuer
for common causes.
Step 6: Request a certificate
Create a cert-manager Certificate resource in the application namespace. Set
issuerRef.group to secrets.hashicorp.com and issuerRef.kind to the issuer
type:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: web
namespace: app
spec:
secretName: web-tls
commonName: web.example.com
dnsNames:
- web.example.com
duration: 24h
renewBefore: 8h
issuerRef:
group: secrets.hashicorp.com
kind: VaultIssuer
name: vault-issuer
Include the common name in dnsNames. The issuers exclude the common name from
the certificate SANs by default, and many TLS clients reject certificates
without SANs.
Save the certificate to a file named certificate.yaml and apply it:
$ kubectl apply --filename certificate.yaml
cert-manager creates a CertificateRequest, the approver approves it, and the
Vault Secrets Operator signs it. When you do not use automatic approval, approve
the request with cmctl:
$ cmctl approve --namespace app <CERTIFICATE_REQUEST_NAME>
Step 7: Verify the certificate
Confirm that the
CertificateRequestis approved and ready. TheAPPROVEDandREADYcolumns showTrue:$ kubectl get certificaterequest --namespace appConfirm that the
Certificateis ready:$ kubectl get certificate web --namespace appInspect the issued certificate in the Kubernetes Secret:
$ kubectl get secret web-tls --namespace app \ --output jsonpath='{.data.tls\.crt}' \ | base64 --decode \ | openssl x509 -noout -subject -issuer -dates -ext subjectAltNameConfirm the SANs include
web.example.comand check the intended expiration, accounting for Vault's backdating and CA expiration settings.Confirm that the Vault Secrets Operator signed the certificate. The
CertificateIssuedevent has the messageCertificate issued successfully:$ kubectl get events --namespace app \ --field-selector involvedObject.kind=CertificateRequest
cert-manager renews the certificate before it expires and updates the
web-tls Secret. Your application must reload the Secret to use the renewed
certificate.