Chapter 9. cert-manager Operator for Red Hat OpenShift

9.1. cert-manager Operator for Red Hat OpenShift overview

The cert-manager Operator for Red Hat OpenShift is a cluster-wide service that provides application certificate lifecycle management. The cert-manager Operator for Red Hat OpenShift allows you to integrate with external certificate authorities and provides certificate provisioning, renewal, and retirement.

9.1.1. About the cert-manager Operator for Red Hat OpenShift

The cert-manager project introduces certificate authorities and certificates as resource types in the Kubernetes API, which makes it possible to provide certificates on demand to developers working within your cluster. The cert-manager Operator for Red Hat OpenShift provides a supported way to integrate cert-manager into your OpenShift Container Platform cluster.

The cert-manager Operator for Red Hat OpenShift provides the following features:

  • Support for integrating with external certificate authorities
  • Tools to manage certificates
  • Ability for developers to self-serve certificates
  • Automatic certificate renewal
Important

Do not attempt to use more than one cert-manager Operator in your cluster. If you have a community cert-manager Operator installed in your cluster, you must uninstall it before installing the cert-manager Operator for Red Hat OpenShift.

9.1.2. Supported issuer types

The cert-manager Operator for Red Hat OpenShift supports the following issuer types:

  • Automated Certificate Management Environment (ACME)
  • Certificate authority (CA)
  • Self-signed
  • Vault
  • Venafi

9.1.3. Certificate request methods

There are two ways to request a certificate using the cert-manager Operator for Red Hat OpenShift:

Using the cert-manager.io/CertificateRequest object
With this method a service developer creates a CertificateRequest object with a valid issuerRef pointing to a configured issuer (configured by a service infrastructure administrator). A service infrastructure administrator then accepts or denies the certificate request. Only accepted certificate requests create a corresponding certificate.
Using the cert-manager.io/Certificate object
With this method, a service developer creates a Certificate object with a valid issuerRef and obtains a certificate from a secret that they pointed to the Certificate object.

9.1.4. Additional resources

9.2. cert-manager Operator for Red Hat OpenShift release notes

The cert-manager Operator for Red Hat OpenShift is a cluster-wide service that provides application certificate lifecycle management.

These release notes track the development of cert-manager Operator for Red Hat OpenShift.

For more information, see About the cert-manager Operator for Red Hat OpenShift.

9.2.1. Release notes for cert-manager Operator for Red Hat OpenShift 1.13.0

Issued: 2024-01-16

The following advisory is available for the cert-manager Operator for Red Hat OpenShift 1.13.0:

Version 1.13.0 of the cert-manager Operator for Red Hat OpenShift is based on the upstream cert-manager version v1.13.3. For more information, see the cert-manager project release notes for v1.13.0.

9.2.1.1. New features and enhancements

  • You can now manage certificates for API Server and Ingress Controller by using the cert-manager Operator for Red Hat OpenShift. For more information, see Configuring certificates with an issuer.
  • With this release, the scope of the cert-manager Operator for Red Hat OpenShift, which was previously limited to the OpenShift Container Platform on AMD64 architecture, has now been expanded to include support for managing certificates on OpenShift Container Platform running on IBM Z (s390x), IBM Power (ppc64le), and ARM64 architectures.
  • With this release, you can use DNS over HTTPS (DoH) for performing the self-checks during the ACME DNS-01 challenge verification. The DNS self-check method can be controlled by using the command line flags, --dns01-recursive-nameservers-only and --dns01-recursive-nameservers. For more information, see Customizing cert-manager by overriding arguments from the cert-manager Operator API.

9.2.1.2. CVEs

9.2.2. Release notes for cert-manager Operator for Red Hat OpenShift 1.12.1

Issued: 2023-11-15

The following advisory is available for the cert-manager Operator for Red Hat OpenShift 1.12.1:

Version 1.12.1 of the cert-manager Operator for Red Hat OpenShift is based on the upstream cert-manager version v1.12.5. For more information, see the cert-manager project release notes for v1.12.5.

9.2.2.1. Bug fixes

  • Previously, in a multi-architecture environment, the cert-manager Operator pods were prone to failures because of the invalid node affinity configuration. With this fix, the cert-manager Operator pods run without any failures. (OCPBUGS-19446)

9.2.2.2. CVEs

9.2.3. Release notes for cert-manager Operator for Red Hat OpenShift 1.12.0

Issued: 2023-10-02

The following advisories are available for the cert-manager Operator for Red Hat OpenShift 1.12.0:

Version 1.12.0 of the cert-manager Operator for Red Hat OpenShift is based on the upstream cert-manager version v1.12.4. For more information, see the cert-manager project release notes for v1.12.4.

9.2.3.1. Bug fixes

  • Previously, you could not configure the CPU and memory requests and limits for the cert-manager components such as cert-manager controller, CA injector, and Webhook. Now, you can configure the CPU and memory requests and limits for the cert-manager components by using the command-line interface (CLI). For more information, see Overriding CPU and memory limits for the cert-manager components. (OCPBUGS-13830)
  • Previously, if you updated the ClusterIssuer object, the cert-manager Operator for Red Hat OpenShift could not verify and update the change in the cluster issuer. Now, if you modify the ClusterIssuer object, the cert-manager Operator for Red Hat OpenShift verifies the ACME account registration and updates the change. (OCPBUGS-8210)
  • Previously, the cert-manager Operator for Red Hat OpenShift did not support enabling the --enable-certificate-owner-ref flag. Now, the cert-manager Operator for Red Hat OpenShift supports enabling the --enable-certificate-owner-ref flag by adding the spec.controllerConfig.overrideArgs field in the cluster object. After enabling the --enable-certificate-owner-ref flag, cert-manager can automatically delete the secret when the Certificate resource is removed from the cluster. For more information on enabling the --enable-certificate-owner-ref flag and deleting the TLS secret automatically, see Deleting a TLS secret automatically upon Certificate removal (CM-98)
  • Previously, the cert-manager Operator for Red Hat OpenShift could not pull the jetstack-cert-manager-container-v1.12.4-1 image. The cert-manager controller, CA injector, and Webhook pods were stuck in the ImagePullBackOff state. Now, the cert-manager Operator for Red Hat OpenShift pulls the jetstack-cert-manager-container-v1.12.4-1 image to run the cert-manager controller, CA injector, and Webhook pods successfully. (OCPBUGS-19986)

9.2.4. Release notes for cert-manager Operator for Red Hat OpenShift 1.11.5

Issued: 2023-11-15

The following advisory is available for the cert-manager Operator for Red Hat OpenShift 1.11.5:

The golang version is updated to the version 1.20.10 to fix Common Vulnerabilities and Exposures (CVEs). Version 1.11.5 of the cert-manager Operator for Red Hat OpenShift is based on the upstream cert-manager version v1.11.5. For more information, see the cert-manager project release notes for v1.11.5.

9.2.4.1. Bug fixes

  • Previously, in a multi-architecture environment, the cert-manager Operator pods were prone to failures because of the invalid node affinity configuration. With this fix, the cert-manager Operator pods run without any failures. (OCPBUGS-19446)

9.2.4.2. CVEs

9.2.5. Release notes for cert-manager Operator for Red Hat OpenShift 1.11.4

Issued: 2023-07-26

The following advisory is available for the cert-manager Operator for Red Hat OpenShift 1.11.4:

The golang version is updated to the version 1.19.10 to fix Common Vulnerabilities and Exposures (CVEs). Version 1.11.4 of the cert-manager Operator for Red Hat OpenShift is based on the upstream cert-manager version v1.11.4. For more information, see the cert-manager project release notes for v1.11.4.

