// Module included in the following assemblies:
//
// * security/certificates/api-server.adoc

:_mod-docs-content-type: PROCEDURE
[id="customize-certificates-api-add-named_{context}"]
= Adding an API server named certificate for the first time

[role="_abstract"]
The default API server certificate is issued by an internal {product-title} cluster Certificate Authority (CA). You can add 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.

[NOTE]
====
Adding a custom API server named certificate for the first time triggers the `kube-apiserver-operator` to roll out a new revision of the API server pods. Node reboots are not required.
====

.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.
* 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, followed by intermediate certificates, and ending 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

. Log in to the CLI as the `kubeadmin` user:
+
[source,terminal]
----
$ oc login -u kubeadmin -p <password> https://<fqdn>:6443
----
+
where:
+
--
`<password>`:: Specifies your cluster administrative password.
`<fqdn>`:: Specifies the fully qualified domain name of the internal cluster API endpoint.
--

. Create a secret that contains the certificate chain and private key in the `openshift-config` namespace:
+
[source,terminal]
----
$ oc create secret tls <secret_name> \
     --cert=<path_to_certificate_file> \
     --key=<path_to_private_key_file> \
     -n openshift-config
----
+
where:
+
--
`<secret_name>`:: Specifies the name of the new secret resource that will contain the cryptographic key pair.
`<path_to_certificate_file>`:: Specifies the absolute local path to your custom certificate chain file.
`<path_to_private_key_file>`:: Specifies the absolute local path to the unencrypted private key file associated with the certificate.
--

. Update the API server to reference the created secret resource:
+
[source,terminal]
----
$ oc patch apiserver cluster --type=merge -p '
{
  "spec": {
    "servingCerts": {
      "namedCertificates": [
        {
          "names": ["<fqdn>"],
          "servingCertificate": {
            "name": "<secret_name>"
          }
        }
      ]
    }
  }
}'
----
+
where:
+
--
`<fqdn>`:: Specifies the fully qualified domain name for which the API server serves this custom certificate. Do not include a port number.
`<secret_name>`:: Specifies the name of the secret you created in the previous step.
--

. Verify that a new revision of the Kubernetes API server rolls out by checking the operator status:
+
[source,terminal]
----
$ oc get clusteroperators kube-apiserver
----
+
[NOTE]
====
The `PROGRESSING` status column will change to `True` while the API server operator deploys the new pod revision configured with your custom certificate. Do not interrupt the process or apply additional configuration updates while the rollout is underway. Continue only after the status returns to `False` and `AVAILABLE` reads `True`.
====
