[OSDOCS-14647]: Config custom API server cert for a hosted cluster

Author: lahinson

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

@@ -52,19 +52,24 @@ include::modules/hcp-aws-deploy-hc.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
-
 * xref:../../hosted_control_planes/hcp-deploy/hcp-deploy-aws.adoc#hcp-enable-arm-amd_hcp-deploy-aws[Running hosted clusters on an ARM64 architecture]
 
+include::modules/hcp-access-hc-aws.adoc[leveloffset=+2]
+
 include::modules/hcp-access-pub-hc-aws.adoc[leveloffset=+2]
 
 include::modules/hcp-access-pub-hc-aws-cli.adoc[leveloffset=+2]
 
+include::modules/hcp-custom-cert.adoc[leveloffset=+1]
+
 include::modules/hc-create-aws-multi-zones.adoc[leveloffset=+1]
 
 include::modules/hcp-create-hc-multi-zone-aws-creds.adoc[leveloffset=+2]
 
 include::modules/hcp-enable-arm-amd.adoc[leveloffset=+1]
+
 include::modules/hcp-create-hc-arm64-aws.adoc[leveloffset=+2]
+
 include::modules/hcp-create-np-arm64-aws.adoc[leveloffset=+2]
 
 [role="_additional-resources"]

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

@@ -19,52 +19,70 @@ The {mce-short} supports only the default `local-cluster`, which is a hub cluste
 
 A _hosted cluster_ is an {product-title} cluster with its API endpoint and control plane that are hosted on the management cluster. The hosted cluster includes the control plane and its corresponding data plane. You can use the {mce-short} console or the hosted control plane command-line interface, `hcp`, to create a hosted cluster.
 
-The hosted cluster is automatically imported as a managed cluster. If you want to disable this automatic import feature, see _Disabling the automatic import of hosted clusters into {mce-short}_.
+The hosted cluster is automatically imported as a managed cluster. If you want to disable this automatic import feature, see "Disabling the automatic import of hosted clusters into {mce-short}".
 
 include::modules/hcp-bm-prepare.adoc[leveloffset=+1]
+
 include::modules/hcp-bm-prereqs.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
+
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#advanced-config-engine[Advanced configuration]
+
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#enable-cim[Enabling the central infrastructure management service]
 
 include::modules/hcp-bm-firewall-port-svc-reqs.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
+
 * xref:../../networking/configuring_network_settings/enable-cluster-wide-proxy.adoc#enable-cluster-wide-proxy[Configuring the cluster-wide proxy]
 
 include::modules/hcp-bm-infra-reqs.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
+
 * xref:../../etcd/etcd-practices.adoc#recommended-etcd-practices[Recommended etcd practices]
+
 * xref:../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc[Persistent storage using {lvms}]
+
 * xref:../../hosted_control_planes/hcp-import.adoc#hcp-import-disable_hcp-import[Disabling the automatic import of hosted clusters into {mce-short}]
+
 * xref:../../hosted_control_planes/hcp-prepare/hcp-enable-disable.adoc[Enabling or disabling the {hcp} feature]
+
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/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"]
 .Additional resources
+
 * xref:../../hosted_control_planes/hcp-import.adoc[Manually importing a hosted cluster]
 
 include::modules/hcp-bm-hc-console.adoc[leveloffset=+2]
 
 .Next steps
+
 * To access the web console, see xref:../../web_console/web-console.adoc#web-console-overview[Accessing the web console].
 
 include::modules/hcp-bm-hc-mirror.adoc[leveloffset=+2]
 
 .Next steps
+
 * To create credentials that you can reuse when you create a hosted cluster with the console, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#creating-a-credential-for-an-on-premises-environment[Creating a credential for an on-premises environment].
+
 * To access a hosted cluster, see xref:../../hosted_control_planes/hcp-manage/hcp-manage-bm.adoc#hcp-bm-access_hcp-manage-bm[Accessing the hosted cluster].