9.2.5.1. Bug fixes

  • Previously, the cert-manager Operator for Red Hat OpenShift did not allow you to install older versions of the cert-manager Operator for Red Hat OpenShift. Now, you can install older versions of the cert-manager Operator for Red Hat OpenShift using the web console or the command-line interface (CLI). For more information on how to use the web console to install older versions, see Installing the cert-manager Operator for Red Hat OpenShift. (OCPBUGS-16393)

9.2.6. Release notes for cert-manager Operator for Red Hat OpenShift 1.11.1

Issued: 2023-06-21

The following advisory is available for the cert-manager Operator for Red Hat OpenShift 1.11.1:

Version 1.11.1 of the cert-manager Operator for Red Hat OpenShift is based on the upstream cert-manager version v1.11.1. For more information, see the cert-manager project release notes for v1.11.1.

9.2.6.1. New features and enhancements

This is the general availability (GA) release of the cert-manager Operator for Red Hat OpenShift.

9.2.6.1.1. Setting log levels for cert-manager and the cert-manager Operator for Red Hat OpenShift
9.2.6.1.2. Authenticating the cert-manager Operator for Red Hat OpenShift with AWS
9.2.6.1.3. Authenticating the cert-manager Operator for Red Hat OpenShift with GCP

9.2.6.2. Bug fixes

  • Previously, the cm-acme-http-solver pod did not use the latest published Red Hat image registry.redhat.io/cert-manager/jetstack-cert-manager-acmesolver-rhel9. With this release, the cm-acme-http-solver pod uses the latest published Red Hat image registry.redhat.io/cert-manager/jetstack-cert-manager-acmesolver-rhel9. (OCPBUGS-10821)
  • Previously, the cert-manager Operator for Red Hat OpenShift did not support changing labels for cert-manager pods such as controller, CA injector, and Webhook pods. With this release, you can add labels to cert-manager pods. (OCPBUGS-8466)
  • Previously, you could not update the log verbosity level in the cert-manager Operator for Red Hat OpenShift. You can now update the log verbosity level by using an environmental variable OPERATOR_LOG_LEVEL in its subscription resource. (OCPBUGS-9994)
  • Previously, when uninstalling the cert-manager Operator for Red Hat OpenShift, if you select the Delete all operand instances for this operator checkbox in the OpenShift Container Platform web console, the Operator was not uninstalled properly. The cert-manager Operator for Red Hat OpenShift is now properly uninstalled. (OCPBUGS-9960)
  • Previously, the cert-manager Operator for Red Hat OpenShift did not support using Google workload identity federation. The cert-manager Operator for Red Hat OpenShift now supports using Google workload identity federation. (OCPBUGS-9998)

9.2.6.3. Known issues

  • After installing the cert-manager Operator for Red Hat OpenShift, if you navigate to Operators → Installed Operators and select Operator details in the OpenShift Container Platform web console, you cannot see the cert-manager resources that are created across all namespaces. As a workaround, you can navigate to Home → API Explorer to see the cert-manager resources. (OCPBUGS-11647)
  • After uninstalling the cert-manager Operator for Red Hat OpenShift by using the web console, the cert-manager Operator for Red Hat OpenShift does not remove the cert-manager controller, CA injector, and Webhook pods automatically from the cert-manager namespace. As a workaround, you can manually delete the cert-manager controller, CA injector, and Webhook pod deployments present in the cert-manager namespace. (OCPBUGS-13679)

9.2.7. Release notes for cert-manager Operator for Red Hat OpenShift 1.10.3

Issued: 2023-08-08

The following advisory is available for the cert-manager Operator for Red Hat OpenShift 1.10.3:

The version 1.10.3 of the cert-manager Operator for Red Hat OpenShift is based on the cert-manager upstream version v1.10.2. With this release, the version of the cert-manager Operator for Red Hat OpenShift is 1.10.3 but the cert-manager operand version is 1.10.2. For more information, see the cert-manager project release notes for v1.10.2.

9.2.7.1. CVEs

9.2.8. Release notes for cert-manager Operator for Red Hat OpenShift 1.10.2

Issued: 2023-03-23

The following advisory is available for the cert-manager Operator for Red Hat OpenShift 1.10.2:

Version 1.10.2 of the cert-manager Operator for Red Hat OpenShift is based on the upstream cert-manager version v1.10.2. For more information, see the cert-manager project release notes for v1.10.2.

Important

If you used the Technology Preview version of the cert-manager Operator for Red Hat OpenShift, you must uninstall it and remove all related resources for the Technology Preview version before installing this version of the cert-manager Operator for Red Hat OpenShift.

For more information, see Uninstalling the cert-manager Operator for Red Hat OpenShift.

9.2.8.1. New features and enhancements

This is the general availability (GA) release of the cert-manager Operator for Red Hat OpenShift.

  • The following issuer types are supported:

    • Automated Certificate Management Environment (ACME)
    • Certificate authority (CA)
    • Self-signed
  • The following ACME challenge types are supported:

    • DNS-01
    • HTTP-01
  • The following DNS-01 providers for ACME issuers are supported:

    • Amazon Route 53
    • Azure DNS
    • Google Cloud DNS
  • The cert-manager Operator for Red Hat OpenShift now supports injecting custom CA certificates and propagating cluster-wide egress proxy environment variables.
  • You can customize the cert-manager Operator for Red Hat OpenShift API fields by overriding environment variables and arguments. For more information, see Customizing cert-manager Operator API fields
  • You can enable monitoring and metrics collection for the cert-manager Operator for Red Hat OpenShift by using a service monitor to perform the custom metrics scraping. After you have enabled monitoring for the cert-manager Operator for Red Hat OpenShift, you can query its metrics by using the OpenShift Container Platform web console. For more information, see Enabling monitoring for the cert-manager Operator for Red Hat OpenShift

9.2.8.2. Bug fixes

  • Previously, the unsupportedConfigOverrides field replaced user-provided arguments instead of appending them. Now, the unsupportedConfigOverrides field properly appends user-provided arguments. (CM-23)

    Warning

    Using the unsupportedConfigOverrides section to modify the configuration of an Operator is unsupported and might block cluster upgrades.

  • Previously, the cert-manager Operator for Red Hat OpenShift was installed as a cluster Operator. With this release, the cert-manager Operator for Red Hat OpenShift is now properly installed as an OLM Operator. (CM-35)

9.2.8.3. Known issues

  • Using Route objects is not fully supported. Currently, to use cert-manager Operator for Red Hat OpenShift with Routes, users must create Ingress objects, which are translated to Route objects by the Ingress-to-Route Controller. (CM-16)
  • 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. As a workaround, you can use a service principal to assign a managed identity. (OCPBUGS-8665)
  • The cert-manager Operator for Red Hat OpenShift does not support using Google workload identity federation. (OCPBUGS-9998)
  • When uninstalling the cert-manager Operator for Red Hat OpenShift, if you select the Delete all operand instances for this operator checkbox in the OpenShift Container Platform web console, the Operator is not uninstalled properly. As a workaround, do not select this checkbox when uninstalling the cert-manager Operator for Red Hat OpenShift. (OCPBUGS-9960)

9.3. Installing the cert-manager Operator for Red Hat OpenShift

The cert-manager Operator for Red Hat OpenShift is not installed in OpenShift Container Platform by default. You can install the cert-manager Operator for Red Hat OpenShift by using the web console.

9.3.1. Installing the cert-manager Operator for Red Hat OpenShift using the web console

You can use the web console to install the cert-manager Operator for Red Hat OpenShift.

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • You have access to the OpenShift Container Platform web console.

