OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Configuring an ACME issuer

The cert-manager Operator for Red Hat OpenShift supports using Automated Certificate Management Environment (ACME) CA servers, such as Let’s Encrypt, to issue certificates. Explicit credentials are configured by specifying the secret details in the Issuer API object. Ambient credentials are extracted from the environment, metadata services, or local files which are not explicitly configured in the Issuer API object.

The Issuer object is namespace scoped. It can only issue certificates from the same namespace. You can also use the ClusterIssuer object to issue certificates across all namespaces in the cluster.

Example YAML file that defines the ClusterIssuer object
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: acme-cluster-issuer
spec:
  acme:
    ...

By default, you can use the ClusterIssuer object with ambient credentials. To use the Issuer object with ambient credentials, you must enable the --issuer-ambient-credentials setting for the cert-manager controller.

About ACME issuers

The ACME issuer type for the cert-manager Operator for Red Hat OpenShift represents an Automated Certificate Management Environment (ACME) certificate authority (CA) server. ACME CA servers rely on a challenge to verify that a client owns the domain names that the certificate is being requested for. If the challenge is successful, the cert-manager Operator for Red Hat OpenShift can issue the certificate. If the challenge fails, the cert-manager Operator for Red Hat OpenShift does not issue the certificate.

Private DNS zones are not supported with Let’s Encrypt and internet ACME servers.

Supported ACME challenges types

The cert-manager Operator for Red Hat OpenShift supports the following challenge types for ACME issuers:

HTTP-01

With the HTTP-01 challenge type, you provide a computed key at an HTTP URL endpoint in your domain. If the ACME CA server can get the key from the URL, it can validate you as the owner of the domain.

For more information, see HTTP01 in the upstream cert-manager documentation.

HTTP-01 requires that the Let’s Encrypt servers can access the route of the cluster. If an internal or private cluster is behind a proxy, the HTTP-01 validations for certificate issuance fail.

The HTTP-01 challenge is restricted to port 80. For more information, see HTTP-01 challenge (Let’s Encrypt).
DNS-01

With the DNS-01 challenge type, you provide a computed key at a DNS TXT record. If the ACME CA server can get the key by DNS lookup, it can validate you as the owner of the domain.

For more information, see DNS01 in the upstream cert-manager documentation.

Supported DNS-01 providers

The cert-manager Operator for Red Hat OpenShift supports the following DNS-01 providers for ACME issuers:

  • Amazon Route 53

  • Azure DNS

    The cert-manager Operator for Red Hat OpenShift does not support using Azure Active Directory (Azure AD) pod identities to assign a managed identity to a pod.

  • Google Cloud DNS

  • Webhook

    Red Hat tests and supports DNS providers using an external webhook with cert-manager on OpenShift Container Platform. The following DNS providers are tested and supported with OpenShift Container Platform:

    Using a DNS provider that is not listed might work with OpenShift Container Platform, but the provider was not tested by Red Hat and therefore is not supported by Red Hat.

Configuring an ACME issuer to solve HTTP-01 challenges

You can use cert-manager Operator for Red Hat OpenShift to set up an ACME issuer to solve HTTP-01 challenges. This procedure uses Let’s Encrypt as the ACME CA server.

Prerequisites

  • You have access to the cluster as a user with the cluster-admin role.

  • You have a service that you want to expose. In this procedure, the service is named sample-workload.

Procedure

  1. Create an ACME cluster issuer.

    1. Create a YAML file that defines the ClusterIssuer object:

      Example acme-cluster-issuer.yaml file
      apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging                                        (1)
spec:
  acme:
    preferredChain: ""
    privateKeySecretRef:
      name: <secret_for_private_key>                               (2)
    server: https://acme-staging-v02.api.letsencrypt.org/directory (3)
    solvers:
    - http01:
        ingress:
          ingressClassName: openshift-default                                 (4)
      1 Provide a name for the cluster issuer.
      2 Replace <secret_private_key> with the name of secret to store the ACME account private key in.
      3 Specify the URL to access the ACME server’s directory endpoint. This example uses the Let’s Encrypt staging environment.
      4 Specify the Ingress class.

    2. Optional: If you create the object without specifying ingressClassName, use the following command to patch the existing ingress:

      $ oc patch ingress/<ingress-name> --type=merge --patch '{"spec":{"ingressClassName":"openshift-default"}}' -n <namespace>

    3. Create the ClusterIssuer object by running the following command:

      $ oc create -f acme-cluster-issuer.yaml

  2. Create an Ingress to expose the service of the user workload.

    1. Create a YAML file that defines a Namespace object:

      Example namespace.yaml file
      apiVersion: v1
