1. Documentation
    2. history bug_report picture_as_pdf
×

Managing certificates with an ACME issuer

The cert-manager Operator for Red Hat OpenShift supports using ACME CA servers, such as Let’s Encrypt, to issue certificates.

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.

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.

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

    The cert-manager Operator for Red Hat OpenShift does not support using Google workload identity federation.

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:
          class: 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. 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 to solve DNS-01 challenges

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

Private DNS zones are not supported.
Prerequisites

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

  • You have set up an IAM role for Amazon Route 53. For more information, see Route53 in the upstream cert-manager documentation.

    If your cluster is not configured to use the AWS Security Token Service (STS), you must provide explicit accessKeyID and secretAccessKey credentials. If you cluster uses AWS STS, you can use implicit ambient credentials.
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=1.1.1.1:53' (2)
      - '--dns01-recursive-nameservers-only'       (3)
      1 Add the spec.controllerConfig section.
      2 Provide a comma-separated list of <host>:<port> nameservers to query for the DNS-01 self check.
      3 Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain.

    3. Save the file to apply the changes.

  2. Optional: Create a namespace for the issuer.

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

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

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

      $ oc create -f namespace.yaml

  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: my-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: us-east-1
          secretAccessKeySecretRef:
            name: "aws-secret"                                     (8)
            key: "awsSecretAccessKey"                              (9)
      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 Specify the name of the secret you created.
      9 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

  5. Create a certificate.

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

      Example certificate.yaml file
      apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-tls-cert              (1)
  namespace: my-issuer-namespace (2)
spec:
  isCA: false
  commonName: '<common_name>'    (3)
  secretName: my-tls-cert        (4)
  dnsNames:
  - '<domain_name>'              (5)
  issuerRef:
    name: letsencrypt-staging    (6)
    kind: Issuer
      1 Provide a name for the certificate.
      2 Specify the namespace that you created for the issuer.
      3 Replace <common_name> with your common name (CN).
      4 Specify the name of the secret to create that will contain the certificate.
      5 Replace <domain_name> with your domain name.
      6 Specify the name of the issuer that you created.

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

      $ oc create -f certificate.yaml