Procedure

  1. Log in to the OpenShift Container Platform web console.
  2. Navigate to OperatorsOperatorHub.
  3. Enter cert-manager Operator for Red Hat OpenShift into the filter box.
  4. Select the cert-manager Operator for Red Hat OpenShift and click Install.

    Note

    From the cert-manager Operator for Red Hat OpenShift 1.12.0 and later, the z-stream versions of the upstream cert-manager operands such as cert-manager controller, CA injector, Webhook, and cert-manager Operator for Red Hat OpenShift are decoupled. For example, for the cert-manager Operator for Red Hat OpenShift 1.12.0, the cert-manager operand version is v1.12.4.

  5. On the Install Operator page:

    1. Update the Update channel, if necessary. The channel defaults to stable-v1, which installs the latest stable release of the cert-manager Operator for Red Hat OpenShift.
    2. Choose the Installed Namespace for the Operator. The default Operator namespace is cert-manager-operator.

      If the cert-manager-operator namespace does not exist, it is created for you.

    3. Select an Update approval strategy.

      • The Automatic strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available.
      • The Manual strategy requires a user with appropriate credentials to approve the Operator update.
    4. Click Install.

Verification

  1. Navigate to OperatorsInstalled Operators.
  2. Verify that cert-manager Operator for Red Hat OpenShift is listed with a Status of Succeeded in the cert-manager-operator namespace.
  3. Verify that cert-manager pods are up and running by entering the following command:

    $ oc get pods -n cert-manager

    Example output

    NAME                                       READY   STATUS    RESTARTS   AGE
    cert-manager-bd7fbb9fc-wvbbt               1/1     Running   0          3m39s
    cert-manager-cainjector-56cc5f9868-7g9z7   1/1     Running   0          4m5s
    cert-manager-webhook-d4f79d7f7-9dg9w       1/1     Running   0          4m9s

    You can use the cert-manager Operator for Red Hat OpenShift only after cert-manager pods are up and running.

9.3.2. Understanding update channels of the cert-manager Operator for Red Hat OpenShift

Update channels are the mechanism by which you can declare the version of your cert-manager Operator for Red Hat OpenShift in your cluster. The cert-manager Operator for Red Hat OpenShift offers the following update channels:

  • stable-v1
  • stable-v1.y

9.3.2.1. stable-v1 channel

The stable-v1 channel is the default and suggested channel while installing the cert-manager Operator for Red Hat OpenShift. The stable-v1 channel installs and updates the latest release version of the cert-manager Operator for Red Hat OpenShift. Select the stable-v1 channel if you want to use the latest stable release of the cert-manager Operator for Red Hat OpenShift.

The stable-v1 channel offers the following update approval strategies:

Automatic
If you choose automatic updates for an installed cert-manager Operator for Red Hat OpenShift, a new version of the cert-manager Operator for Red Hat OpenShift is available in the stable-v1 channel. The Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention.
Manual
If you select manual updates, when a newer version of the cert-manager Operator for Red Hat OpenShift is available, OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the cert-manager Operator for Red Hat OpenShift updated to the new version.

9.3.2.2. stable-v1.y channel

The y-stream version of the cert-manager Operator for Red Hat OpenShift installs updates from the stable-v1.y channels such as stable-v1.10, stable-v1.11, and stable-v1.12. Select the stable-v1.y channel if you want to use the y-stream version and stay updated to the z-stream version of the cert-manager Operator for Red Hat OpenShift.

The stable-v1.y channel offers the following update approval strategies:

Automatic
If you choose automatic updates for an installed cert-manager Operator for Red Hat OpenShift, a new z-stream version of the cert-manager Operator for Red Hat OpenShift is available in the stable-v1.y channel. OLM automatically upgrades the running instance of your Operator without human intervention.
Manual
If you select manual updates, when a newer version of the cert-manager Operator for Red Hat OpenShift is available, OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the cert-manager Operator for Red Hat OpenShift updated to the new version of the z-stream releases.

9.3.3. Additional resources

9.4. 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.

Note

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:
    ...

Note

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.

9.4.1. 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.

Note

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

9.4.1.1. 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.

9.4.1.2. 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

    Note

    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:

    Note

    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.

9.4.2. 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

9.4.3. 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.

    Note

    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

9.4.4. 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

9.4.5. 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.

    Note

    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

9.4.6. 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

9.4.7. 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.

    Note

    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

9.4.8. Additional resources

9.5. Configuring certificates with an issuer

By using the cert-manager Operator for Red Hat OpenShift, you can manage certificates, handling tasks such as renewal and issuance, for workloads within the cluster, as well as components interacting externally to the cluster.

9.5.1. Creating certificates for user workloads

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • You have installed the cert-manager Operator for Red Hat OpenShift.

Procedure

  1. Create an issuer. For more information, see "Configuring an issuer" in the "Additional Resources" section.
  2. Create a certificate:

    1. Create a YAML file, for example, certificate.yaml, that defines the Certificate object:

      Example certificate.yaml file

      apiVersion: cert-manager.io/v1
      kind: Certificate
      metadata:
        name: <tls_cert> 1
        namespace: <issuer_namespace> 2
      spec:
        isCA: false
        commonName: '<common_name>' 3
        secretName: <secret_name> 4
        dnsNames:
        - "<domain_name>" 5
        issuerRef:
          name: <issuer_name> 6
          kind: Issuer

      1
      Provide a name for the certificate.
      2
      Specify the namespace of the issuer.
      3
      Specify the common name (CN).
      4
      Specify the name of the secret to create that contains the certificate.
      5
      Specify the domain name.
      6
      Specify the name of the issuer.
    2. Create the Certificate object by running the following command:

      $ oc create -f certificate.yaml

Verification

  • Verify that the certificate is created and ready to use by running the following command:

    $ oc get certificate -w -n <issuer_namespace>

    Once certificate is in Ready status, workloads on your cluster can start using the generated certificate secret.

9.5.2. Creating certificates for the API server

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • You have installed the cert-manager Operator for Red Hat OpenShift 1.13.0 or later.

Procedure

  1. Create an issuer. For more information, see "Configuring an issuer" in the "Additional Resources" section.
  2. Create a certificate:

    1. Create a YAML file, for example, certificate.yaml, that defines the Certificate object:

      Example certificate.yaml file

      apiVersion: cert-manager.io/v1
      kind: Certificate
      metadata:
        name: <tls_cert> 1
        namespace: openshift-config
      spec:
        isCA: false
        commonName: "api.<cluster_base_domain>" 2
        secretName: <secret_name> 3
        dnsNames:
        - "api.<cluster_base_domain>" 4
        issuerRef:
          name: <issuer_name> 5
          kind: Issuer

      1
      Provide a name for the certificate.
      2
      Specify the common name (CN).
      3
      Specify the name of the secret to create that contains the certificate.
      4
      Specify the DNS name of the API server.
      5
      Specify the name of the issuer.
    2. Create the Certificate object by running the following command:

      $ oc create -f certificate.yaml
  3. Add the API server named certificate. For more information, see "Adding an API server named certificate" section in the "Additional resources" section.
Note

To ensure the certificates are updated, run the oc login command again after the certificate is created.

Verification

  • Verify that the certificate is created and ready to use by running the following command:

    $ oc get certificate -w -n openshift-config

    Once certificate is in Ready status, API server on your cluster can start using the generated certificate secret.

9.5.3. Creating certificates for the Ingress Controller

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • You have installed the cert-manager Operator for Red Hat OpenShift 1.13.0 or later.

