NEW: Get project updates onTwitterandMastodon

Venafi

Introduction

The Venafi Issuer types allows you to obtain certificates from Venafi as a Service (VaaS) and Venafi Trust Protection Platform (TPP) instances.

You can have multiple different Venafi Issuer types installed within the same cluster, including mixtures of Venafi as a Service and TPP issuer types. This allows you to be flexible with the types of Venafi account you use.

Automated certificate renewal and management are provided for Certificates using the Venafi Issuer.

A single Venafi Issuer represents a single Venafi 'zone' so you must create one Issuer resource for each zone you want to use. A zone is a single entity that combines the policy that governs certificate issuance with information about how certificates are organized in Venafi to identify the business application and establish ownership.

You can configure your Issuer resource to either issue certificates only within a single namespace, or cluster-wide (using a ClusterIssuer resource). For more information on the distinction between Issuer and ClusterIssuer resources, read the Namespaces section.

Creating a Venafi as a Service Issuer

If you haven't already done so, create your Venafi as a Service account on this page and copy the API key from your user preferences. Then you may want to create a custom CA Account and Issuing Template or choose instead to use defaults that are automatically created for testing ("Built-in CA" and "Default", respectively). Lastly you'll need to create an Application for establishing ownership of all the certificates requested by your cert-manager Issuer, and assign to it the Issuing Template.

Make a note of the Application name and API alias of the Issuing Template because together they comprise the 'zone' you will need for your Issuer configuration.

In order to set up a Venafi as a Service Issuer, you must first create a Kubernetes Secret resource containing your Venafi as a Service API credentials:

$ kubectl create secret generic \
       vaas-secret \
       --namespace='NAMESPACE OF YOUR ISSUER RESOURCE' \
       --from-literal=apikey='YOUR_VAAS_API_KEY_HERE'

Note: If you are configuring your issuer as a ClusterIssuer resource in order to serve Certificates across your whole cluster, you must set the --namespace parameter to cert-manager, which is the default Cluster Resource Namespace. The Cluster Resource Namespace can be configured through the --cluster-resource-namespace flag on the cert-manager controller component.

This API key will be used by cert-manager to interact with Venafi as a Service on your behalf.

Once the API key Secret has been created, you can create your Issuer or ClusterIssuer resource. If you are creating a ClusterIssuer resource, you must change the kind field to ClusterIssuer and remove the metadata.namespace field.

Save the below content after making your amendments to a file named vaas-issuer.yaml.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vaas-issuer
  namespace: <NAMESPACE YOU WANT TO ISSUE CERTIFICATES IN>
spec:
  venafi:
    zone: "My Application\My CIT" # Set this to <Application Name>\<Issuing Template Alias>
    cloud:
      apiTokenSecretRef:
        name: vaas-secret
        key: apikey

You can then create the Issuer using kubectl create.

$ kubectl create -f vaas-issuer.yaml

Verify the Issuer has been initialized correctly using kubectl describe.

$ kubectl get issuer vaas-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOURCE' -o wide
NAME           READY   STATUS                 AGE
vaas-issuer    True    Venafi issuer started  2m

You are now ready to issue certificates using the newly provisioned Venafi Issuer and Venafi as a Service.

Read the Requesting Certificates document for more information on how to create Certificate resources.

Creating a Venafi Trust Protection Platform Issuer

The Venafi Trust Protection Platform integration allows you to obtain certificates from a properly configured Venafi TPP instance.

The setup is similar to the Venafi as a Service configuration above, however some of the connection parameters are slightly different.

Note: You must allow "User Provided CSRs" as part of your TPP policy, as this is the only type supported by cert-manager at this time.

More specifically, the valid configurations of the "CSR handling" are:

  • "User Provided CSRs" selected and unlocked,
  • "User Provided CSRs" selected and locked,
  • "Service Generated CSRs" selected and unlocked.

When using "Service Generated CSRs" selected and unlocked, the default CSR configuration present in your policy folder will override the configuration of your Certificate resource. The subject DN, key algorithm, and key size will be overridden by the values set in the policy folder.

With "Service Generated CSRs" selected and locked, the certificate issuance will systematically fail with the following message:

400 PKCS#10 data will not be processed. Policy "\VED\Policy\foo" is locked to a Server Generated CSR.

In order to set up a Venafi Trust Protection Platform Issuer, you must first create a Kubernetes Secret resource containing your Venafi TPP API credentials.

