diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-aws.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-aws.adoc index ec6de219e83a..d6be0b7539ad 100644 --- a/hosted_control_planes/hcp-deploy/hcp-deploy-aws.adoc +++ b/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-dns.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] diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc index f64f8d3b15cc..5ca59385ec81 100644 --- a/hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc +++ b/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-dns.adoc[leveloffset=+2] + include::modules/hcp-bm-hc.adoc[leveloffset=+1] [role="_additional-resources"] diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc index 40bcbacdddcf..5593e0fa7075 100644 --- a/hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc +++ b/hosted_control_planes/hcp-deploy/hcp-deploy-ibm-power.adoc @@ -35,6 +35,7 @@ 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-dns.adoc[leveloffset=+2] include::modules/hcp-bm-hc.adoc[leveloffset=+1] diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc index 8041837ae326..d4403f9f244f 100644 --- a/hosted_control_planes/hcp-deploy/hcp-deploy-ibmz.adoc +++ b/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-dns.adoc[leveloffset=+2] + include::modules/hcp-bm-hc.adoc[leveloffset=+1] [role="_additional-resources"] diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-non-bm.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-non-bm.adoc index 74dbe8fc4adf..8f5393e75435 100644 --- a/hosted_control_planes/hcp-deploy/hcp-deploy-non-bm.adoc +++ b/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-dns.adoc[leveloffset=+2] + include::modules/hcp-non-bm-hc.adoc[leveloffset=+1] [role="_additional-resources"] diff --git a/hosted_control_planes/hcp-deploy/hcp-deploy-virt.adoc b/hosted_control_planes/hcp-deploy/hcp-deploy-virt.adoc index bb14330bdf72..82fea49731fd 100644 --- a/hosted_control_planes/hcp-deploy/hcp-deploy-virt.adoc +++ b/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-dns.adoc[leveloffset=+2] [id="hcp-virt-ingress-dns-custom"] == Customizing ingress and DNS behavior diff --git a/hosted_control_planes/hcp-manage/hcp-manage-aws.adoc b/hosted_control_planes/hcp-manage/hcp-manage-aws.adoc index 6f2d04d4035e..84fcdb895e11 100644 --- a/hosted_control_planes/hcp-manage/hcp-manage-aws.adoc +++ b/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] \ No newline at end of file diff --git a/modules/hcp-custom-dns.adoc b/modules/hcp-custom-dns.adoc new file mode 100644 index 000000000000..0d0ec294d4ba --- /dev/null +++ b/modules/hcp-custom-dns.adoc @@ -0,0 +1,60 @@ +// 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-dns_{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 + +You can define a DNS name either during your initial setup or during day-2 operations, by entering a domain name in the `kubeAPIServerDNSName` field of a `HostedCluster` object. + +.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 and specify which certificate to use, as shown in the following example: ++ +[source,yaml] +---- +#... +spec: + configuration: + apiServer: + servingCerts: + namedCertificates: + - names: + - xxx.example.com + - yyy.example.com + servingCertificate: + name: + kubeAPIServerDNSName: # <1> +---- ++ +<1> The value for the `kubeAPIServerDNSName` field must be a valid, addressable domain. + +After you define the `kubeAPIServerDNSName` field and specify the certificate, 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 `-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 receives the changes from the HyperShift Operator and deletes the corresponding fields. +==== + +If you remove the `kubeAPIServerDNSName` field from the specification for the `HostedCluster` object, all newly generated secrets and the `CustomKubeconfig` reference are removed from the cluster and from the `status` field. \ No newline at end of file