kind: Namespace
metadata:
  name: my-ingress-namespace (1)
      1 Specify the namespace for the Ingress.

    2. Create the Namespace object by running the following command:

      $ oc create -f namespace.yaml

    3. Create a YAML file that defines the Ingress object:

      Example ingress.yaml file
      apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: sample-ingress                                           (1)
  namespace: my-ingress-namespace                                (2)
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-staging          (3)
    acme.cert-manager.io/http01-ingress-class: openshift-default (4)
spec:
  ingressClassName: openshift-default                            (5)
  tls:
  - hosts:
    - <hostname>                                                 (6)
    secretName: sample-tls                                       (7)
  rules:
  - host: <hostname>                                             (8)
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: sample-workload                                (9)
            port:
              number: 80
      1 Specify the name of the Ingress.
      2 Specify the namespace that you created for the Ingress.
      3 Specify the cluster issuer that you created.
      4 Specify the Ingress class.
      5 Specify the Ingress class.
      6 Replace <hostname> with the Subject Alternative Name to be associated with the certificate. This name is used to add DNS names to the certificate.
      7 Specify the secret to store the created certificate in.
      8 Replace <hostname> with the hostname. You can use the <host_name>.<cluster_ingress_domain> syntax to take advantage of the *.<cluster_ingress_domain> wildcard DNS record and serving certificate for the cluster. For example, you might use apps.<cluster_base_domain>. Otherwise, you must ensure that a DNS record exists for the chosen hostname.
      9 Specify the name of the service to expose. This example uses a service named sample-workload.

    4. Create the Ingress object by running the following command:

      $ oc create -f ingress.yaml

Configuring an ACME issuer by using explicit credentials for AWS Route53

You can use cert-manager Operator for Red Hat OpenShift to set up an Automated Certificate Management Environment (ACME) issuer to solve DNS-01 challenges by using explicit credentials on AWS. This procedure uses Let’s Encrypt as the ACME certificate authority (CA) server and shows how to solve DNS-01 challenges with Amazon Route 53.

Prerequisites

  • You must provide the explicit accessKeyID and secretAccessKey credentials. For more information, see Route53 in the upstream cert-manager documentation.

    You can use Amazon Route 53 with explicit credentials in an OpenShift Container Platform cluster that is not running on AWS.
Procedure

  1. Optional: Override the nameserver settings for the DNS-01 self check.

    This step is required only when the target public-hosted zone overlaps with the cluster’s default private-hosted zone.

    1. Edit the CertManager resource by running the following command:

      $ oc edit certmanager cluster

    2. Add a spec.controllerConfig section with the following override arguments:

      apiVersion: operator.openshift.io/v1alpha1
kind: CertManager
metadata:
  name: cluster
  ...
spec:
  ...
  controllerConfig:                                (1)
    overrideArgs:
      - '--dns01-recursive-nameservers-only'       (2)
      - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 Add the spec.controllerConfig section.
      2 Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain.
      3 Provide a comma-separated list of <host>:<port> nameservers to query for the DNS-01 self check. You must use a 1.1.1.1:53 value to avoid the public and private zones overlapping.

    3. Save the file to apply the changes.

  2. Optional: Create a namespace for the issuer:

    $ oc new-project <issuer_namespace>

  3. Create a secret to store your AWS credentials in by running the following command:

    $ oc create secret generic aws-secret --from-literal=awsSecretAccessKey=<aws_secret_access_key> \ (1)
    -n my-issuer-namespace
    1 Replace <aws_secret_access_key> with your AWS secret access key.

  4. Create an issuer:

    1. Create a YAML file that defines the Issuer object:

      Example issuer.yaml file
      apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: <letsencrypt_staging>                                        (1)
  namespace: <issuer_namespace>                                   (2)
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory (3)
    email: "<email_address>"                                       (4)
    privateKeySecretRef:
      name: <secret_private_key>                                   (5)
    solvers:
    - dns01:
        route53:
          accessKeyID: <aws_key_id>                                (6)
          hostedZoneID: <hosted_zone_id>                           (7)
          region: <region_name>                                    (8)
          secretAccessKeySecretRef:
            name: "aws-secret"                                     (9)
            key: "awsSecretAccessKey"                              (10)
      1 Provide a name for the issuer.
      2 Specify the namespace that you created for the issuer.
      3 Specify the URL to access the ACME server’s directory endpoint. This example uses the Let’s Encrypt staging environment.
      4 Replace <email_address> with your email address.
      5 Replace <secret_private_key> with the name of the secret to store the ACME account private key in.
      6 Replace <aws_key_id> with your AWS key ID.
      7 Replace <hosted_zone_id> with your hosted zone ID.
      8 Replace <region_name> with the AWS region name. For example, us-east-1.
      9 Specify the name of the secret you created.
      10 Specify the key in the secret you created that stores your AWS secret access key.

    2. Create the Issuer object by running the following command:

      $ oc create -f issuer.yaml

