Use custom certificate authorities for the MicroShift API server

To enable external clients to verify the MicroShift API server and maintain encrypted connections, you can replace the default internal certificate with a custom server certificate issued by a trusted certificate authority (CA).

By default, clients outside of the node cannot verify the MicroShift-issued API server certificate. You must update the configuration file with the certificate location and relevant domain names to ensure secure access across your network.

The following steps illustrate the workflow for customizing the API server certificate configuration in MicroShift:

  1. Copy the certificates and keys to the preferred directory in the host operating system. Ensure that the files are accessible only with root access.

  2. Update the MicroShift configuration for each custom CA by specifying the certificate names and new fully qualified domain name (FQDN) in the MicroShift /etc/microshift/config.yaml configuration file.

    Each certificate configuration can contain the following values:

    • The certificate file location is a required value.

    • A single common name containing the API server DNS and IP address or IP address range.

      Tip

      In most cases, MicroShift generates a new kubeconfig file for your custom CA that includes the IP address or range that you specify. The exception is when you specify wildcards for the IP address. In this case, MicroShift generates a kubeconfig file with the public IP address of the server. To use wildcards, you must update the kubeconfig file with your specific details.

    • Multiple Subject Alternative Names (SANs) containing the API server DNS and IP addresses or a wildcard certificate.

    • You can list additional DNS names for each certificate.

  3. After the MicroShift service restarts, you must copy the generated kubeconfig files to the client.

  4. Configure additional CAs on the client system. For example, you can update CA bundles in the Red Hat Enterprise Linux (RHEL) truststore.

    Important

    Custom server certificates must be validated against CA data configured in the trust root of the host operating system. For more information, read the following documentation:

  5. The certificates and keys are read from the specified file location on the host. You can test and validate configuration from the client.

    • If any validation fails, MicroShift skips the custom configuration and uses the default certificate to start. The priority is to continue the service uninterrupted. MicroShift logs errors when the service starts. Common errors include expired certificates, missing files, or wrong IP addresses.

  6. External server certificates are not automatically renewed. You must manually rotate your external certificates.

↑ Up: Secure the MicroShift API and control plane | ⌂ Home: Red Hat build of MicroShift | Next: Configure custom certificate authorities →