[OSDOCS-14539]: Custom KubeAPI name

Author: lahinson

hosted_control_planes/hcp-deploy/hcp-deploy-aws.adoc

@@ -46,6 +46,8 @@ include::modules/hcp-aws-create-dns-hosted-zone.adoc[leveloffset=+2]
 
 include::modules/hcp-aws-hc-ext-dns.adoc[leveloffset=+2]
 
+include::modules/hcp-custom-kubeapi.adoc[leveloffset=+2]
+
 include::modules/hcp-aws-deploy-hc.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -72,9 +74,8 @@ include::modules/hcp-create-np-arm64-aws.adoc[leveloffset=+2]
 
 include::modules/hcp-create-private-hc-aws.adoc[leveloffset=+1]
 
-[role="_additional-resources"]
-.Additional resources
-
+//[role="_additional-resources"]
+//.Additional resources
 //Identity and Access Management (IAM) permissions
 
 include::modules/hcp-access-priv-mgmt-aws.adoc[leveloffset=+2]

hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc

@@ -46,6 +46,8 @@ include::modules/hcp-bm-infra-reqs.adoc[leveloffset=+2]
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#ansible-config-hosted-cluster[Configuring Ansible Automation Platform jobs to run on hosted clusters]
 
 include::modules/hcp-bm-dns.adoc[leveloffset=+1]
+include::modules/hcp-custom-kubeapi.adoc[leveloffset=+2]
+
 include::modules/hcp-bm-hc.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc

@@ -35,5 +35,6 @@ include::modules/hcp-ibm-power-prereqs.adoc[leveloffset=+1]
 include::modules/hcp-ibm-power-infra-reqs.adoc[leveloffset=+1]
 
 include::modules/hcp-ibm-power-dns.adoc[leveloffset=+1]
+include::modules/hcp-custom-kubeapi.adoc[leveloffset=+2]
 
 include::modules/hcp-bm-hc.adoc[leveloffset=+1]

hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc

@@ -41,6 +41,8 @@ include::modules/hcp-ibm-z-infra-reqs.adoc[leveloffset=+1]
 * xref:../../hosted_control_planes/hcp-prepare/hcp-enable-disable.adoc[Enabling or disabling the {hcp} feature]
 
 include::modules/hcp-ibm-z-dns.adoc[leveloffset=+1]
+include::modules/hcp-custom-kubeapi.adoc[leveloffset=+2]
+
 include::modules/hcp-bm-hc.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

hosted_control_planes/hcp-deploy/hcp-deploy-non-bm.adoc

@@ -53,6 +53,8 @@ include::modules/hcp-non-bm-infra-reqs.adoc[leveloffset=+2]
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.13/html/clusters/cluster_mce_overview#ansible-config-hosted-cluster[Configuring Ansible Automation Platform jobs to run on hosted clusters]
 
 include::modules/hcp-non-bm-dns.adoc[leveloffset=+1]
+include::modules/hcp-custom-kubeapi.adoc[leveloffset=+2]
+
 include::modules/hcp-non-bm-hc.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

hosted_control_planes/hcp-deploy/hcp-deploy-virt.adoc

@@ -62,6 +62,7 @@ include::modules/hcp-virt-create-hc-console.adoc[leveloffset=+2]
 * To access the hosted cluster, see xref:../../hosted_control_planes/hcp-manage/hcp-manage-virt.adoc#hcp-virt-access_hcp-manage-virt[Accessing the hosted cluster].
 
 include::modules/hcp-virt-ingress-dns.adoc[leveloffset=+1]
+include::modules/hcp-custom-kubeapi.adoc[leveloffset=+2]
 
 [id="hcp-virt-ingress-dns-custom"]
 == Customizing ingress and DNS behavior

hosted_control_planes/hcp-manage/hcp-manage-aws.adoc

@@ -35,4 +35,4 @@ include::modules/hcp-managed-aws-hc-separate.adoc[leveloffset=+2]
 
 include::modules/hcp-migrate-aws-single-to-multiarch.adoc[leveloffset=+1]
 
