Vault Installation

Installing Vault

Vault installation is a complex subject. For a thorough tour of the subject you can read the official HashiCorp Vault documentation.

Vault PKI Backend

The PKI Secrets Engine needs to be initialized for cert-manager to be able to generate certificate. The official Vault documentation can be found here.

Vault Authentication with a AppRole

This Vault authentication method uses a Vault AppRole.

The secret ID of the AppRole is stored in a secret.

Here an example of a secret containing the secretId of the AppRole:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: cert-manager-vault-approle
  namespace: default
data:
  secretId: "MDI..."

Where the secretId is the base 64 encoded value of the appRole secretId giving access to the pki backend in Vault.

We can now create a cluster issuer referencing this secret:

apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
  name: vault-issuer
  namespace: default
spec:
  vault:
    path: pki_int/sign/example-dot-com
    server: https://vault
    auth:
      appRole:
        path: approle
        roleId: "291b9d21-8ff5-..."
        secretRef:
          name: cert-manager-vault-approle
          key: secretId

Where path is the Vault role path of the PKI backend and server is the Vault server base URL. The path MUST USE the vault sign endpoint. The Vault appRole credentials are supplied as the Vault authentication method using the appRole created in Vault. The secretRef references the Kubernetes secret created previously. More specifically, the field name is the Kubernetes secret name and key is the name given as the key value that store the secretId. The optional attribute path specifies where the AppRole authentication is mounted in Vault. The attribute path default value is approle.

Once we have created the above Issuer we can use it to obtain a certificate.

apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
  name: example-com
  namespace: default
spec:
  secretName: example-com-tls
  issuerRef:
    name: vault-issuer
  commonName: example.com
  dnsNames:
  - www.example.com

The Certificate resource describes our desired certificate and the possible methods that can be used to obtain it. You can learn more about the Certificate resource in the reference docs. If the certificate is obtained successfully, the resulting key pair will be stored in a secret called example-com-tls in the same namespace as the Certificate.

The certificate will have a common name of example.com and the Subject Alternative Names (SANs) will be example.com and www.example.com.

In our Certificate we have referenced the vault-issuer Issuer above. The Issuer must be in the same namespace as the Certificate. If you want to reference a ClusterIssuer, which is a cluster-scoped version of an Issuer, you must add kind: ClusterIssuer to the issuerRef stanza.

For more information on ClusterIssuers, read the ClusterIssuer reference docs.

Vault Authentication with a Token

This Vault authentication method uses a plain token. A Vault token is generated by one of the many authentication backend supported by Vault. Tokens in Vault have expiration and need to be refreshed. You need to be aware that cert-manager do not refresh these tokens. Another process must be put in place to keep them from expiring.

For testing purpose a root token which do not expire is generated at Vault installation time. WARNING: a root token should only be used for testing purpose only.

Please refer to the official token documentation for all the details.

Here an example of a secret Kubernetes resource containing the Vault token:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: cert-manager-vault-token
  namespace: kube-system
data:
  token: "MjI..."

Where the token value is the base 64 encoded value of the token giving access to the PKI backend in Vault.

We can now create an issuer referencing this secret:

apiVersion: certmanager.k8s.io/v1alpha1
kind: Issuer
metadata:
  name: vault-issuer
  namespace: default
spec:
  vault:
    auth:
      tokenSecretRef:
        name: cert-manager-vault-token
        key: token
    path: pki_int/sign/example-dot-com
    server: https://vault

Where path is the Vault role path of the PKI backend and server is the Vault server base URL. The secret created previously is referenced in the issuer with its name and key corresponding to the name of the Kubernetes secret and the property name containing the token value respectively.

Once we have created the above Issuer we can use it to obtain a certificate.

apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
  name: example-com
  namespace: default
spec:
  secretName: example-com-tls
  issuerRef:
    name: vault-issuer
  commonName: example.com
  dnsNames:
  - www.example.com

The Certificate resource describes our desired certificate and the possible methods that can be used to obtain it. You can learn more about the Certificate resource in the reference docs. If the certificate is obtained successfully, the resulting key pair will be stored in a secret called example-com-tls in the same namespace as the Certificate.

The certificate will have a common name of example.com and the Subject Alternative Names (SANs) will be example.com and www.example.com.

In our Certificate we have referenced the vault-issuer Issuer above. The Issuer must be in the same namespace as the Certificate. If you want to reference a ClusterIssuer, which is a cluster-scoped version of an Issuer, you must add kind: ClusterIssuer to the issuerRef stanza.

For more information on ClusterIssuers, read the ClusterIssuer reference docs.