+
 * To add hosts to the host inventory by using the Discovery Image, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#add-host-host-inventory[Adding hosts to the host inventory by using the Discovery Image].
+
 * To extract the {product-title} release image digest, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#configure-hosted-disconnected-digest-image[Extracting the {product-title} release image digest].
 
 include::modules/hcp-bm-verify.adoc[leveloffset=+1]
+
+include::modules/hcp-custom-cert.adoc[leveloffset=+1]

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

@@ -25,6 +25,7 @@ A _hosted cluster_ is an {product-title} cluster with its API endpoint and contr
 The hosted cluster is automatically imported as a managed cluster. If you want to disable this automatic import feature, see "Disabling the automatic import of hosted clusters into {mce-short}".
 
 include::modules/hcp-non-bm-prepare.adoc[leveloffset=+1]
+
 include::modules/hcp-non-bm-prereqs.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
@@ -35,6 +36,7 @@ include::modules/hcp-non-bm-prereqs.adoc[leveloffset=+2]
 * link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#enable-cim[Enabling the central infrastructure management service]
 
 include::modules/hcp-non-bm-firewall-port-svc-reqs.adoc[leveloffset=+2]
+
 include::modules/hcp-non-bm-infra-reqs.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
@@ -53,6 +55,7 @@ include::modules/hcp-non-bm-infra-reqs.adoc[leveloffset=+2]
 * link:4/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]
@@ -81,3 +84,5 @@ include::modules/hcp-bm-hc-mirror.adoc[leveloffset=+2]
 * To extract the {product-title} release image digest, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.14/html/clusters/cluster_mce_overview#configure-hosted-disconnected-digest-image[Extracting the {product-title} release image digest].
 
 include::modules/hcp-non-bm-verify.adoc[leveloffset=+1]
+
+include::modules/hcp-custom-cert.adoc[leveloffset=+1]

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

@@ -99,3 +99,5 @@ include::modules/hcp-virt-add-node.adoc[leveloffset=+2]
 * To scale down the data plane to zero, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.15/html/hosted_control_planes/troubleshooting-hosted-control-planes#scale-down-data-plane_hcp-troubleshooting[Scaling down the data plane to zero].
 
 include::modules/hcp-virt-verify-hc.adoc[leveloffset=+1]
+
+include::modules/hcp-custom-cert.adoc[leveloffset=+1]

modules/hcp-access-hc-aws.adoc

@@ -3,7 +3,7 @@
 // * hosted-control-planes/hcp-deploy/hcp-deploy-aws.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="hcp-create-private-hc-aws_{context}"]
+[id="hcp-access-hc-aws_{context}"]
 = Accessing a hosted cluster on {aws-short}
 
 You can access the hosted cluster by getting the `kubeconfig` file and the `kubeadmin` credentials directly from resources.

modules/hcp-aws-create-secret-s3.adoc

@@ -14,20 +14,28 @@ Before you can create and manage hosted clusters on {aws-first}, you must create
 +
 [source,terminal]
 ----
-$ aws s3api create-bucket --bucket <bucket_name> \// <1>
-  --create-bucket-configuration LocationConstraint=<region> \// <2>
-  --region <region> <2>
+$ aws s3api create-bucket --bucket <bucket_name> \
+  --create-bucket-configuration LocationConstraint=<region> \
+  --region <region>
 ----
 +
-<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
-<2> To create the bucket in a region other than the `us-east-1` region, include this line and replace `<region>` with the region you want to use. To create a bucket in the `us-east-1` region, omit this line.
+where:
++
+--
+<bucket_name>:: Is the name of the S3 bucket you are creating.
+<region>:: To create the bucket in a region other than the `us-east-1` region, include this line and replace `<region>` with the region you want to use. To create a bucket in the `us-east-1` region, omit this line.
+--
 +
 [source,terminal]
 ----
-$ aws s3api delete-public-access-block --bucket <bucket_name> <1>
+$ aws s3api delete-public-access-block --bucket <bucket_name>
 ----
 +
