Adding API server certificates

The default API server certificate is issued by an internal OpenShift Container Platform cluster CA. Clients outside of the cluster will not be able to verify the API server’s certificate by default. This certificate can be replaced by one that is issued by a CA that clients trust.

Note

In hosted control plane clusters, you can add as many custom certificates to your Kubernetes API Server as you need. However, do not add a certificate for the endpoint that worker nodes use to communicate with the control plane. For more information, see Configuring a custom API server certificate in a hosted cluster.

Add an API server named certificate

The default API server certificate is issued by an internal OpenShift Container Platform cluster CA. You can add one or more alternative certificates that the API server will return based on the fully qualified domain name (FQDN) requested by the client, for example when a reverse proxy or load balancer is used.

Prerequisites

You must have a certificate for the FQDN and its corresponding private key. Each should be in a separate PEM format file.
The private key must be unencrypted. If your key is encrypted, decrypt it before importing it into OpenShift Container Platform.
The certificate must include the subjectAltName extension showing the FQDN.
The certificate file can contain one or more certificates in a chain. The certificate for the API server FQDN must be the first certificate in the file. It can then be followed with any intermediate certificates, and the file should end with the root CA certificate.

Warning

Do not provide a named certificate for the internal load balancer (host name api-int.<cluster_name>.<base_domain>). Doing so will leave your cluster in a degraded state.

Procedure

Login to the new API as the kubeadmin user.

$ oc login -u kubeadmin -p <password> https://FQDN:6443

Get the kubeconfig file.

$ oc config view --flatten > kubeconfig-newapi

Create a secret that contains the certificate chain and private key in the openshift-config namespace.
```
$ oc create secret tls <secret> \
     --cert=</path/to/cert.crt> \
     --key=</path/to/cert.key> \
     -n openshift-config
```
1. <secret> is the name of the secret that will contain the certificate chain and private key.
2. </path/to/cert.crt> is the path to the certificate chain on your local file system.
3. </path/to/cert.key> is the path to the private key associated with this certificate.
Update the API server to reference the created secret.
```
$ oc patch apiserver cluster \
     --type=merge -p \
     '{"spec":{"servingCerts": {"namedCertificates":
     [{"names": ["<FQDN>"],
     "servingCertificate": {"name": "<secret>"}}]}}}'
```
where:

<FQDN>

Replace <FQDN> with the FQDN that the API server should provide the certificate for. Do not include the port number.

<secret>

Replace <secret> with the name used for the secret in the previous step.

Examine the apiserver/cluster object and confirm the secret is now referenced.

$ oc get apiserver cluster -o yaml

Example output

...
spec:
  servingCerts:
    namedCertificates:
    - names:
      - <FQDN>
      servingCertificate:
        name: <secret>
...

Check the kube-apiserver operator, and verify that a new revision of the Kubernetes API server rolls out. It may take a minute for the operator to detect the configuration change and trigger a new deployment. While the new revision is rolling out, PROGRESSING will report True.
```
$ oc get clusteroperators kube-apiserver
```
Do not continue to the next step until PROGRESSING is listed as False, as shown in the following output:
Example output
```
NAME             VERSION   AVAILABLE   PROGRESSING   DEGRADED   SINCE
kube-apiserver   4.19.0     True        False         False      145m
```
If PROGRESSING is showing True, wait a few minutes and try again.

Note

A new revision of the Kubernetes API server only rolls out if the API server named certificate is added for the first time. When the API server named certificate is renewed, a new revision of the Kubernetes API server does not roll out because the kube-apiserver pods dynamically reload the updated certificate.