Configuring an ACME issuer by using ambient credentials on AWS

You can use cert-manager Operator for Red Hat OpenShift to set up an ACME issuer to solve DNS-01 challenges by using ambient credentials on AWS. This procedure uses Let’s Encrypt as the ACME CA server and shows how to solve DNS-01 challenges with Amazon Route 53.

Prerequisites

  • If your cluster is configured to use the AWS Security Token Service (STS), you followed the instructions from the Configuring cloud credentials for the cert-manager Operator for Red Hat OpenShift for the AWS Security Token Service cluster section.

  • If your cluster does not use the AWS STS, you followed the instructions from the Configuring cloud credentials for the cert-manager Operator for Red Hat OpenShift on AWS section.

Procedure

  1. Optional: Override the nameserver settings for the DNS-01 self check.

    This step is required only when the target public-hosted zone overlaps with the cluster’s default private-hosted zone.

    1. Edit the CertManager resource by running the following command:

      $ oc edit certmanager cluster

    2. Add a spec.controllerConfig section with the following override arguments:

      apiVersion: operator.openshift.io/v1alpha1
kind: CertManager
metadata:
  name: cluster
  ...
spec:
  ...
  controllerConfig:                                (1)
    overrideArgs:
      - '--dns01-recursive-nameservers-only'       (2)
      - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 Add the spec.controllerConfig section.
      2 Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain.
      3 Provide a comma-separated list of <host>:<port> nameservers to query for the DNS-01 self check. You must use a 1.1.1.1:53 value to avoid the public and private zones overlapping.

    3. Save the file to apply the changes.

  2. Optional: Create a namespace for the issuer:

    $ oc new-project <issuer_namespace>

  3. Modify the CertManager resource to add the --issuer-ambient-credentials argument:

    $ oc patch certmanager/cluster \
  --type=merge \
  -p='{"spec":{"controllerConfig":{"overrideArgs":["--issuer-ambient-credentials"]}}}'

  4. Create an issuer:

    1. Create a YAML file that defines the Issuer object:

      Example issuer.yaml file
      apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: <letsencrypt_staging>                                        (1)
  namespace: <issuer_namespace>                                   (2)
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory (3)
    email: "<email_address>"                                       (4)
    privateKeySecretRef:
      name: <secret_private_key>                                   (5)
    solvers:
    - dns01:
        route53:
          hostedZoneID: <hosted_zone_id>                           (6)
          region: us-east-1
      1 Provide a name for the issuer.
      2 Specify the namespace that you created for the issuer.
      3 Specify the URL to access the ACME server’s directory endpoint. This example uses the Let’s Encrypt staging environment.
      4 Replace <email_address> with your email address.
      5 Replace <secret_private_key> with the name of the secret to store the ACME account private key in.
      6 Replace <hosted_zone_id> with your hosted zone ID.

    2. Create the Issuer object by running the following command:

      $ oc create -f issuer.yaml

Configuring an ACME issuer by using explicit credentials for GCP Cloud DNS

You can use the cert-manager Operator for Red Hat OpenShift to set up an ACME issuer to solve DNS-01 challenges by using explicit credentials on GCP. This procedure uses Let’s Encrypt as the ACME CA server and shows how to solve DNS-01 challenges with Google CloudDNS.

Prerequisites

  • You have set up Google Cloud service account with a desired role for Google CloudDNS. For more information, see Google CloudDNS in the upstream cert-manager documentation.

    You can use Google CloudDNS with explicit credentials in an OpenShift Container Platform cluster that is not running on GCP.
Procedure

  1. Optional: Override the nameserver settings for the DNS-01 self check.

    This step is required only when the target public-hosted zone overlaps with the cluster’s default private-hosted zone.

    1. Edit the CertManager resource by running the following command:

      $ oc edit certmanager cluster

    2. Add a spec.controllerConfig section with the following override arguments:

      apiVersion: operator.openshift.io/v1alpha1
