×

In the OpenShift Container Platform, the route API is extended to provide a configurable option to reference TLS certificates via secrets. With the Creating a route with externally managed certificate Technology Preview feature enabled, you can minimize errors from manual intervention, streamline the certificate management process, and enable the OpenShift Container Platform router to promptly serve the referenced certificate.

Securing routes with the cert-manager Operator for Red Hat OpenShift is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

Configuring certificates to secure routes in your cluster

The following steps demonstrate the process of utilizing the cert-manager Operator for Red Hat OpenShift with the Let’s Encrypt ACME HTTP-01 challenge type to secure the route resources in your OpenShift Container Platform cluster.

Prerequisites
  • You have installed version 1.14.0 or later of the cert-manager Operator for Red Hat OpenShift.

  • You have enabled the RouteExternalCertificate feature gate.

  • You have the create and update permissions on the routes/custom-host sub-resource.

  • You have a Service resource that you want to expose.

Procedure
  1. Create a Route resource for your Service resource using edge TLS termination and a custom hostname by running the following command. The hostname will be used while creating a Certificate resource in the following steps.

    $ oc create route edge <route_name> \ (1)
      --service=<service_name> \ (2)
      --hostname=<hostname> \ (3)
      --namespace=<namespace> (4)
    
    1 Specify your route’s name.
    2 Specify the service you want to expose.
    3 Specify the hostname of your route.
    4 Specify the namespace where your route is located.
  2. Create an Issuer to configure the HTTP-01 solver by running the following command. For other ACME issuer types, see "Configuring ACME an issuer".

    Example Issuer.yaml file
    $ oc create -f - << EOF
    apiVersion: cert-manager.io/v1
    kind: Issuer
    metadata:
      name: letsencrypt-acme
      namespace: <namespace> (1)
    spec:
      acme:
        server: https://acme-v02.api.letsencrypt.org/directory
        privateKeySecretRef:
          name: letsencrypt-acme-account-key
        solvers:
          - http01:
              ingress:
                ingressClassName: openshift-default
    EOF
    1 Specify the namespace where the Issuer is located. It should be the same as your route’s namespace.
  3. Create a Certificate object for the route by running the following command. The secretName specifies the TLS secret that is going to be issued and managed by cert-manager and will also be referenced in your route in the following steps.

    $ oc create -f - << EOF
    apiVersion: cert-manager.io/v1
    kind: Certificate
    metadata:
      name: example-route-cert
      namespace: <namespace> (1)
    spec:
      commonName: <hostname> (2)
      dnsNames:
        - <hostname> (3)
      usages:
        - server auth
      issuerRef:
        kind: Issuer
        name: letsencrypt-acme
      secretName: <secret_name> (4)
    EOF
    1 Specify the namespace where the Certificate resource is located. It should be the same as your route’s namespace.
    2 Specify the certificate’s common name using the hostname of the route.
    3 Add the hostname of your route to the certificate’s DNS names.
    4 Specify the name of the secret that contains the certificate.
  4. Create a Role to provide the router service account permissions to read the referenced secret by using the following command:

    $ oc create role secret-reader \
      --verb=get,list,watch \
      --resource=secrets \
      --resource-name=<secret_name> \ (1)
      --namespace=<namespace> (2)
    
    1 Specify the name of the secret that you want to grant access to. It should be consistent with your secretName specified in the Certificate resource.
    2 Specify the namespace where both your secret and route are located.
  5. Create a RoleBinding resource to bind the router service account with the newly created Role resource by using the following command:

    $ oc create rolebinding secret-reader-binding \
      --role=secret-reader \
      --serviceaccount=openshift-ingress:router \
      --namespace=<namespace> (1)
    1 Specify the namespace where both your secret and route are located.
  6. Update your route’s .spec.tls.externalCertificate field to reference the previously created secret and use the certificate issued by cert-manager by using the following command:

    $ oc patch route <route_name> \ (1)
      -n <namespace> \ (2)
      --type=merge \
      -p '{"spec":{"tls":{"externalCertificate":{"name":"<secret_name>"}}}}' (3)
    
    1 Specify the route name.
    2 Specify the namespace where both your secret and route are located.
    3 Specify the name of the secret that contains the certificate.
Verification
  • Verify that the certificate is created and ready to use by running the following command:

    $ oc get certificate -n <namespace> (1)
    $ oc get secret -n <namespace> (1)
    1 Specify the namespace where both your secret and route reside.
  • Verify that the router is using the referenced external certificate by running the following command. The command should return with the status code 200 OK.

    $ curl -IsS https://<hostname> (1)
    1 Specify the hostname of your route.
  • Verify the server certificate’s subject, subjectAltName and issuer are all as expected from the curl verbose outputs by running the following command:

    $ curl -v https://<hostname> (1)
    1 Specify the hostname of your route.

    The route is now successfully secured by the certificate from the referenced secret issued by cert-manager. cert-manager will automatically manage the certificate’s lifecycle.