Skip to content

Latest commit

 

History

History
400 lines (315 loc) · 18.3 KB

certificate_customization.adoc

File metadata and controls

400 lines (315 loc) · 18.3 KB

Configuring Custom Certificates

Overview

Administrators can configure custom serving certificates for the public host names of the {product-title} API and web console. This can be done during a cluster installation or configured after installation.

Configuring Custom Certificates During Installation

During cluster 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.

Custom Certificate Configuration Parameters
openshift_master_overwrite_named_certificates=true (1)
openshift_master_named_certificates=[{"certfile": "/path/on/host/to/crt-file", "keyfile": "/path/on/host/to/key-file", "names": ["public-master-host.com"], "cafile": "/path/on/host/to/ca-file"}] (2)
openshift_hosted_router_certificate={"certfile": "/path/on/host/to/app-crt-file", "keyfile": "/path/on/host/to/app-key-file", "cafile": "/path/on/host/to/app-ca-file"} (3)

  1. If you provide a value for the openshift_master_named_certificates parameter, set this parameter to true.

  2. Provisions a master API certificate.

  3. Provisions a wildcard API certificate.

Example parameters for a master API certificate:

openshift_master_overwrite_named_certificates=true
openshift_master_named_certificates=[{"names": ["master.148.251.233.173.nip.io"], "certfile": "/home/cloud-user/master-bundle.cert.pem", "keyfile": "/home/cloud-user/master.148.251.233.173.nip.io.key.pem" ]

Example parameters for a wildcard API certificate:

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"}

Configuring Custom Certificates for the Web Console or CLI

You can specify custom certificates for the web console and for the CLI through the servingInfo section of the master configuration file:

  • The servingInfo.namedCertificates section serves up custom certificates for the web console.

  • The servingInfo section serves up custom certificates for the CLI and other API calls.

You can configure multiple certificates this way, and each certificate can be associated with multiple host names, multiple routers, or the {product-title} image registry.

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

Note

The namedCertificates section should be configured only for the host name associated with the masterPublicURL and oauthConfig.assetPublicURL settings n the /etc/origin/master/master-config.yaml file. 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"

  1. Path to certificate and key files for the CLI and other API calls.

  2. Path to certificate and key files for the web console.

The openshift_master_cluster_public_hostname and openshift_master_cluster_hostname parameters in the Ansible inventory file, by default /etc/ansible/hosts, must be different. If they are the same, the named certificates will fail and you will need to re-install them.

# Native HA with External LB VIPs
openshift_master_cluster_hostname=internal.paas.example.com
openshift_master_cluster_public_hostname=external.paas.example.com

For more information on using DNS with {product-title}, see the DNS installation prerequisites.

This approach allows you to take advantage of the self-signed certificates generated by {product-title} and add custom trusted certificates to individual components as needed.

Note that the internal infrastructure certificates remain self-signed, which might be perceived as bad practice by some security or PKI teams. However, any risk here is minimal, as the only clients that trust these certificates are other components within the cluster. All external users and systems use custom trusted certificates.

Relative paths are resolved based on the location of the master configuration file. Restart the server to pick up the configuration changes.

Configuring a Custom Master Host Certificate

In order to facilitate trusted connections with external users of {product-title}, you can provision a named certificate that matches the domain name provided in the openshift_master_cluster_public_hostname paramater in the Ansible inventory file, by default /etc/ansible/hosts.

You must place this certificate in a directory accessible to Ansible and add the path in the Ansible inventory file, as follows:

openshift_master_named_certificates=[{"certfile": "/path/to/console.ocp-c1.myorg.com.crt", "keyfile": "/path/to/console.ocp-c1.myorg.com.key", "names": ["console.ocp-c1.myorg.com"]}]

Where the parameter values are:

  • certfile is the path to the file that contains the {product-title} custom certificate.

  • keyfile is the path to the file that contains the {product-title} custom key.

  • names is the cluster public hostname.

The file paths must be local to the system where Ansible runs. Certificates are copied to master hosts and are deployed within the /etc/origin/master directory.

When securing the registry, add the service hostnames and IP addresses to the server certificate for the registry. The Subject Alternative Names (SAN) must contain the following.

  • Two service hostnames:

    docker-registry.default.svc.cluster.local
docker-registry.default.svc

  • Service IP address.

    For example:

    172.30.252.46

    Use the following command to get the container image registry service IP address:

    oc get service docker-registry --template='{{.spec.clusterIP}}'

  • Public hostname.

    docker-registry-default.apps.example.com

    Use the following command to get the container image registry public hostname:

    oc get route docker-registry --template '{{.spec.host}}'

For example, the server certificate should contain SAN details similar to the following:

X509v3 Subject Alternative Name:
               DNS:docker-registry-public.openshift.com, DNS:docker-registry.default.svc, DNS:docker-registry.default.svc.cluster.local, DNS:172.30.2.98, IP Address:172.30.2.98

Configuring a Custom Wildcard Certificate for the Default Router

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

Note

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

In order 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 {product-title} router certificate.

  • keyfile is the path to the file that contains the {product-title} wildcard 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 {product-title} cluster, change to the playbook directory and run the Ansible deploy_router.yml playbook to add these files to the {product-title} configuration files. The playbook adds the certificate files to the /etc/origin/master/ directory.









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








ansible-playbook /usr/share/ansible/openshift-ansible/playbooks/redeploy-certificates.yml













Note



For this playbook to run, the certificate names must not change. If the certificate names change, rerun the Ansible deploy_cluster.yml playbook
as if the certificates were new.














Configuring a Custom Certificate for the Image Registry






The {product-title} image registry is an internal service that facilitates builds and deployments. Most of the communication with the registry is handled by internal components in {product-title}. As such, you should not need to replace the certificate used by the registry service itself.






However, by default, the registry uses routes to allow external systems and users to do pulls and pushes of images. You can use a re-encrypt route with a custom certificate that is presented to external users instead of using the internal, self-signed certificate.






To configure this, add the
following lines
of code to the [OSEv3:vars] section of the Ansible inventory file, by default
/etc/ansible/hosts file. Specify the certificates to use with the registry
route.








openshift_hosted_registry_routehost=registry.apps.c1-ocp.myorg.com (1)
openshift_hosted_registry_routecertificates={"certfile": "/path/to/registry.apps.c1-ocp.myorg.com.crt", "keyfile": "/path/to/registry.apps.c1-ocp.myorg.com.key", "cafile": "/path/to/registry.apps.c1-ocp.myorg.com-ca.crt"} (2)
openshift_hosted_registry_routetermination=reencrypt (3)








    

  1. 

    The host name of the registry.
    

    2. 

  2. 

    The locations of the cacert, root, and cafile files.
    

    

      

    • 

      certfile is the path to the file that contains the {product-title} router certificate.
      

      • 

    • 

      keyfile is the path to the file that contains the {product-title} wildcard 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.
      

      • 

    

    

    3. 

  3. 

    Specify where encryption is performed:
    

    

      

    • 

      Set to reencrypt with a re-encrypt route to terminate encryption at the edge router and re-encrypt it with a new certificate supplied by the destination.
      

      • 

    • 

      Set to passthrough to terminate encryption at the destination. The destination is responsible for decrypting traffic.
      

      • 

    

    

    4. 











Configuring a Custom Certificate for a Load Balancer






If your {product-title} 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 {product-title} 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. 

    2. 

      Path to the key file for the web console.
      

      

      

      


      Note
      
      		


      

      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.
      

      
      		

      

      

      

      3. 

    

    

    2. 

  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. 

    2. 

      The FQDN for external the load balancer with custom (public) certificate.
      

      3. 

    

    

    3. 







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










Retrofit Custom Certificates into a Cluster






You can retrofit custom master and custom router certificates into an existing {product-title} cluster by editing the
the Ansible inventory file, by default /etc/ansible/hosts, and running a playbook.






Retrofit Custom Master Certificates into a Cluster




To retrofit custom certificates:






    

  1. 

    Edit the Ansible inventory file to set the openshift_master_overwrite_named_certificates=true.
    

    2. 

  2. 

    Specify the path to the certificate using the openshift_master_named_certificates parameter.
    

    

    

    openshift_master_overwrite_named_certificates=true
openshift_master_named_certificates=[{"certfile": "/path/on/host/to/crt-file", "keyfile": "/path/on/host/to/key-file", "names": ["public-master-host.com"], "cafile": "/path/on/host/to/ca-file"}] (1)
    

    

    


    3. 

  3. 

    Change to the playbook directory and run the following playbook:
    

    

    

    ansible-playbook /usr/share/ansible/openshift-ansible/playbooks/redeploy-certificates.yml
    

    

    

    4. 









Retrofit Custom Router Certificates into a Cluster




To retrofit custom router certificates:






    

  1. 

    Edit the Ansible inventory file to set the openshift_master_overwrite_named_certificates=true.
    

    2. 

  2. 

    Specify the path to the certificate using the openshift_hosted_router_certificate parameter.
    

    

    

    openshift_master_overwrite_named_certificates=true
openshift_hosted_router_certificate={"certfile": "/path/on/host/to/app-crt-file", "keyfile": "/path/on/host/to/app-key-file", "cafile": "/path/on/host/to/app-ca-file"} (1)
    

    

    


    3. 

  3. 

    Change to the playbook directory and run the following playbook:
    

    

    

    $ cd /usr/share/ansible/openshift-ansible
$ ansible-playbook playbooks/openshift-hosted/redeploy-router-certificates.yml
    

    

    

    4. 













Using Custom Certificates with Other Components






For information on how other components, such as Logging & Metrics, use custom certificates, see
Certificate Management.