kind: CertManager
metadata:
  name: cluster
  ...
spec:
  ...
  controllerConfig:                                (1)
    overrideArgs:
      - '--dns01-recursive-nameservers-only'       (2)
      - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 Add the spec.controllerConfig section.
      2 Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain.
      3 Provide a comma-separated list of <host>:<port> nameservers to query for the DNS-01 self check. You must use a 1.1.1.1:53 value to avoid the public and private zones overlapping.

    3. Save the file to apply the changes.

  2. Optional: Create a namespace for the issuer:

    $ oc new-project my-issuer-namespace

  3. Create a secret to store your GCP credentials by running the following command:

    $ oc create secret generic clouddns-dns01-solver-svc-acct --from-file=service_account.json=<path/to/gcp_service_account.json> -n my-issuer-namespace

  4. Create an issuer:

    1. Create a YAML file that defines the Issuer object:

      Example issuer.yaml file
      apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: <acme_dns01_clouddns_issuer> (1)
  namespace: <issuer_namespace> (2)
spec:
  acme:
    preferredChain: ""
    privateKeySecretRef:
      name: <secret_private_key> (3)
    server: https://acme-staging-v02.api.letsencrypt.org/directory (4)
    solvers:
    - dns01:
        cloudDNS:
          project: <project_id> (5)
          serviceAccountSecretRef:
            name: clouddns-dns01-solver-svc-acct (6)
            key: service_account.json (7)
      1 Provide a name for the issuer.
      2 Replace <issuer_namespace> with your issuer namespace.
      3 Replace <secret_private_key> with the name of the secret to store the ACME account private key in.
      4 Specify the URL to access the ACME server’s directory endpoint. This example uses the Let’s Encrypt staging environment.
      5 Replace <project_id> with the name of the GCP project that contains the Cloud DNS zone.
      6 Specify the name of the secret you created.
      7 Specify the key in the secret you created that stores your GCP secret access key.

    2. Create the Issuer object by running the following command:

      $ oc create -f issuer.yaml

Configuring an ACME issuer by using ambient credentials on GCP

You can use the cert-manager Operator for Red Hat OpenShift to set up an ACME issuer to solve DNS-01 challenges by using ambient credentials on GCP. This procedure uses Let’s Encrypt as the ACME CA server and shows how to solve DNS-01 challenges with Google CloudDNS.

Prerequisites

  • If your cluster is configured to use GCP Workload Identity, you followed the instructions from the Configuring cloud credentials for the cert-manager Operator for Red Hat OpenShift with GCP Workload Identity section.

  • If your cluster does not use GCP Workload Identity, you followed the instructions from the Configuring cloud credentials for the cert-manager Operator for Red Hat OpenShift on GCP section.

Procedure

  1. Optional: Override the nameserver settings for the DNS-01 self check.

    This step is required only when the target public-hosted zone overlaps with the cluster’s default private-hosted zone.

    1. Edit the CertManager resource by running the following command:

      $ oc edit certmanager cluster

    2. Add a spec.controllerConfig section with the following override arguments:

      apiVersion: operator.openshift.io/v1alpha1
kind: CertManager
metadata:
  name: cluster
  ...
spec:
  ...
  controllerConfig:                                (1)
    overrideArgs:
      - '--dns01-recursive-nameservers-only'       (2)
      - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 Add the spec.controllerConfig section.
      2 Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain.
      3 Provide a comma-separated list of <host>:<port> nameservers to query for the DNS-01 self check. You must use a 1.1.1.1:53 value to avoid the public and private zones overlapping.

    3. Save the file to apply the changes.

  2. Optional: Create a namespace for the issuer:

    $ oc new-project <issuer_namespace>

  3. Modify the CertManager resource to add the --issuer-ambient-credentials argument:

    $ oc patch certmanager/cluster \
  --type=merge \
  -p='{"spec":{"controllerConfig":{"overrideArgs":["--issuer-ambient-credentials"]}}}'

  4. Create an issuer:

    1. Create a YAML file that defines the Issuer object:

      Example issuer.yaml file
      apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: <acme_dns01_clouddns_issuer> (1)
  namespace: <issuer_namespace>