Procedure

  1. Create an issuer. For more information, see "Configuring an issuer" in the "Additional Resources" section.
  2. Create a certificate:

    1. Create a YAML file, for example, certificate.yaml, that defines the Certificate object:

      Example certificate.yaml file

      apiVersion: cert-manager.io/v1
      kind: Certificate
      metadata:
        name: <tls_cert> 1
        namespace: openshift-ingress
      spec:
        isCA: false
        commonName: "apps.<cluster_base_domain>" 2
        secretName: <secret_name> 3
        dnsNames:
        - "apps.<cluster_base_domain>" 4
        - "*.apps.<cluster_base_domain>" 5
        issuerRef:
          name: <issuer_name> 6
          kind: Issuer

      1
      Provide a name for the certificate.
      2
      Specify the common name (CN).
      3
      Specify the name of the secret to create that contains the certificate.
      4 5
      Specify the DNS name of the ingress.
      6
      Specify the name of the issuer.
    2. Create the Certificate object by running the following command:

      $ oc create -f certificate.yaml
  3. Replace the default ingress certificate. For more information, see "Replacing the default ingress certificate" section in the "Additional resources" section.

Verification

  • Verify that the certificate is created and ready to use by running the following command:

    $ oc get certificate -w -n openshift-ingress

    Once certificate is in Ready status, Ingress Controller on your cluster can start using the generated certificate secret.

9.5.4. Additional resources

9.6. Enabling monitoring for the cert-manager Operator for Red Hat OpenShift

You can expose controller metrics for the cert-manager Operator for Red Hat OpenShift in the format provided by the Prometheus Operator.

9.6.1. Enabling monitoring by using a service monitor for the cert-manager Operator for Red Hat OpenShift

You can enable monitoring and metrics collection for the cert-manager Operator for Red Hat OpenShift by using a service monitor to perform the custom metrics scraping.

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • The cert-manager Operator for Red Hat OpenShift is installed.

Procedure

  1. Add the label to enable cluster monitoring by running the following command:

    $ oc label namespace cert-manager openshift.io/cluster-monitoring=true
  2. Create a service monitor:

    1. Create a YAML file that defines the Role, RoleBinding, and ServiceMonitor objects:

      Example monitoring.yaml file

      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        name: prometheus-k8s
        namespace: cert-manager
      rules:
      - apiGroups:
        - ""
        resources:
        - services
        - endpoints
        - pods
        verbs:
        - get
        - list
        - watch
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        name: prometheus-k8s
        namespace: cert-manager
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: prometheus-k8s
      subjects:
      - kind: ServiceAccount
        name: prometheus-k8s
        namespace: openshift-monitoring
      ---
      apiVersion: monitoring.coreos.com/v1
      kind: ServiceMonitor
      metadata:
        labels:
          app: cert-manager
          app.kubernetes.io/component: controller
          app.kubernetes.io/instance: cert-manager
          app.kubernetes.io/name: cert-manager
        name: cert-manager
        namespace: cert-manager
      spec:
        endpoints:
        - interval: 30s
          port: tcp-prometheus-servicemonitor
          scheme: http
        selector:
          matchLabels:
            app.kubernetes.io/component: controller
            app.kubernetes.io/instance: cert-manager
            app.kubernetes.io/name: cert-manager

    2. Create the Role, RoleBinding, and ServiceMonitor objects by running the following command:

      $ oc create -f monitoring.yaml

9.6.2. Querying metrics for the cert-manager Operator for Red Hat OpenShift

After you have enabled monitoring for the cert-manager Operator for Red Hat OpenShift, you can query its metrics by using the OpenShift Container Platform web console.

Prerequisites

  • You have access to the cluster as a user with the cluster-admin role.
  • You have installed the cert-manager Operator for Red Hat OpenShift.
  • You have enabled monitoring and metrics collection for the cert-manager Operator for Red Hat OpenShift.

Procedure

  1. From the OpenShift Container Platform web console, navigate to ObserveMetrics.
  2. Add a query by using one of the following formats:

    • Specify the endpoints:

      {instance="<endpoint>"} 1
      1
      Replace <endpoint> with the value of the endpoint for the cert-manager service. You can find the endpoint value by running the following command: oc describe service cert-manager -n cert-manager.
    • Specify the tcp-prometheus-servicemonitor port:

      {endpoint="tcp-prometheus-servicemonitor"}

9.7. Configuring the egress proxy for the cert-manager Operator for Red Hat OpenShift

If a cluster-wide egress proxy is configured in OpenShift Container Platform, Operator Lifecycle Manager (OLM) automatically configures Operators that it manages with the cluster-wide proxy. OLM automatically updates all of the Operator’s deployments with the HTTP_PROXY, HTTPS_PROXY, NO_PROXY environment variables.

You can inject any CA certificates that are required for proxying HTTPS connections into the cert-manager Operator for Red Hat OpenShift.

9.7.1. Injecting a custom CA certificate for the cert-manager Operator for Red Hat OpenShift

If your OpenShift Container Platform cluster has the cluster-wide proxy enabled, you can inject any CA certificates that are required for proxying HTTPS connections into the cert-manager Operator for Red Hat OpenShift.

Prerequisites

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

Procedure

  1. Create a config map in the cert-manager namespace by running the following command:

    $ oc create configmap trusted-ca -n cert-manager
  2. Inject the CA bundle that is trusted by OpenShift Container Platform into the config map by running the following command:

    $ oc label cm trusted-ca config.openshift.io/inject-trusted-cabundle=true -n cert-manager
  3. Update the deployment for the cert-manager Operator for Red Hat OpenShift to use the config map by running the following command:

    $ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator --type='merge' -p '{"spec":{"config":{"env":[{"name":"TRUSTED_CA_CONFIGMAP_NAME","value":"trusted-ca"}]}}}'

Verification

  1. Verify that the deployments have finished rolling out by running the following command:

    $ oc rollout status deployment/cert-manager-operator-controller-manager -n cert-manager-operator && \
    oc rollout status deployment/cert-manager -n cert-manager && \
    oc rollout status deployment/cert-manager-webhook -n cert-manager && \
    oc rollout status deployment/cert-manager-cainjector -n cert-manager

    Example output

    deployment "cert-manager-operator-controller-manager" successfully rolled out
    deployment "cert-manager" successfully rolled out
    deployment "cert-manager-webhook" successfully rolled out
    deployment "cert-manager-cainjector" successfully rolled out

  2. Verify that the CA bundle was mounted as a volume by running the following command:

    $ oc get deployment cert-manager -n cert-manager -o=jsonpath={.spec.template.spec.'containers[0].volumeMounts'}

    Example output

    [{"mountPath":"/etc/pki/tls/certs/cert-manager-tls-ca-bundle.crt","name":"trusted-ca","subPath":"ca-bundle.crt"}]

  3. Verify that the source of the CA bundle is the trusted-ca config map by running the following command:

    $ oc get deployment cert-manager -n cert-manager -o=jsonpath={.spec.template.spec.volumes}

    Example output

    [{"configMap":{"defaultMode":420,"name":"trusted-ca"},"name":"trusted-ca"}]

9.7.2. Additional resources

9.8. Customizing cert-manager Operator API fields

You can customize the cert-manager Operator for Red Hat OpenShift API fields by overriding environment variables and arguments.

Warning

To override unsupported arguments, you can add spec.unsupportedConfigOverrides section in the CertManager resource, but using spec.unsupportedConfigOverrides is unsupported.

9.8.1. Customizing cert-manager by overriding environment variables from the cert-manager Operator API

You can override the supported environment variables for the cert-manager Operator for Red Hat OpenShift by adding a spec.controllerConfig section in the CertManager resource.

Prerequisites

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