-include::modules/hcp-migrate-aws-multiarch-nodepools.adoc[leveloffset=+1]
+include::modules/hcp-migrate-aws-multiarch-nodepools.adoc[leveloffset=+1]

modules/hcp-custom-kubeapi.adoc

@@ -0,0 +1,72 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-deploy/hcp-deploy-aws.adoc
+// * hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc
+// * hosted_control_planes/hcp-deploy/hcp-deploy-virt.adoc
+// * hosted_control_planes/hcp-deploy/hcp-deploy-non-bm.adoc
+// * hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc
+// * hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-custom-kubeapi_{context}"]
+= Defining a custom DNS name
+
+As a cluster administrator, you can create a hosted cluster with an external API DNS name that is different from the internal endpoint that is used for node bootstraps and control plane communication. You might want to define a different DNS name for the following reasons:
+
+* To replace the user-facing TLS certificate with one from a public CA without breaking the control plane functions that are bound to the internal root CA
+* To support split-horizon DNS and NAT scenarios
+* To ensure a similar experience to standalone control planes, where you can use functions such as the "Show Login Command" function with the correct `kubeconfig` and DNS configuration
+
+In order to define a DNS name, you insert a domain name in the `kubeAPIServerDNSName` field of a `HostedCluster` object. You can define the name either during your initial setup or during day-2 operations.
+
+.Prerequisites
+
+* You have a valid TLS certificate that covers the DNS name that you will set in the `kubeAPIServerDNSName` field.
+* Your DNS name is a resolvable URI that is reachable and pointing to the right address.
+
+.Procedure
+
+. In the specification for the `HostedCluster` object, add the `kubeAPIServerDNSName` field and the address for the domain.
++
+[source,yaml]
+----
+apiVersion: hypershift.openshift.io/v1beta1
+kind: HostedCluster
+
+#...
+
+kubeAPIServerDNSName: <your_custom_address> <1>
+----
++
+<1> The value for the `kubeAPIServerDNSName` field must be a valid, addressable domain.
+
+. In the `namedCertificates` file of the OpenShift API, specify which certificate to use, as shown in the following example.
++
+.Example `namedCertificates` file
++
+[source,yaml]
+----
+spec:
+  configuration:
+    apiServer:
+      servingCerts:
+        namedCertificates:
+        - names:
+          - xxx.example.com
+          - yyy.example.com
+          servingCertificate:
+            name: my-serving-certificate 
+----
+
+After the `kubeAPIServerDNSName` field is defined and the certificate is specified, the Control Plane Operator controllers create a `kubeconfig` file named `custom-admin-kubeconfig`, which is stored in the `HostedControlPlane` namespace. The certificates are generated from the root CA, and the `HostedControlPlane` namespace manages their expiration and renewal.
+
+The Control Plane Operator reports a new `kubeconfig` file named `CustomKubeconfig` in the `HostedControlPlane` namespace. That file uses the new server that is defined in the `kubeAPIServerDNSName` field.
+
+The custom `kubeconfig` file is referenced in the `HostedCluster` object in the `status` field as `CustomKubeconfig`. The `CustomKubeConfig` field is optional, and can be added only if the `kubeAPIServerDNSName` field is not empty. When the `CustomKubeConfig` field is set, it triggers the generation of a secret named `<hosted_cluster_name>-custom-admin-kubeconfig` in the `HostedCluster` namespace. You can use the secret to access the `HostedCluster` API server. If you remove the `CustomKubeConfig` field during day-2 operations, all related secrets and status references are deleted.
+
+[NOTE]
+====
+This process does not directly affect the data plane, so no rollouts are expected to occur. The `HostedControlPlane` namespace will receive the changes from the HyperShift Operator and will delete the corresponding fields.
+====
+
+If you remove the `kubeAPIServerDNSName` field from the specification, all newly generated secrets and the `CustomKubeconfig` reference will be removed from the cluster and from the `status` field.