Access Token Authentication

  1. Set up token authentication.

    NOTE: Do not select "Refresh Token Enabled" and set a long "Token Validity (days)". The Refresh Token feature is not supported by cert-manager's Venafi Issuer.

  2. Create a new user with sufficient privileges to manage and revoke certificates in a particular policy folder (zone).

    E.g. k8s-xyz-automation

  3. Create a new application integration

    Create an application integration with name and ID cert-manager.io. Set the "Base Access Settings" to certificate: manage.

    "Edit Access" to the new application integration, and allow it to be used by the user you created earlier.

  4. Generate an access token

    vcert getcred \
      --username k8s-xyz-automation \
      --password somepassword \
      -u https://tpp.example.com/vedsdk \
      --client-id cert-manager.io \
      --scope "certificate:manage,revoke"

    This will print an access-token to stdout. E.g.

    vCert: 2020/10/07 16:34:27 Getting credentials
    access_token:  I69n.............y1VjNJT3o9U0Wko19g==
    access_token_expires:  2021-01-05T15:34:30Z

  5. Save the access-token to a Secret in the Kubernetes cluster

    $ kubectl create secret generic \
          tpp-secret \
          --namespace=<NAMESPACE OF YOUR ISSUER RESOURCE> \
          --from-literal=access-token='YOUR_TPP_ACCESS_TOKEN'

Username / Password Authentication

Note: when using username / password authentication, cert-manager will manage the generation of access token for you . cert-manager does not use refresh tokens to renew access token.

  1. Create a new user with sufficient privileges to manage certificates in a particular policy folder (zone).

    E.g. k8s-xyz-automation

  2. Create a new application integration

    Create an application integration with name and ID cert-manager.io. Set the "Base Access Settings" to certificate: manage.

    "Edit Access" to the new application integration, and allow it to be used by the user you created earlier.

  3. Save the credentials to a Secret in the Kubernetes cluster

    $ kubectl create secret generic \
          tpp-secret \
          --namespace=<NAMESPACE OF YOUR ISSUER RESOURCE> \
          --from-literal=username='YOUR_TPP_USERNAME_HERE' \
          --from-literal=password='YOUR_TPP_PASSWORD_HERE'

Note: By default cert-manager uses cert-manager.io as client ID when authenticating to Venafi. You can customize this by adding client-id key to the secret:

$ kubectl create secret generic \
      tpp-secret \
      --namespace=<NAMESPACE OF YOUR ISSUER RESOURCE> \
      --from-literal=username='YOUR_TPP_USERNAME_HERE' \
      --from-literal=password='YOUR_TPP_PASSWORD_HERE' \
      --from-literal=client-id='YOUR_TPP_CLIENT-ID_HERE'

These credentials will be used by cert-manager to interact with your Venafi TPP instance. Username attribute must adhere to the <identity provider>:<username> format. For example: local:admin.

Once the Secret containing credentials has been created, you can create your Issuer or ClusterIssuer resource. If you are creating a ClusterIssuer resource, you must change the kind field to ClusterIssuer and remove the metadata.namespace field.

ℹ️ If you are using a ClusterIssuer resource, the Secret containing the credentials must be in the Cluster Resource Namespace, which is cert-manager by default. The Cluster Resource Namespace can be configured through the --cluster-resource-namespace flag on the cert-manager controller component.

📖 Read Issuer Configuration to learn more about the concept of a ClusterIssuer and the Cluster Resource Namespace

Save the below content after making your amendments to a file named tpp-issuer.yaml.

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: tpp-issuer
  namespace: <NAMESPACE YOU WANT TO ISSUE CERTIFICATES IN>
spec:
  venafi:
    zone: \VED\Policy\devops\cert-manager # Set this to the Venafi policy folder you want to use
    tpp:
      url: https://tpp.venafi.example/vedsdk # Change this to the URL of your TPP instance
      caBundle: <base64 encoded string of caBundle PEM file, or empty to use system root CAs>
      ## Use only caBundle above or the caBundleSecretRef below. Secret can be created from a ca.crt file by running below command
      ## kubectl create secret generic custom-tpp-ca --from-file=/my/certs/ca.crt -n <cert-manager-namespace>
      # caBundleSecretRef:
      #  name: custom-tpp-ca
      #  key: ca.crt
      credentialsRef:
        name: tpp-secret

You can then create the Issuer using kubectl create -f.

$ kubectl create -f tpp-issuer.yaml

Verify the Issuer has been initialized correctly using kubectl describe.

$ kubectl describe issuer tpp-issuer --namespace='NAMESPACE OF YOUR ISSUER RESOURCE'

You are now ready to issue certificates using the newly provisioned Venafi Issuer and Trust Protection Platform.

Read the Requesting Certificates document for more information on how to create Certificate resources.

Issuer specific annotations

Custom Fields

Starting v0.14 you can pass custom fields to Venafi (TPP version v19.2 and higher) using the venafi.cert-manager.io/custom-fields annotation on Certificate resources. The value is a JSON encoded array of custom field objects having a name and value key. For example:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-certificate
  annotations:
    venafi.cert-manager.io/custom-fields: |-
      [
        {"name": "field-name", "value": "field value"},
        {"name": "field-name-2", "value": "field value 2"}
      ]
...