Procedure

  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:
        overrideEnv:
          - name: HTTP_PROXY
            value: http://<proxy_url> 1
          - name: HTTPS_PROXY
            value: https://<proxy_url> 2
          - name: NO_PROXY
            value: <ignore_proxy_domains> 3
    1 2
    Replace <proxy_url> with the proxy server URL.
    3
    Replace <ignore_proxy_domains> with a comma separated list of domains. These domains are ignored by the proxy server.
  3. Save your changes and quit the text editor to apply your changes.

Verification

  1. Verify that the cert-manager controller pod is redeployed by running the following command:

    $ oc get pods -l app.kubernetes.io/name=cert-manager -n cert-manager

    Example output

    NAME                          READY   STATUS    RESTARTS   AGE
    cert-manager-bd7fbb9fc-wvbbt  1/1     Running   0          39s

  2. Verify that environment variables are updated for the cert-manager pod by running the following command:

    $ oc get pod <redeployed_cert-manager_controller_pod> -n cert-manager -o yaml

    Example output

        env:
        ...
        - name: HTTP_PROXY
          value: http://<PROXY_URL>
        - name: HTTPS_PROXY
          value: https://<PROXY_URL>
        - name: NO_PROXY
          value: <IGNORE_PROXY_DOMAINS>

9.8.2. Customizing cert-manager by overriding arguments from the cert-manager Operator API

You can override the supported arguments for the cert-manager Operator for Red Hat OpenShift by adding a spec.controllerConfig section in the CertManager resource.

Prerequisites

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

Procedure

  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:
        overrideArgs:
          - '--dns01-recursive-nameservers=<host>:<port>' 1
          - '--dns01-recursive-nameservers-only' 2
          - '--acme-http01-solver-nameservers=<host>:<port>' 3
          - '--v=<verbosity_level>' 4
          - '--metrics-listen-address=<host>:<port>' 5
          - '--issuer-ambient-credentials' 6
      webhookConfig:
        overrideArgs:
          - '--v=4' 7
      cainjectorConfig:
        overrideArgs:
          - '--v=2' 8
    1
    Provide a comma-separated list of <host>:<port> nameservers to query for the DNS-01 self check. For example, --dns01-recursive-nameservers=1.1.1.1:53.
    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 Automated Certificate Management Environment (ACME) HTTP01 self check. For example, --acme-http01-solver-nameservers=1.1.1.1:53.
    4 7 8
    Specify to set the log level verbosity to determine the verbosity of log messages.
    5
    Specify the host and port for the metrics endpoint. The default value is --metrics-listen-address=0.0.0.0:9402.
    6
    You must use the --issuer-ambient-credentials argument when configuring an ACME Issuer to solve DNS-01 challenges by using ambient credentials.
  3. Save your changes and quit the text editor to apply your changes.

Verification

  • Verify that arguments are updated for cert-manager pods by running the following command:

    $ oc get pods -n cert-manager -o yaml

    Example output

    ...
      metadata:
        name: cert-manager-6d4b5d4c97-kldwl
        namespace: cert-manager
    ...
      spec:
        containers:
        - args:
          - --acme-http01-solver-nameservers=1.1.1.1:53
          - --cluster-resource-namespace=$(POD_NAMESPACE)
          - --dns01-recursive-nameservers=1.1.1.1:53
          - --dns01-recursive-nameservers-only
          - --leader-election-namespace=kube-system
          - --max-concurrent-challenges=60
          - --metrics-listen-address=0.0.0.0:9042
          - --v=6
    ...
      metadata:
        name: cert-manager-cainjector-866c4fd758-ltxxj
        namespace: cert-manager
    ...
      spec:
        containers:
        - args:
          - --leader-election-namespace=kube-system
          - --v=2
    ...
      metadata:
        name: cert-manager-webhook-6d48f88495-c88gd
        namespace: cert-manager
    ...
      spec:
        containers:
        - args:
          ...
          - --v=4

9.8.3. Deleting a TLS secret automatically upon Certificate removal

You can enable the --enable-certificate-owner-ref flag for the cert-manager Operator for Red Hat OpenShift by adding a spec.controllerConfig section in the CertManager resource. The --enable-certificate-owner-ref flag sets the certificate resource as an owner of the secret where the TLS certificate is stored.

Warning

If you uninstall the cert-manager Operator for Red Hat OpenShift or delete certificate resources from the cluster, the secret is deleted automatically. This might cause network connectivity issues depending upon where the certificate TLS secret is being used.

Prerequisites

  • You have access to the OpenShift Container Platform cluster as a user with the cluster-admin role.
  • You have installed the cert-manager Operator for Red Hat OpenShift 1.12.0 or later.

Procedure

  1. Check that the Certificate object and its secret are available by running the following command:

    $ oc get certificate

    Example output

    NAME                                             READY   SECRET                                           AGE
    certificate-from-clusterissuer-route53-ambient   True    certificate-from-clusterissuer-route53-ambient   8h

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

    $ oc edit certmanager cluster
  3. Add a spec.controllerConfig section with the following override arguments:

    apiVersion: operator.openshift.io/v1alpha1
    kind: CertManager
    metadata:
      name: cluster
    # ...
    spec:
    # ...
      controllerConfig:
        overrideArgs:
          - '--enable-certificate-owner-ref'
  4. Save your changes and quit the text editor to apply your changes.

Verification

  • Verify that the --enable-certificate-owner-ref flag is updated for cert-manager controller pod by running the following command:

    $ oc get pods -l app.kubernetes.io/name=cert-manager -n cert-manager -o yaml

    Example output

    # ...
      metadata:
        name: cert-manager-6e4b4d7d97-zmdnb
        namespace: cert-manager
    # ...
      spec:
        containers:
        - args:
          - --enable-certificate-owner-ref

9.8.4. Overriding CPU and memory limits for the cert-manager components

After installing the cert-manager Operator for Red Hat OpenShift, you can configure the CPU and memory limits from the cert-manager Operator for Red Hat OpenShift API for the cert-manager components such as cert-manager controller, CA injector, and Webhook.

Prerequisites

  • You have access to the OpenShift Container Platform cluster as a user with the cluster-admin role.
  • You have installed the cert-manager Operator for Red Hat OpenShift 1.12.0 or later.

