openshift-docs/modules/microshift-custom-ca-proc.adoc

// Module included in the following assemblies:
//
// * microshift_security_compliance/microshift-custom-ca.adoc

:_mod-docs-content-type: PROCEDURE
[id="microshift-custom-cas-configuring_{context}"]
= Configuring custom certificate authorities

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

[NOTE]
====
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 access to the cluster as a user with the cluster administration role.
* The certificate authority has issued the custom certificates.
* A {microshift-short} `/etc/microshift/config.yaml` configuration file exists.

.Procedure

. Copy the custom certificates you want to add to the trust root of the {microshift-short} host. Ensure that the
certificate and private keys are only accessible to {microshift-short}.

. For each custom CA that you need, add an `apiServer` section called `namedCertificates` to the `/etc/microshift/config.yaml` {microshift-short} configuration file by using the following example:
+
[source,yaml]
----
apiServer:
  namedCertificates:
   - certPath: ~/certs/api_fqdn_1.crt <1>
     keyPath:  ~/certs/api_fqdn_1.key <2>
   - certPath: ~/certs/api_fqdn_2.crt
     keyPath:  ~/certs/api_fqdn_2.key
     names: <3>
     - api_fqdn_1
     - *.apps.external.com
----
<1> Add the full path to the certificate.
<2> Add the full path to the certificate key.
<3> Optional. Add a list of explicit DNS names. Leading wildcards are allowed. If no names are provided, the implicit names are extracted from the certificates.

. Restart the {microshift-service} to apply the certificates by running the following command:
+
[source,terminal]
----
$ 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:
+
[source,terminal]
----
$ export KUBECONFIG=~/custom-kubeconfigs/kubeconfig <1>
----
<1> Use the location of the copied `kubeconfig` file as the path.

.. Check that the certificates are applied by using the following command:
+
[source,terminal]
----
$ oc --certificate-authority ~/certs/ca.ca get node
----
+
.Example output
[source,terminal]
----
oc get node
NAME                             STATUS   ROLES                         AGE   VERSION
dhcp-1-235-195.arm.example.com   Ready    control-plane,master,worker   76m   v1.29.2
----

.. Add the new CA file to the $KUBECONFIG environment variable by running the following command:
+
[source,terminal]
----
$ 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:
+
[source,terminal]
----
$ oc config view --flatten
----
+
.Example externally generated `kubeconfig` file
+
[source,yaml]
----
apiVersion: v1
clusters:
- cluster:
    certificate-authority: /tmp/certificate-authority-data-new.crt <1>
    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: {}
----
<1> 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:
+
[source,terminal]
----
$ 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.
----
+
[IMPORTANT]
====
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. See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#the-system-wide-trust-store_using-shared-system-certificates[The system-wide truststore] for details.
** 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.