spec:
  acme:
    preferredChain: ""
    privateKeySecretRef:
      name: <secret_private_key> (2)
    server: https://acme-staging-v02.api.letsencrypt.org/directory (3)
    solvers:
    - dns01:
        cloudDNS:
          project: <gcp_project_id> (4)
      1 Provide a name for the issuer.
      2 Replace <secret_private_key> with the name of the secret to store the ACME account private key in.
      3 Specify the URL to access the ACME server’s directory endpoint. This example uses the Let’s Encrypt staging environment.
      4 Replace <gcp_project_id> with the name of the GCP project that contains the Cloud DNS zone.

    2. Create the Issuer object by running the following command:

      $ oc create -f issuer.yaml

Configuring an ACME issuer by using explicit credentials for Microsoft Azure DNS

You can use cert-manager Operator for Red Hat OpenShift to set up an ACME issuer to solve DNS-01 challenges by using explicit credentials on Microsoft Azure. This procedure uses Let’s Encrypt as the ACME CA server and shows how to solve DNS-01 challenges with Azure DNS.

Prerequisites

  • You have set up a service principal with desired role for Azure DNS. For more information, see Azure DNS in the upstream cert-manager documentation.

    You can follow this procedure for an OpenShift Container Platform cluster that is not running on Microsoft Azure.
Procedure

  1. Optional: Override the nameserver settings for the DNS-01 self check.

    This step is required only when the target public-hosted zone overlaps with the cluster’s default private-hosted zone.

    1. Edit the CertManager resource by running the following command:

      $ oc edit certmanager cluster

    2. Add a spec.controllerConfig section with the following override arguments:

      apiVersion: operator.openshift.io/v1alpha1
kind: CertManager
metadata:
  name: cluster
  ...
spec:
  ...
  controllerConfig:                                (1)
    overrideArgs:
      - '--dns01-recursive-nameservers-only'       (2)
      - '--dns01-recursive-nameservers=1.1.1.1:53' (3)
      1 Add the spec.controllerConfig section.
      2 Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain.
      3 Provide a comma-separated list of <host>:<port> nameservers to query for the DNS-01 self check. You must use a 1.1.1.1:53 value to avoid the public and private zones overlapping.

    3. Save the file to apply the changes.

  2. Optional: Create a namespace for the issuer:

    $ oc new-project my-issuer-namespace

  3. Create a secret to store your Azure credentials in by running the following command:

    $ oc create secret generic <secret_name> --from-literal=<azure_secret_access_key_name>=<azure_secret_access_key_value> \   (1) (2) (3)
    -n my-issuer-namespace
    1 Replace <secret_name> with your secret name.
    2 Replace <azure_secret_access_key_name> with your Azure secret access key name.
    3 Replace <azure_secret_access_key_value> with your Azure secret key.

  4. Create an issuer:

    1. Create a YAML file that defines the Issuer object:

      Example issuer.yaml file
      apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: <acme-dns01-azuredns-issuer>   (1)
  namespace: <issuer_namespace>   (2)
spec:
  acme:
    preferredChain: ""
    privateKeySecretRef:
      name: <secret_private_key> (3)
    server: https://acme-staging-v02.api.letsencrypt.org/directory (4)
    solvers:
    - dns01:
        azureDNS:
          clientID: <azure_client_id> (5)
          clientSecretSecretRef:
            name: <secret_name> (6)
            key: <azure_secret_access_key_name> (7)
          subscriptionID: <azure_subscription_id> (8)
          tenantID: <azure_tenant_id> (9)
          resourceGroupName: <azure_dns_zone_resource_group> (10)
          hostedZoneName: <azure_dns_zone> (11)
          environment: AzurePublicCloud
      1 Provide a name for the issuer.
      2 Replace <issuer_namespace> with your issuer namespace.
      3 Replace <secret_private_key> with the name of the secret to store the ACME account private key in.
      4 Specify the URL to access the ACME server’s directory endpoint. This example uses the Let’s Encrypt staging environment.
      5 Replace <azure_client_id> with your Azure client ID.
      6 Replace <secret_name> with a name of the client secret.
      7 Replace <azure_secret_access_key_name> with the client secret key name.
      8 Replace <azure_subscription_id> with your Azure subscription ID.
      9 Replace <azure_tenant_id> with your Azure tenant ID.
      10 Replace <azure_dns_zone_resource_group> with the name of the Azure DNS zone resource group.
      11 Replace <azure_dns_zone> with the name of Azure DNS zone.

    2. Create the Issuer object by running the following command:

      $ oc create -f issuer.yaml

Additional resources