Procedure

  1. Check that the deployments of the cert-manager controller, CA injector, and Webhook are available by entering the following command:

    $ oc get deployment -n cert-manager

    Example output

    NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
    cert-manager              1/1     1            1           53m
    cert-manager-cainjector   1/1     1            1           53m
    cert-manager-webhook      1/1     1            1           53m

  2. Before setting the CPU and memory limit, check the existing configuration for the cert-manager controller, CA injector, and Webhook by entering the following command:

    $ oc get deployment -n cert-manager -o yaml

    Example output

    # ...
      metadata:
        name: cert-manager
        namespace: cert-manager
    # ...
      spec:
        template:
          spec:
            containers:
            - name: cert-manager-controller
              resources: {} 1
    # ...
      metadata:
        name: cert-manager-cainjector
        namespace: cert-manager
    # ...
      spec:
        template:
          spec:
            containers:
            - name: cert-manager-cainjector
              resources: {} 2
    # ...
      metadata:
        name: cert-manager-webhook
        namespace: cert-manager
    # ...
      spec:
        template:
          spec:
            containers:
            - name: cert-manager-webhook
              resources: {} 3
    # ...

    1 2 3
    The spec.resources field is empty by default. The cert-manager components do not have CPU and memory limits.
  3. To configure the CPU and memory limits for the cert-manager controller, CA injector, and Webhook, enter the following command:

    $ oc patch certmanager.operator cluster --type=merge -p="
    spec:
      controllerConfig:
        overrideResources:
          limits: 1
            cpu: 200m 2
            memory: 64Mi 3
          requests: 4
            cpu: 10m 5
            memory: 16Mi 6
      webhookConfig:
        overrideResources:
          limits: 7
            cpu: 200m 8
            memory: 64Mi 9
          requests: 10
            cpu: 10m 11
            memory: 16Mi 12
      cainjectorConfig:
        overrideResources:
          limits: 13
            cpu: 200m 14
            memory: 64Mi 15
          requests: 16
            cpu: 10m 17
            memory: 16Mi 18
    "
    1
    Defines the maximum amount of CPU and memory that a single container in a cert-manager controller pod can request.
    2 5
    You can specify the CPU limit that a cert-manager controller pod can request. The default value is 10m.
    3 6
    You can specify the memory limit that a cert-manager controller pod can request. The default value is 32Mi.
    4
    Defines the amount of CPU and memory set by scheduler for the cert-manager controller pod.
    7
    Defines the maximum amount of CPU and memory that a single container in a CA injector pod can request.
    8 11
    You can specify the CPU limit that a CA injector pod can request. The default value is 10m.
    9 12
    You can specify the memory limit that a CA injector pod can request. The default value is 32Mi.
    10
    Defines the amount of CPU and memory set by scheduler for the CA injector pod.
    13
    Defines the maximum amount of CPU and memory Defines the maximum amount of CPU and memory that a single container in a Webhook pod can request.
    14 17
    You can specify the CPU limit that a Webhook pod can request. The default value is 10m.
    15 18
    You can specify the memory limit that a Webhook pod can request. The default value is 32Mi.
    16
    Defines the amount of CPU and memory set by scheduler for the Webhook pod.

    Example output

    certmanager.operator.openshift.io/cluster patched

Verification

  1. Verify that the CPU and memory limits are updated for the cert-manager components:

    $ oc get deployment -n cert-manager -o yaml

    Example output

    # ...
      metadata:
        name: cert-manager
        namespace: cert-manager
    # ...
      spec:
        template:
          spec:
            containers:
            - name: cert-manager-controller
              resources:
                limits:
                  cpu: 200m
                  memory: 64Mi
                requests:
                  cpu: 10m
                  memory: 16Mi
    # ...
      metadata:
        name: cert-manager-cainjector
        namespace: cert-manager
    # ...
      spec:
        template:
          spec:
            containers:
            - name: cert-manager-cainjector
              resources:
                limits:
                  cpu: 200m
                  memory: 64Mi
                requests:
                  cpu: 10m
                  memory: 16Mi
    # ...
      metadata:
        name: cert-manager-webhook
        namespace: cert-manager
    # ...
      spec:
        template:
          spec:
            containers:
            - name: cert-manager-webhook
              resources:
                limits:
                  cpu: 200m
                  memory: 64Mi
                requests:
                  cpu: 10m
                  memory: 16Mi
    # ...

9.9. Authenticating the cert-manager Operator for Red Hat OpenShift with AWS Security Token Service

You can authenticate the cert-manager Operator for Red Hat OpenShift on the AWS Security Token Service (STS) cluster. You can configure cloud credentials for the cert-manager Operator for Red Hat OpenShift by using the ccoctl binary.

9.9.1. Configuring cloud credentials for the cert-manager Operator for Red Hat OpenShift for the AWS Security Token Service cluster

To configure the cloud credentials for the cert-manager Operator for Red Hat OpenShift on the AWS Security Token Service (STS) cluster with the cloud credentials. You must generate the cloud credentials manually, and apply it on the cluster by using the ccoctl binary.

Prerequisites

  • You have extracted and prepared the ccoctl binary.
  • You have configured an OpenShift Container Platform cluster with AWS STS by using the Cloud Credential Operator in manual mode.

Procedure

  1. Create a directory to store a CredentialsRequest resource YAML file by running the following command:

    $ mkdir credentials-request
  2. Create a CredentialsRequest resource YAML file under the credentials-request directory, such as, sample-credential-request.yaml, by applying the following yaml:

    apiVersion: cloudcredential.openshift.io/v1
    kind: CredentialsRequest
    metadata:
      name: cert-manager
      namespace: openshift-cloud-credential-operator
    spec:
      providerSpec:
        apiVersion: cloudcredential.openshift.io/v1
        kind: AWSProviderSpec
        statementEntries:
        - action:
          - "route53:GetChange"
          effect: Allow
          resource: "arn:aws:route53:::change/*"
        - action:
          - "route53:ChangeResourceRecordSets"
          - "route53:ListResourceRecordSets"
          effect: Allow
          resource: "arn:aws:route53:::hostedzone/*"
        - action:
          - "route53:ListHostedZonesByName"
          effect: Allow
          resource: "*"
      secretRef:
        name: aws-creds
        namespace: cert-manager
      serviceAccountNames:
      - cert-manager
  3. Use the ccoctl tool to process CredentialsRequest objects by running the following command:

    $ ccoctl aws create-iam-roles \
        --name <user_defined_name> --region=<aws_region> \
        --credentials-requests-dir=<path_to_credrequests_dir> \
        --identity-provider-arn <oidc_provider_arn> --output-dir=<path_to_output_dir>

    Example output

    2023/05/15 18:10:34 Role arn:aws:iam::XXXXXXXXXXXX:role/<user_defined_name>-cert-manager-aws-creds created
    2023/05/15 18:10:34 Saved credentials configuration to: <path_to_output_dir>/manifests/cert-manager-aws-creds-credentials.yaml
    2023/05/15 18:10:35 Updated Role policy for Role <user_defined_name>-cert-manager-aws-creds

    Copy the <aws_role_arn> from the output to use in the next step. For example, "arn:aws:iam::XXXXXXXXXXXX:role/<user_defined_name>-cert-manager-aws-creds"

  4. Add the eks.amazonaws.com/role-arn="<aws_role_arn>" annotation to the service account by running the following command:

    $ oc -n cert-manager annotate serviceaccount cert-manager eks.amazonaws.com/role-arn="<aws_role_arn>"
  5. To create a new pod, delete the existing cert-manager controller pod by running the following command:

    $ oc delete pods -l app.kubernetes.io/name=cert-manager -n cert-manager

    The AWS credentials are applied to a new cert-manager controller pod within a minute.

Verification

  1. Get the name of the updated cert-manager controller pod by running the following command:

    $ oc get pods -l app.kubernetes.io/name=cert-manager -n cert-manager

    Example output

    NAME                          READY   STATUS    RESTARTS   AGE
    cert-manager-bd7fbb9fc-wvbbt  1/1     Running   0          39s

  2. Verify that AWS credentials are updated by running the following command:

    $ oc set env -n cert-manager po/<cert_manager_controller_pod_name> --list

    Example output

    # pods/cert-manager-57f9555c54-vbcpg, container cert-manager-controller
    # POD_NAMESPACE from field path metadata.namespace
    AWS_ROLE_ARN=XXXXXXXXXXXX
    AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token

9.9.2. Additional resources

9.10. Configuring log levels for cert-manager and the cert-manager Operator for Red Hat OpenShift

To troubleshoot issues with the cert-manager components and the cert-manager Operator for Red Hat OpenShift, you can configure the log level verbosity.

Note

To use different log levels for different cert-manager components, see Customizing cert-manager Operator API fields.

9.10.1. Setting a log level for cert-manager

You can set a log level for cert-manager to determine the verbosity of log messages.

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • You have installed the cert-manager Operator for Red Hat OpenShift 1.11.1 or later.