-<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
+where:
++
+--
+<bucket_name>:: Is the name of the S3 bucket you are creating.
+--
 +
 [source,terminal]
 ----
@@ -38,21 +46,29 @@ $ echo '{
             "Effect": "Allow",
             "Principal": "*",
             "Action": "s3:GetObject",
-            "Resource": "arn:aws:s3:::<bucket_name>/*" <1>
+            "Resource": "arn:aws:s3:::<bucket_name>/*"
         }
     ]
 }' | envsubst > policy.json
 ----
 +
-<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
+where:
++
+--
+<bucket_name>:: Is the name of the S3 bucket you are creating.
+--
 +
 [source,terminal]
 ----
-$ aws s3api put-bucket-policy --bucket <bucket_name> \// <1>
+$ aws s3api put-bucket-policy --bucket <bucket_name> \
   --policy file://policy.json
 ----
 +
-<1> Replace `<bucket_name>` with the name of the S3 bucket you are creating.
+where:
++
+--
+<bucket_name>:: Is the name of the S3 bucket you are creating.
+--
 +
 [NOTE]
 ====

modules/hcp-custom-cert.adoc

@@ -0,0 +1,76 @@
+// 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-non-bm.adoc
+// * hosted-control-planes/hcp-deploy/hcp-deploy-virt.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-custom-cert_{context}"]
+= Configuring a custom API server certificate in a hosted cluster
+
+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.
+
+.Prerequisites
+
+* You created a Kubernetes secret that contains your custom certificate in the management cluster. The secret contains the following keys:
+
+ ** `tls.crt`: The certificate
+ ** `tls.key`: They private key
+
+* If your `HostedCluster` configuration includes a service publishing strategy that uses a load balancer, ensure that the Subject Alternative Names (SANs) of the certificate do not conflict with the internal API endpoint (`api-int`). The internal API endpoint is automatically created and managed by your platform. If you use the same hostname in both the custom certificate and the internal API endpoint, routing conflictcs can occur. The only exception to this rule is when you use {aws-short} as the provider with either Private or PublicAndPrivate configurations. In those cases, the SAN conflict is managed by the platform.
+
+* The certificate must be valid for the external API endpoint.
+
+* The validity period of the certificate aligns with your cluster's expected life cycle.
+
+.Procedure
+
+. Create a secret with your custom certificate by entering the following command:
++
+[source,terminal]
+----
+$ oc create secret tls sample-hosted-kas-custom-cert \
+  --cert=path/to/cert.crt \
+  --key=path/to/key.key \
+  -n <namespace>
+----
+
+. Update your `HostedCluster` configuration with the custom certificate details, as shown in the following example:
++
+[source,yaml]
+----
+spec:
+  configuration:
+    apiServer:
+      servingCerts:
+        namedCertificates:
+        - names:
+          - api-custom-cert-sample-hosted.sample-hosted.example.com
+          servingCertificate:
+            name: sample-hosted-kas-custom-cert
+----
++
+where:
++
+--
+names:: The list of DNS names that the certificate is valid for.
+servingCertificate.name:: The name of the secret that contains the custom certificate.
+--
+
+. Apply the changes to your `HostedCluster` configuration by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f <hosted_cluster_config>.yaml
+----
+
+.Verification
+
+* Check the API server pods to ensure that the new certificate is mounted.
+
+* Test the conncetion to the API server by using the custom domain name.
+
+* Verify the certificate details in your browser or by using tools such as `openssl`.

security/certificates/api-server.adoc

@@ -13,7 +13,7 @@ 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.
+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 xref:../hosted_control_planes/hcp-deploy/hcp-deploy-bm.adoc#hcp-custom-cert_hcp-deploy-bm[Configuring a custom API server certificate in a hosted cluster].
 ====
 
 include::modules/customize-certificates-api-add-named.adoc[leveloffset=+1]