Migrate from the cert-manager Vault issuer
Enterprise
Appropriate Vault EnterpriseĀ license required
Replace the built-in cert-manager Issuer or ClusterIssuer with a Vault
Secrets Operator VaultIssuer or VaultClusterIssuer. Keep your Certificate
resources and Secret names, and migrate one certificate at a time by changing
its issuerRef. You may also need an explicit spec.duration to preserve its
intended lifetime.
Keep the original issuer and its credentials until migration and renewal succeed so that you can roll back.
Before you start
- Use Vault Enterprise, with cert-manager already issuing certificates through Vault.
- Install Helm 3.7 or later and
jq. - Use Vault Secrets Operator 2.0.0 or later. Replace
<VSO_VERSION>in the Helm commands on this page with the version you install or upgrade to. - Check your permissions to update Vault policies and auth roles, install or upgrade the operator, and manage Kubernetes issuers and certificates.
- Plan a change window. Changing
issuerReftriggers reissuance and can rotate the private key, depending onspec.privateKey.rotationPolicy.
The examples use the application namespace app, the operator namespace
vault-secrets-operator, and the signing path pki/sign/example-dot-com.
Replace these values with your configuration.
If you manage cert-manager or Vault Secrets Operator resources with a GitOps
tool, such as Argo CD or Flux, make the resource changes in this guide in your
source repository instead of with kubectl. Otherwise, the next sync can
revert them.
Step 1: Plan the configuration
Review the following settings before you migrate, and update your configuration where needed:
- Authentication: The issuers authenticate to Vault with a
VaultAuthresource, which supports the Kubernetes, JWT, AppRole, AWS, and GCP auth methods. If your current issuer uses a static token (tokenSecretRef) or TLS certificate authentication (clientCertificate), set up one of these methods in Vault before you migrate. Refer to Vault authentication in detail. - Vault connection: The issuers connect to Vault with a
VaultConnectionresource, which verifies the Vault server certificate with a CA bundle. If your current issuer setsclientCertSecretRefandclientKeySecretRefbecause your Vault endpoint requires client certificates, confirm that the Vault Secrets Operator can connect to the endpoint before you migrate. Keep TLS verification enabled. - Certificate lifetime: When a
Certificatedoes not setspec.duration, the cert-manager Vault issuer requests 90 days (2160h). With the Vault Secrets Operator issuers, Vault applies the PKI role'sttlinstead. To keep the current lifetime, setspec.durationon the certificate when you migrate it, rather than changing a shared PKI role. Vault shortens a requested duration that exceeds the role'smax_ttl. Vault rejects a request when the certificate would expire after the issuing CA certificate, unless the issuer'sleaf_not_after_behaviorsetting allows it. - Signing path names: Kubernetes rejects
mount,role, orissuerRefvalues that contain..or unsupported characters. Check your current signing path against the API reference.
Step 2: Inventory the issuers and certificates
Export your issuers. For each
spec.vaultblock, record the server, signing path, Vault namespace, TLS, and authentication settings:$ kubectl get issuer,clusterissuer --all-namespaces --output yaml \ > issuer-inventory.yamlFind certificates referencing the original issuer. Match its namespace, name, kind, and API group:
$ kubectl get certificate --namespace app --output json \ | jq --raw-output '.items[] | select(.spec.issuerRef.name == "vault-issuer" and (.spec.issuerRef.kind // "Issuer") == "Issuer" and (.spec.issuerRef.group // "cert-manager.io") == "cert-manager.io") | "\(.metadata.namespace)/\(.metadata.name)"'Save a rollback patch for each certificate, using a separate file per certificate. This patch captures its issuer and lifetime settings, including absent fields as
null, so that the rollback patch removes values that the migration adds:$ kubectl get certificate web --namespace app --output json \ | jq '{spec: {issuerRef: {name: .spec.issuerRef.name, kind: .spec.issuerRef.kind, group: .spec.issuerRef.group}, duration: .spec.duration, renewBefore: .spec.renewBefore, renewBeforePercentage: .spec.renewBeforePercentage}}' \ > web-rollback.json
Step 3: Grant access to Vault
Create a dedicated policy. Replace the signing path with the original issuer's
spec.vault.path, including anyissuer/<issuerRef>segment:$ vault policy write pki-issuer - <<EOF path "pki/sign/example-dot-com" { capabilities = ["create", "update"] } path "sys/license/status" { capabilities = ["read"] } EOFCreate an auth role for the operator. This Kubernetes auth example uses a dedicated service account named
pki-issuer, created in Step 4:$ vault write auth/kubernetes/role/pki-issuer \ bound_service_account_names=pki-issuer \ bound_service_account_namespaces=<AUTH_SERVICE_ACCOUNT_NAMESPACE> \ token_policies=pki-issuer \ audience=vault \ token_ttl=1hSet
<AUTH_SERVICE_ACCOUNT_NAMESPACE>according to the replacement issuer:Issuer Service account namespace VaultIssuerThe issuer's namespace, for example app.VaultClusterIssuerThe VaultAuthnamespace;vault-secrets-operatorfor the Helm-createddefaultauth.If you reuse an auth role, add the policy without replacing its existing policies. All consumers of that role gain signing access; prefer a dedicated role and
VaultAuth.
Step 4: Set up the Vault Secrets Operator
Choose the path for an existing or new operator installation.
Update the chart repository and export your current release values:
$ helm repo update hashicorp $ helm get values vault-secrets-operator \ --namespace vault-secrets-operator --output yaml > values.yamlCheck CRD upgrades. CRDs update automatically when enabling
hooks.upgradeCRDs.enabled=trueand Helm hooks. Otherwise, apply the target chart's CRDs before upgrading:$ helm show crds hashicorp/vault-secrets-operator --version <VSO_VERSION> \ > vso-crds.yaml $ kubectl apply --filename vso-crds.yamlPreview the upgrade with your current values and approval permission:
$ helm upgrade vault-secrets-operator hashicorp/vault-secrets-operator \ --version <VSO_VERSION> \ --namespace vault-secrets-operator \ --values values.yaml \ --set certManager.approverRBAC.enabled=true \ --dry-runReview the rendered changes. Then run the same command without
--dry-runto upgrade.Pass
--valuesto preserve your settings while receiving the target's chart defaults; avoid--reuse-values, which retains the previous releases defaults.Reuse your
VaultConnectionand create the service account and dedicatedVaultAuthfor the role from Step 3. Refer to Create the connection and auth resources.
Confirm the issuer CRDs exist and your connection and auth resources are ready:
$ kubectl get crd vaultissuers.secrets.hashicorp.com \
vaultclusterissuers.secrets.hashicorp.com
$ kubectl get vaultconnection,vaultauth --all-namespaces
The approval setting lets cert-manager approve every request for these issuers.
For policy-based approval, leave it disabled and configure
approver-policy
instead. If cert-manager uses a non-default controller service account, set
certManager.approverRBAC.serviceAccountName and
certManager.approverRBAC.serviceAccountNamespace.
Step 5: Create the issuer
Map the signing path and authentication reference:
| Original setting | Replacement issuer setting |
|---|---|
pki/sign/example-dot-com | mount: pki, role: example-dot-com |
pki/issuer/example-issuer/sign/example-dot-com | Also set issuerRef: example-issuer. |
spec.vault.namespace | spec.namespace; omit to inherit from VaultAuth. |
Dedicated VaultAuth | Set vaultAuthRef to name or namespace/name; omit for the operator namespace's default auth. |
When you set issuerRef, the Vault Secrets Operator signs certificates with the
<mount>/issuer/<issuerRef>/sign/<role> path, for example
pki/issuer/example-issuer/sign/example-dot-com. Make sure the policy from
Step 3 grants that path. Otherwise, Vault
returns a 403 error and the certificate request fails.
Save the matching resource as vso-issuer.yaml. These examples use the
Helm-created default auth; set vaultAuthRef if you created a dedicated auth.
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultIssuer
metadata:
name: vso-issuer
namespace: app
spec:
mount: pki
role: example-dot-com
The operator namespace's default auth allows all namespaces. For a dedicated
auth, configure allowedNamespaces for the namespaces requesting certificates.
Refer to namespace access.
Apply the resource and confirm that the matching issuer's READY column is
True:
$ kubectl apply --filename vso-issuer.yaml
$ kubectl get vaultissuer --namespace app
$ kubectl get vaultclusterissuer
Before migrating production, issue a test Certificate in the same namespace
with the intended subject, SANs, key, and lifetime settings and the replacement
issuerRef. Use a unique certificate name and Secret name, such as
web-migration-test and web-migration-test-tls. Verify it with Step 7, then
delete those test resources. Issuer readiness alone does not prove signing
works.
Step 6: Update one certificate
Start with a low-risk certificate. If you omit duration, add
"duration":"2160h" alongside "issuerRef" in the patch to preserve the
built-in issuer's requested lifetime, or choose another approved duration.
Check the role and CA limits and ensure its renewal settings fit that lifetime.
Do not change a shared PKI role's ttl only for this migration.
$ kubectl patch certificate web --namespace app --type merge \
--patch '{"spec":{"issuerRef":{"group":"secrets.hashicorp.com","kind":"VaultIssuer","name":"vso-issuer"}}}'
cert-manager requests a replacement certificate. The Secret retains the existing certificate until cert-manager writes the replacement.
Step 7: Verify the certificate
Confirm that the new request is approved and ready, and that the
Certificateis ready. Inspect the request'sspec.issuerRefto ensure it names the replacement issuer insecrets.hashicorp.com, not the old issuer:$ kubectl get certificaterequest,certificate --namespace app $ kubectl get certificaterequest <CERTIFICATE_REQUEST_NAME> \ --namespace app --output yamlInspect the certificate stored in the Secret. Check the SANs and intended expiration, accounting for Vault's backdating and CA expiration settings:
$ kubectl get secret web-tls --namespace app \ --output jsonpath='{.data.tls\.crt}' \ | base64 --decode \ | openssl x509 -noout -subject -issuer -dates -ext subjectAltNameConfirm the request has a
CertificateIssuedevent with the messageCertificate issued successfully:$ kubectl get events --namespace app \ --field-selector involvedObject.kind=CertificateRequest,involvedObject.name=<CERTIFICATE_REQUEST_NAME>
Repeat Step 6 and Step 7 for each certificate. Applications must reload the updated Secret to use the replacement certificate.
To roll back either issuer type, apply the patch saved for that certificate:
$ kubectl patch certificate web --namespace app --type merge \
--patch-file web-rollback.json
The patch restores the original issuer and lifetime settings and triggers reissuance; it does not restore the previous Secret contents. Verify issuance by the original issuer before considering rollback complete.
Step 8: Remove the cert-manager Vault issuer
After all migrated certificates complete at least one automatic renewal:
Delete the original issuer:
$ kubectl delete issuer vault-issuer --namespace appRevoke credentials and remove credential Secrets used only by that issuer. Do not remove shared authentication resources.
After cleanup, rollback requires recreating the issuer from
issuer-inventory.yaml and restoring or replacing its credentials.