Procedure

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

    $ oc edit certmanager.operator cluster
  2. Set the log level value by editing the spec.logLevel section:

    apiVersion: operator.openshift.io/v1alpha1
    kind: CertManager
    ...
    spec:
      logLevel: Normal 1
    1
    The default logLevel is Normal. Replace Normal with the desired log level value. The valid log level values for the CertManager resource are Normal, Debug, Trace, and TraceAll. To audit logs and perform common operations when everything is fine, set logLevel to Normal . To troubleshoot a minor issue by viewing verbose logs, set logLevel to Debug . To troubleshoot a major issue by viewing more verbose logs, you can set logLevel to Trace. To troubleshoot serious issues, set logLevel to TraceAll.
    Note

    TraceAll generates huge amount of logs. After setting logLevel to TraceAll, you might experience performance issues.

  3. Save your changes and quit the text editor to apply your changes.

    After applying the changes, the verbosity level for the cert-manager components controller, CA injector, and webhook is updated.

9.10.2. Setting a log level for the cert-manager Operator for Red Hat OpenShift

You can set a log level for the cert-manager Operator for Red Hat OpenShift to determine the verbosity of the operator log messages.

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • You have installed the cert-manager Operator for Red Hat OpenShift 1.11.1 or later.

Procedure

  • Update the subscription object for cert-manager Operator for Red Hat OpenShift to provide the verbosity level for the operator logs by running the following command:

    $ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator --type='merge' -p '{"spec":{"config":{"env":[{"name":"OPERATOR_LOG_LEVEL","value":"v"}]}}}' 1
    1
    Replace v with the desired log level number. The valid values for v can range from 1`to `10. The default value is 2.

Verification

  1. The cert-manager Operator pod is redeployed. Verify that the log level of the cert-manager Operator for Red Hat OpenShift is updated by running the following command:

    $ oc set env deploy/cert-manager-operator-controller-manager -n cert-manager-operator --list | grep -e OPERATOR_LOG_LEVEL -e container

    Example output

    # deployments/cert-manager-operator-controller-manager, container kube-rbac-proxy
    OPERATOR_LOG_LEVEL=9
    # deployments/cert-manager-operator-controller-manager, container cert-manager-operator
    OPERATOR_LOG_LEVEL=9

  2. Verify that the log level of the cert-manager Operator for Red Hat OpenShift is updated by running the oc logs command:

    $ oc logs deploy/cert-manager-operator-controller-manager -n cert-manager-operator

9.10.3. Additional resources

9.11. Authenticating the cert-manager Operator for Red Hat OpenShift with GCP Workload Identity

You can authenticate the cert-manager Operator for Red Hat OpenShift on the GCP Workload Identity cluster by using the cloud credentials. You can configure the cloud credentials by using the ccoctl binary.

9.11.1. Configuring cloud credentials for the cert-manager Operator for Red Hat OpenShift with GCP Workload Identity

Generate the cloud credentials for the cert-manager Operator for Red Hat OpenShift by using the ccoctl binary. Then, apply them to the GCP Workload Identity cluster.

Prerequisites

  • You extracted and prepared the ccoctl binary.
  • The cert-manager Operator for Red Hat OpenShift 1.11.1 or later is installed.
  • You have configured an OpenShift Container Platform cluster with GCP Workload Identity by using the Cloud Credential Operator in a manual mode.

