From bdc346a8120c973a57355629ba853419dd727d2e Mon Sep 17 00:00:00 2001 From: Laura Hinson Date: Fri, 10 Jul 2026 16:29:53 -0400 Subject: [PATCH] [OSDOCS-20640]: CQA: HCP certificates --- hosted_control_planes/hcp-certificates.adoc | 6 ++++-- modules/hcp-custom-cert.adoc | 16 +++++++++------- modules/hcp-kube-api-server-cert.adoc | 18 ++++++++++-------- modules/hcp-ts-custom-dns.adoc | 5 +++-- 4 files changed, 26 insertions(+), 19 deletions(-) diff --git a/hosted_control_planes/hcp-certificates.adoc b/hosted_control_planes/hcp-certificates.adoc index cea2e851554b..8d0817c7c6fa 100644 --- a/hosted_control_planes/hcp-certificates.adoc +++ b/hosted_control_planes/hcp-certificates.adoc @@ -1,13 +1,15 @@ :_mod-docs-content-type: ASSEMBLY -[id="hcp-certificates"] include::_attributes/common-attributes.adoc[] +[id="hcp-certificates"] = Configuring certificates for {hcp} :context: hcp-certificates toc::[] [role="_abstract"] -To establish secure and encrypted communication between your clients and the hosted control plane, you must configure a server certificate for your hosted cluster. With {hcp}, the steps to configure certificates differ from those of standalone {product-title}. +To establish secure and encrypted communication between your clients and the hosted control plane, you must configure a server certificate for your hosted cluster. + +With {hcp}, the steps to configure certificates differ from those of standalone {product-title}. include::modules/hcp-custom-cert.adoc[leveloffset=+1] diff --git a/modules/hcp-custom-cert.adoc b/modules/hcp-custom-cert.adoc index dcfea0b49946..4b7ca0fd7057 100644 --- a/modules/hcp-custom-cert.adoc +++ b/modules/hcp-custom-cert.adoc @@ -6,9 +6,10 @@ [id="hcp-custom-cert_{context}"] = Configuring a custom API server certificate in a hosted cluster +[role="_abstract"] To configure a custom certificate for the API server, specify the certificate details in the `spec.configuration.apiServer` section of your `HostedCluster` configuration. -You can configure a custom certificate during either day-1 or day-2 operations. However, because the service publishing strategy is immutable after you set it during hosted cluster creation, you must know what the hostname is for the Kubernetes API server that you plan to configure. +You can configure a custom certificate during either Day 1 or Day 2 operations. However, because the service publishing strategy is immutable after you set it during hosted cluster creation, you must know what the hostname is for the Kubernetes API server that you plan to configure. .Prerequisites @@ -17,9 +18,9 @@ You can configure a custom certificate during either day-1 or day-2 operations. ** `tls.crt`: The certificate ** `tls.key`: The private key -* If your `HostedCluster` configuration includes custom serving certificates via the `spec.configuration.apiServer.servingCerts.namedCertificates` specification, ensure that the Subject Alternative Names (SANs) of the certificate do not conflict with the external API server address. For example, depending on the hostname pattern used in your environment, the address might be in the following format: `api..`. +* If your `HostedCluster` configuration includes custom serving certificates via the `spec.configuration.apiServer.servingCerts.namedCertificates` specification, ensure that the Subject Alternative Names (SANs) of the certificate do not conflict with the external API server address. For example, depending on the hostname pattern used in your environment, the address might be in the following format: `api..`. + -The `HostedCluster` resource automatically includes the external API address in the default Kubernetes API server certificate SANs. If the same hostname is in both the custom certificate and the auto-generated Kubernetes API server certificate, the configuration is rejected to prevent TLS serving ambiguity. +The `HostedCluster` resource automatically includes the external API address in the default Kubernetes API server certificate SANs. If the same hostname is in both the custom certificate and the automatically generated Kubernetes API server certificate, the configuration is rejected to prevent TLS serving ambiguity. + This validation applies to all service publishing strategies, including `LoadBalancer` and `NodePort`. The only exception is when you use {aws-first} as the provider with `Private` or `PublicAndPrivate` endpoint access configurations, where the platform manages the SAN conflict. @@ -48,13 +49,14 @@ spec: apiServer: servingCerts: namedCertificates: - - names: <1> + - names: - api-custom-cert-sample-hosted.sample-hosted.example.com - servingCertificate: <2> + servingCertificate: name: sample-hosted-kas-custom-cert ---- -<1> The list of DNS names that the certificate is valid for. -<2> The name of the secret that contains the custom certificate. ++ +* `spec.configuration.apiServer.servingCerts.namedCertificates.names` specifies the list of DNS names that the certificate is valid for. +* `spec.configuration.apiServer.servingCerts.namedCertificates.servingCertificate` specifies the name of the secret that contains the custom certificate. . Apply the changes to your `HostedCluster` configuration by entering the following command: + diff --git a/modules/hcp-kube-api-server-cert.adoc b/modules/hcp-kube-api-server-cert.adoc index 9130b4a1bf39..8b979aef14ed 100644 --- a/modules/hcp-kube-api-server-cert.adoc +++ b/modules/hcp-kube-api-server-cert.adoc @@ -6,7 +6,8 @@ [id="hcp-kube-api-server-cert_{context}"] = Configuring the Kubernetes API server for a hosted cluster -If you want to customize the Kubernetes API server for your hosted cluster, complete the following steps. +[role="_abstract"] +You can customize the Kubernetes API server for your hosted cluster. .Prerequisites @@ -47,16 +48,17 @@ spec: apiServer: servingCerts: namedCertificates: - - names: <1> + - names: - api-custom-cert-sample-hosted.sample-hosted.example.com - servingCertificate: <2> + servingCertificate: name: sample-hosted-kas-custom-cert - kubeAPIServerDNSName: api-custom-cert-sample-hosted.sample-hosted.example.com <3> + kubeAPIServerDNSName: api-custom-cert-sample-hosted.sample-hosted.example.com # ... ---- -<1> The list of DNS names that the certificate is valid for. The names listed in this field cannot be the same as the names specified in the `spec.servicePublishingStrategy.*hostname` field. -<2> The name of the secret that contains the custom certificate. -<3> This field accepts a URI that will be used as the API server endpoint. ++ +* `spec.configuration.apiServer.servingCerts.namedCertificates.names` specifies the list of DNS names that the certificate is valid for. The names listed in this field cannot be the same as the names specified in the `spec.servicePublishingStrategy.*hostname` field. +* `spec.configuration.apiServer.servingCerts.namedCertificates.servingCertificate` specifies the name of the secret that contains the custom certificate. +* `spec.kubeAPIServerDNSName` accepts a URI that will be used as the API server endpoint. . Apply the configuration by entering the following command: + @@ -84,4 +86,4 @@ $ kubectl get secret -custom-admin-kubeconfig \ [NOTE] ==== You cannot consume the new `kubeconfig` secret by using the **show login command** option in the console. -==== \ No newline at end of file +==== diff --git a/modules/hcp-ts-custom-dns.adoc b/modules/hcp-ts-custom-dns.adoc index e274bafa847d..0b8650f68251 100644 --- a/modules/hcp-ts-custom-dns.adoc +++ b/modules/hcp-ts-custom-dns.adoc @@ -6,7 +6,8 @@ [id="hcp-ts-custom-dns_{context}"] = Troubleshooting accessing a hosted cluster by using a custom DNS -If you encounter issues when you access a hosted cluster by using a custom DNS, complete the following steps. +[role="_abstract"] +If you encounter an issue when you access a hosted cluster by using a custom DNS, you can determine the root cause so that you can resolve the issue. .Procedure @@ -40,4 +41,4 @@ status: ---- $ oc logs -n \ -l app=kube-apiserver -f -c kube-apiserver ----- \ No newline at end of file +----