Red Hat build of MicroShift

Configure custom certificate authorities

To configure externally generated certificates and domain names by using custom certificate authorities (CAs), add them to the MicroShift /etc/microshift/config.yaml configuration file. You must also configure the host operating system trust root.

Externally generated kubeconfig files are created in the /var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig directory. If you need to use localhost in addition to externally generated configurations, retain the original kubeconfig file in its default location. The localhost kubeconfig file uses the self-signed certificate authority.

Prerequisites

The OpenShift CLI (oc) is installed.
You have root access to the node.
The certificate authority has issued the custom certificates.
A MicroShift /etc/microshift/config.yaml configuration file exists.

Procedure

Copy the custom certificates you want to add to the trust root of the MicroShift host. Ensure that the certificate and private keys are only accessible to MicroShift.
For each custom CA that you need, add an apiServer section called namedCertificates to the /etc/microshift/config.yaml MicroShift configuration file by using the following example:
```
apiServer:
  namedCertificates:
   - certPath: ~/certs/api_fqdn_1.crt
     keyPath:  ~/certs/api_fqdn_1.key
   - certPath: ~/certs/api_fqdn_2.crt
     keyPath:  ~/certs/api_fqdn_2.key
     names:
     - api_fqdn_1
     - *.apps.external.com
```
where:

apiServer.namedCertificates.certPath

Add the full path to the certificate.

apiServer.namedCertificates.keyPath

Add the full path to the certificate key.

apiServer.namedCertificates.names

Optional. Add a list of explicit DNS names. Leading wildcards are allowed. If no names are listed, the implicit names are extracted from the certificates.
Restart the MicroShift to apply the certificates by running the following command:
```
$ systemctl microshift restart
```
Wait a few minutes for the system to restart and apply the custom server. New kubeconfig files are generated in the /var/lib/microshift/resources/kubeadmin/ directory.
Copy the kubeconfig files to the client. If you specified wildcards for the IP address, update the kubeconfig to remove the public IP address of the server and replace that IP address with the specific wildcard range you want to use.

From the client, use the following steps:

Specify the kubeconfig to use by running the following command:
```
$ export KUBECONFIG=~/custom-kubeconfigs/kubeconfig
```
Use the location of the copied kubeconfig file as the path.

Check that the certificates are applied by using the following command:

$ oc --certificate-authority ~/certs/ca.ca get node

Example output

oc get node
NAME                             STATUS   ROLES                         AGE   VERSION
dhcp-1-235-195.arm.example.com   Ready    control-plane,master,worker   76m   v1.33.4

Add the new CA file to the $KUBECONFIG environment variable by running the following command:

$ oc config set clusters.microshift.certificate-authority /tmp/certificate-authority-data-new.crt

Verify that the new kubeconfig file contains the new CA by running the following command:

$ oc config view --flatten

Example externally generated kubeconfig file

apiVersion: v1
clusters:
- cluster:
    certificate-authority: /tmp/certificate-authority-data-new.crt
    server: https://api.ci-ln-k0gim2b-76ef8.aws-2.ci.openshift.org:6443
  name: ci-ln-k0gim2b-76ef8
contexts:
- context:
    cluster: ci-ln-k0gim2b-76ef8
    user:
  name:
current-context:
kind: Config
preferences: {}

where:

clusters.cluster.certificate-authority: The certificate-authority-data section is not present in externally generated kubeconfig files. It is added with the oc config set command used previously.

Verify the subject and issuer of your customized API server certificate authority by running the following command:

$ curl --cacert /tmp/caCert.pem https://${fqdn_name}:6443/healthz -v

Example output

Server certificate:
  subject: CN=kas-test-cert_server
  start date: Mar 12 11:39:46 2024 GMT
  expire date: Mar 12 11:39:46 2025 GMT
  subjectAltName: host "dhcp-1-235-3.arm.eng.rdu2.redhat.com" matched cert's "dhcp-1-235-3.arm.eng.rdu2.redhat.com"
  issuer: CN=kas-test-cert_ca
  SSL certificate verify ok.

Either replace the certificate-authority-data in the generated kubeconfig file with the new rootCA or add the certificate-authority-data to the trust root of the operating system. Do not use both methods.

Configure additional CAs in the trust root of the operating system. For example, in the RHEL Client truststore on the client system. The system-wide truststore.
- Updating the certificate bundle with the configuration that contains the CA is recommended.
- If you do not want to configure your certificate bundles, you can alternately use the oc login localhost:8443 --certificate-authority=/path/to/cert.crt command, but this method is not preferred.