Procedure

  1. Create a directory to store a CredentialsRequest resource YAML file by running the following command:

    $ mkdir credentials-request
  2. In the credentials-request directory, create a YAML file that contains the following CredentialsRequest manifest:

    apiVersion: cloudcredential.openshift.io/v1
    kind: CredentialsRequest
    metadata:
      name: cert-manager
      namespace: openshift-cloud-credential-operator
    spec:
      providerSpec:
        apiVersion: cloudcredential.openshift.io/v1
        kind: GCPProviderSpec
        predefinedRoles:
        - roles/dns.admin
      secretRef:
        name: gcp-credentials
        namespace: cert-manager
      serviceAccountNames:
      - cert-manager
    Note

    The dns.admin role provides admin privileges to the service account for managing Google Cloud DNS resources. To ensure that the cert-manager runs with the service account that has the least privilege, you can create a custom role with the following permissions:

    • dns.resourceRecordSets.*
    • dns.changes.*
    • dns.managedZones.list
  3. Use the ccoctl tool to process CredentialsRequest objects by running the following command:

    $ ccoctl gcp create-service-accounts \
        --name <user_defined_name> --output-dir=<path_to_output_dir> \
        --credentials-requests-dir=<path_to_credrequests_dir> \
        --workload-identity-pool <workload_identity_pool> \
        --workload-identity-provider <workload_identity_provider> \
        --project <gcp_project_id>

    Example command

    $ ccoctl gcp create-service-accounts \
        --name abcde-20230525-4bac2781 --output-dir=/home/outputdir \
        --credentials-requests-dir=/home/credentials-requests \
        --workload-identity-pool abcde-20230525-4bac2781 \
        --workload-identity-provider abcde-20230525-4bac2781 \
        --project openshift-gcp-devel

  4. Apply the secrets generated in the manifests directory of your cluster by running the following command:

    $ ls <path_to_output_dir>/manifests/*-credentials.yaml | xargs -I{} oc apply -f {}
  5. Update the subscription object for cert-manager Operator for Red Hat OpenShift by running the following command:

    $ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator --type=merge -p '{"spec":{"config":{"env":[{"name":"CLOUD_CREDENTIALS_SECRET_NAME","value":"gcp-credentials"}]}}}'

Verification

  1. Get the name of the redeployed cert-manager controller pod by running the following command:

    $ oc get pods -l app.kubernetes.io/name=cert-manager -n cert-manager

    Example output

    NAME                          READY   STATUS    RESTARTS   AGE
    cert-manager-bd7fbb9fc-wvbbt  1/1     Running   0          15m39s

  2. Verify that the cert-manager controller pod is updated with GCP workload identity credential volumes that are mounted under the path specified in mountPath by running the following command:

    $ oc get -n cert-manager pod/<cert-manager_controller_pod_name> -o yaml

    Example output

    spec:
      containers:
      - args:
        ...
        volumeMounts:
        - mountPath: /var/run/secrets/openshift/serviceaccount
          name: bound-sa-token
          ...
        - mountPath: /.config/gcloud
          name: cloud-credentials
      ...
      volumes:
      - name: bound-sa-token
        projected:
          ...
          sources:
          - serviceAccountToken:
              audience: openshift
              ...
              path: token
      - name: cloud-credentials
        secret:
          ...
          items:
          - key: service_account.json
            path: application_default_credentials.json
          secretName: gcp-credentials

9.11.2. Additional resources

9.12. Authenticating the cert-manager Operator for Red Hat OpenShift on AWS

You can configure the cloud credentials for the cert-manager Operator for Red Hat OpenShift on the AWS cluster. The cloud credentials are generated by the Cloud Credential Operator.

9.12.1. Configuring cloud credentials for the cert-manager Operator for Red Hat OpenShift on AWS

To configure the cloud credentials for the cert-manager Operator for Red Hat OpenShift on the AWS cluster you must generate the cloud credentials secret by creating a CredentialsRequest object, and allowing the Cloud Credential Operator.

Prerequisites

  • You have installed the cert-manager Operator for Red Hat OpenShift 1.11.1 or later.
  • You have configured the Cloud Credential Operator to operate in mint or passthrough mode.

Procedure

  1. Create a CredentialsRequest resource YAML file, for example, sample-credential-request.yaml, as follows:

    apiVersion: cloudcredential.openshift.io/v1
    kind: CredentialsRequest
    metadata:
      name: cert-manager
      namespace: openshift-cloud-credential-operator
    spec:
      providerSpec:
        apiVersion: cloudcredential.openshift.io/v1
        kind: AWSProviderSpec
        statementEntries:
        - action:
          - "route53:GetChange"
          effect: Allow
          resource: "arn:aws:route53:::change/*"
        - action:
          - "route53:ChangeResourceRecordSets"
          - "route53:ListResourceRecordSets"
          effect: Allow
          resource: "arn:aws:route53:::hostedzone/*"
        - action:
          - "route53:ListHostedZonesByName"
          effect: Allow
          resource: "*"
      secretRef:
        name: aws-creds
        namespace: cert-manager
      serviceAccountNames:
      - cert-manager
  2. Create a CredentialsRequest resource by running the following command:

    $ oc create -f sample-credential-request.yaml
  3. Update the subscription object for cert-manager Operator for Red Hat OpenShift by running the following command:

    $ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator --type=merge -p '{"spec":{"config":{"env":[{"name":"CLOUD_CREDENTIALS_SECRET_NAME","value":"aws-creds"}]}}}'

Verification

  1. Get the name of the redeployed cert-manager controller pod by running the following command:

    $ oc get pods -l app.kubernetes.io/name=cert-manager -n cert-manager

    Example output

    NAME                          READY   STATUS    RESTARTS   AGE
    cert-manager-bd7fbb9fc-wvbbt  1/1     Running   0          15m39s

  2. Verify that the cert-manager controller pod is updated with AWS credential volumes that are mounted under the path specified in mountPath by running the following command:

    $ oc get -n cert-manager pod/<cert-manager_controller_pod_name> -o yaml

    Example output

    ...
    spec:
      containers:
      - args:
        ...
        - mountPath: /.aws
          name: cloud-credentials
      ...
      volumes:
      ...
      - name: cloud-credentials
        secret:
          ...
          secretName: aws-creds

9.13. Authenticating the cert-manager Operator for Red Hat OpenShift on GCP

You can configure cloud credentials for the cert-manager Operator for Red Hat OpenShift on a GCP cluster. The cloud credentials are generated by the Cloud Credential Operator.

9.13.1. Configuring cloud credentials for the cert-manager Operator for Red Hat OpenShift on GCP

To configure the cloud credentials for the cert-manager Operator for Red Hat OpenShift on a GCP cluster you must create a CredentialsRequest object, and allow the Cloud Credential Operator to generate the cloud credentials secret.

Prerequisites

  • You have installed the cert-manager Operator for Red Hat OpenShift 1.11.1 or later.
  • You have configured the Cloud Credential Operator to operate in mint or passthrough mode.

Procedure

  1. Create a CredentialsRequest resource YAML file, such as, sample-credential-request.yaml by applying the following yaml:

    apiVersion: cloudcredential.openshift.io/v1
    kind: CredentialsRequest
    metadata:
      name: cert-manager
      namespace: openshift-cloud-credential-operator
    spec:
      providerSpec:
        apiVersion: cloudcredential.openshift.io/v1
        kind: GCPProviderSpec
        predefinedRoles:
        - roles/dns.admin
      secretRef:
        name: gcp-credentials
        namespace: cert-manager
      serviceAccountNames:
      - cert-manager
    Note

    The dns.admin role provides admin privileges to the service account for managing Google Cloud DNS resources. To ensure that the cert-manager runs with the service account that has the least privilege, you can create a custom role with the following permissions:

    • dns.resourceRecordSets.*
    • dns.changes.*
    • dns.managedZones.list
  2. Create a CredentialsRequest resource by running the following command:

    $ oc create -f sample-credential-request.yaml
  3. Update the subscription object for cert-manager Operator for Red Hat OpenShift by running the following command:

    $ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator --type=merge -p '{"spec":{"config":{"env":[{"name":"CLOUD_CREDENTIALS_SECRET_NAME","value":"gcp-credentials"}]}}}'

Verification

  1. Get the name of the redeployed cert-manager controller pod by running the following command:

    $ oc get pods -l app.kubernetes.io/name=cert-manager -n cert-manager

    Example output

    NAME                                       READY   STATUS    RESTARTS   AGE
    cert-manager-bd7fbb9fc-wvbbt               1/1     Running   0          15m39s

  2. Verify that the cert-manager controller pod is updated with GCP credential volumes that are mounted under the path specified in mountPath by running the following command:

    $ oc get -n cert-manager pod/<cert-manager_controller_pod_name> -o yaml

    Example output

    spec:
      containers:
      - args:
        ...
        volumeMounts:
        ...
        - mountPath: /.config/gcloud
          name: cloud-credentials
        ....
      volumes:
      ...
      - name: cloud-credentials
        secret:
          ...
          items:
          - key: service_account.json
            path: application_default_credentials.json
          secretName: gcp-credentials

9.14. Uninstalling the cert-manager Operator for Red Hat OpenShift

You can remove the cert-manager Operator for Red Hat OpenShift from OpenShift Container Platform by uninstalling the Operator and removing its related resources.

9.14.1. Uninstalling the cert-manager Operator for Red Hat OpenShift

You can uninstall the cert-manager Operator for Red Hat OpenShift by using the web console.

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • You have access to the OpenShift Container Platform web console.
  • The cert-manager Operator for Red Hat OpenShift is installed.

Procedure

  1. Log in to the OpenShift Container Platform web console.
  2. Uninstall the cert-manager Operator for Red Hat OpenShift Operator.

    1. Navigate to OperatorsInstalled Operators.
    2. Click the Options menu kebab next to the cert-manager Operator for Red Hat OpenShift entry and click Uninstall Operator.
    3. In the confirmation dialog, click Uninstall.

9.14.2. Removing cert-manager Operator for Red Hat OpenShift resources

Once you have uninstalled the cert-manager Operator for Red Hat OpenShift, you have the option to eliminate its associated resources from your cluster.

Prerequisites

  • You have access to the cluster with cluster-admin privileges.
  • You have access to the OpenShift Container Platform web console.

Procedure

  1. Log in to the OpenShift Container Platform web console.
  2. Remove the deployments of the cert-manager components, such as cert-manager, cainjector, and webhook, present in the cert-manager namespace.

    1. Click the Project drop-down menu to see a list of all available projects, and select the cert-manager project.
    2. Navigate to WorkloadsDeployments.
    3. Select the deployment that you want to delete.
    4. Click the Actions drop-down menu, and select Delete Deployment to see a confirmation dialog box.
    5. Click Delete to delete the deployment.
    6. Alternatively, delete deployments of the cert-manager components such as cert-manager, cainjector and webhook present in the cert-manager namespace by using the command-line interface (CLI).

      $ oc delete deployment -n cert-manager -l app.kubernetes.io/instance=cert-manager
  3. Optional: Remove the custom resource definitions (CRDs) that were installed by the cert-manager Operator for Red Hat OpenShift:

    1. Navigate to AdministrationCustomResourceDefinitions.
    2. Enter certmanager in the Name field to filter the CRDs.
    3. Click the Options menu kebab next to each of the following CRDs, and select Delete Custom Resource Definition:

      • Certificate
      • CertificateRequest
      • CertManager (operator.openshift.io)
      • Challenge
      • ClusterIssuer
      • Issuer
      • Order
  4. Optional: Remove the cert-manager-operator namespace.

    1. Navigate to AdministrationNamespaces.
    2. Click the Options menu kebab next to the cert-manager-operator and select Delete Namespace.
    3. In the confirmation dialog, enter cert-manager-operator in the field and click Delete.