1. Documentation
×

Configuring Custom Certificates

Overview

Administrators can configure custom serving certificates for the public host names of the OKD API and web console. This can be done during an advanced installation or configured after installation.

Configuring Custom Certificates with Ansible

During advanced installations, custom certificates can be configured using the openshift_master_named_certificates and openshift_master_overwrite_named_certificates parameters, which are configurable in the inventory file. More details are available about configuring custom certificates with Ansible.

Example Custom Certificate Configuration with Ansible
# Configure custom named certificates
# NOTE: openshift_master_named_certificates is cached on masters and is an
# additive fact, meaning that each run with a different set of certificates
# will add the newly provided certificates to the cached set of certificates.
#
# An optional CA may be specified for each named certificate. CAs will
# be added to the OpenShift CA bundle which allows for the named
# certificate to be served for internal cluster communication.
#
# If you would like openshift_master_named_certificates to be overwritten with
# the provided value, specify openshift_master_overwrite_named_certificates.
openshift_master_overwrite_named_certificates=true
#
# Provide local certificate paths which will be deployed to masters
openshift_master_named_certificates=[{"certfile": "/path/on/host/to/custom1.crt", "keyfile": "/path/on/host/to/custom1.key", "cafile": "/path/on/host/to/custom-ca1.crt"}]
#
# Detected names may be overridden by specifying the "names" key
#openshift_master_named_certificates=[{"certfile": "/path/on/host/to/custom1.crt", "keyfile": "/path/on/host/to/custom1.key", "names": ["public-master-host.com"], "cafile": "/path/on/host/to/custom-ca1.crt"}]

Configuring Custom Certificates

In the master configuration file you can list the namedCertificates section in the assetConfig.servingInfo section so the custom certificate serves up for the web console, and in the servingInfo section so the custom certificate serves up for the CLI and other API calls. Multiple certificates can be configured this way and each certificate may be associated with multiple host names or wildcards.

A default certificate must be configured in the servingInfo.certFile and servingInfo.keyFile configuration sections in addition to namedCertificates.

The namedCertificates section should only be configured for the host name associated with the masterPublicURL, assetConfig.publicURL, and oauthConfig.assetPublicURL settings. Using a custom serving certificate for the host name associated with the masterURL will result in TLS errors as infrastructure components will attempt to contact the master API using the internal masterURL host.
Custom Certificates Configuration
servingInfo:
  logoutURL: ""
  masterPublicURL: https://openshift.example.com:8443
  publicURL: https://openshift.example.com:8443/console/
  bindAddress: 0.0.0.0:8443
  bindNetwork: tcp4
  certFile: master.server.crt (1)
  clientCA: ""
  keyFile: master.server.key (1)
  maxRequestsInFlight: 0
  requestTimeoutSeconds: 0
  namedCertificates:
    - certFile: wildcard.example.com.crt (2)
      keyFile: wildcard.example.com.key (2)
      names:
        - "openshift.example.com"
  metricsPublicURL: "https://metrics.os.example.com/hawkular/metrics"

Relative paths are resolved relative to the master configuration file. Restart the server to pick up the configuration changes.

For the master API or web console, wildcard names are accepted.

Configuring a Custom Wildcard Certificate for the Default Router

You can configure the OKD default router with a default wildcard certificate. A default wildcard certificate provides a convenient way for applications that are deployed in OKD to use default encryption without needing custom certificates.

Default wildcard certificates are recommended for non-production environments only.

To configure a default wildcard certificate, provision a certificate that is valid for *.<app_domain>, where <app_domain> is the value of openshift_master_default_subdomain in the Ansible inventory file, by default /etc/ansible/hosts. Once provisioned, place the certificate, key, and ca certificate files on your Ansible host, and add the following line to your Ansible inventory file.

openshift_hosted_router_certificate={"certfile": "/path/to/apps.c1-ocp.myorg.com.crt", "keyfile": "/path/to/apps.c1-ocp.myorg.com.key", "cafile": "/path/to/apps.c1-ocp.myorg.com.ca.crt"}

For example:

openshift_hosted_router_certificate={"certfile": "/home/cloud-user/star-apps.148.251.233.173.nip.io.cert.pem", "keyfile": "/home/cloud-user/star-apps.148.251.233.173.nip.io.key.pem", "cafile": "/home/cloud-user/ca-chain.cert.pem"}

Where the parameter values are:

  • certfile is the path to the file that contains the OKD router wildcard certificate.

  • keyfile is the path to the file that contains the OKD router wildcard certificate key.

  • cafile is the path to the file that contains the root CA for this key and certificate. If an intermediate CA is in use, the file should contain both the intermediate and root CA.

If these certificate files are new to your OKD cluster, run the Ansible byo/config.yml playbook to add these files to the OKD configuration files. The playbook adds the certificate files to the /etc/origin/master/ directory.

# ansible-playbook [-i /path/to/inventory] \
    ~/openshift-ansible/playbooks/byo/config.yml

If the certificates are not new, for example, you want to change existing certificates or replace expired certificates, run the following playbook:

ansible-playbook /usr/share/ansible/openshift-ansible/playbooks/redeploy-certificates.yml
For this playbook to run, the certificate names must not change. If the certificate names change, rerun the Ansible byo/config.yml playbook as if the certificates were new.

Configuring a Custom Certificate for a Load Balancer

If your OKD cluster uses the default load balancer or an enterprise-level load balancer, you can use custom certificates to make the web console and API available externally using a publicly-signed custom certificate. leaving the existing internal certificates for the internal endpoints.

To configure OKD to use custom certificates in this way:

  1. Edit the servingInfo section of the master configuration file:

    servingInfo:
  logoutURL: ""
  masterPublicURL: https://openshift.example.com:8443
  publicURL: https://openshift.example.com:8443/console/
  bindAddress: 0.0.0.0:8443
  bindNetwork: tcp4
  certFile: master.server.crt
  clientCA: ""
  keyFile: master.server.key
  maxRequestsInFlight: 0
  requestTimeoutSeconds: 0
  namedCertificates:
    - certFile: wildcard.example.com.crt (1)
      keyFile: wildcard.example.com.key (2)
      names:
        - "openshift.example.com"
  metricsPublicURL: "https://metrics.os.example.com/hawkular/metrics"
    1 Path to the certificate file for the web console.
    2 Path to the key file for the web console.

    Configure the namedCertificates section for only the host name associated with the masterPublicURL and oauthConfig.assetPublicURL settings. Using a custom serving certificate for the host name associated with the masterURL causes in TLS errors as infrastructure components attempt to contact the master API using the internal masterURL host.

  2. Specify the openshift_master_cluster_public_hostname and openshift_master_cluster_hostname paramaters in the Ansible inventory file, by default /etc/ansible/hosts. These values must be different. If they are the same, the named certificates will fail.

    # Native HA with External LB VIPs
openshift_master_cluster_hostname=paas.example.com (1)
openshift_master_cluster_public_hostname=public.paas.example.com (2)
    1 The FQDN for internal load balancer configured for SSL passthrough.
    2 The FQDN for external the load balancer with custom (public) certificate.

For information specific to your load balancer environment, refer to the OKD Reference Architecture for your provider and Custom Certificate SSL Termination (Production).