[OCPBUGS-78486]: Adding OAuth server cert config docs for HCP

hosted_control_planes/hcp-certificates.adoc

@@ -6,12 +6,17 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-With {hcp}, the steps to configure certificates differ from those of standalone {product-title}.  
+[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}.
 
 include::modules/hcp-custom-cert.adoc[leveloffset=+1]
 
 include::modules/hcp-kube-api-server-cert.adoc[leveloffset=+1]
 
+include::modules/hcp-oauth-server-cert-about.adoc[leveloffset=+1]
+
+include::modules/hcp-oauth-server-cert.adoc[leveloffset=+1]
+
 include::modules/hcp-ts-custom-dns.adoc[leveloffset=+1]
 
 //include::modules/hcp-ingress-cert.adoc[leveloffset=+1]

modules/hcp-oauth-server-cert-about.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// * hosted-control-planes/hcp-certificates.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="hcp-oauth-server-cert-about_{context}"]
+= OAuth server certificates for {hcp}
+
+[role="_abstract"]
+In {hcp}, the OAuth server shares its serving certificate configuration with the Kubernetes API server. To configure a custom serving certificate for the OAuth server, you modify the `spec.configuration.apiServer` section in the `HostedCluster` resource.
+
+[IMPORTANT]
+====
+This configuration method deviates from the standard {product-title} behavior. In {product-title}, OAuth certificates are configured separately through the `componentRoute` properties of the Ingress Operator. In {hcp}, the `namedCertificates` configuration in the API server settings applies to both the Kubernetes API server and the OAuth server.
+====
+
+In {hcp}, the Control Plane Operator reads serving certificates through the shared `GetNamedCertificates()` function. Certificates are not configured in an OAuth-specific section of the `HostedCluster` resource. In addition, OAuth server certificates are not provided through an OAuth custom resource definition (CRD) configuration. Instead, {hcp} automatically injects the selected certificates into the OAuth server deployment.
+
+.OAuth certificate differences between {product-title} and {hcp}
+[cols="3",options="header"]
+|===
+|Area |{product-title} |{hcp}
+
+|Certificate source
+|Ingress Operator generates and maps certificates through component routes
+|OAuth uses `apiServer.servingCerts.namedCertificates` settings
+
+|Certificate selection
+|Based on ingress-managed routes
+|Based on host name match in `namedCertificates` property
+
+|User responsibility
+|No need to manually provide OAuth certificates
+|User must supply certificates if custom behavior is needed
+
+|Code path
+|Ingress Operator manages the OAuth route
+|Control Plane Operator manages the OAuth server container runtime arguments
+|===

modules/hcp-oauth-server-cert.adoc

@@ -0,0 +1,193 @@
+// Module included in the following assemblies:
+//
+// * hosted-control-planes/hcp-certificates.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-oauth-server-cert_{context}"]
+= Configuring OAuth server certificates for a hosted cluster
+
+[role="_abstract"]
+If you want to use certificates from a trusted certificate authority (CA) to access a hosted cluster, you can configure OAuth server certificates.
+
+.Prerequisites
+
+* You have a running hosted cluster.
+
+* You have `cluster-admin` access to the management cluster.
+
+* You have access to modify the `HostedCluster` resource.
+
+* You have a TLS secret that contains your signed certificate and private key in the hosted cluster namespace with the following keys:
++
+** `tls.crt`
+** `tls.key`
+
+.Procedure
+
+. Identify your hosted cluster namespace:
+
+.. Export the namespace where your hosted cluster is running by entering the following command:
++
+[source,terminal]
+----
+$ export HC_NAMESPACE=<hosted_cluster_namespace>
+----
+
+.. Export the hosted cluster name by entering the following command:
++
+[source,terminal]
+----
+$ export CLUSTER_NAME=<hosted_cluster_name>
+----
+
+. Generate a quick test certificate by entering the following command:
++
+[source,terminal]
+----
+$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout tls.key \
+  -out tls.crt \
+  -subj "/CN=openshift-oauth" \
+  -addext "subjectAltName=DNS:oauth-${HC_NAMESPACE}-${CLUSTER_NAME}.api-custom-cert-sample-hosted.sample-hosted.example.com"
+----
++
+The `api-custom-cert-sample-hosted.sample-hosted.example.com` value is used in the command and throughout the rest of this procedure as an example.
++
+[NOTE]
+====
+This example uses a placeholder hostname. After you discover your OAuth route later in this procedure, you must regenerate this certificate with the correct hostname before you edit the `HostedCluster` resource.
+====
+
+. Confirm that the file exists by entering the following command:
++
+[source,terminal]
+----
+$ ls tls.crt tls.key
+----
+
+. If you have not already created the TLS secret in the hosted cluster namespace, create the secret by entering the following command:
++
+[source,terminal]
+----
+$ oc create secret tls my-oauth-cert-secret \
+  --cert=path/to/tls.crt \
+  --key=path/to/tls.key \
+  -n $HC_NAMESPACE
+----
++
+.Example output
+[source,terminal]
+----
+secret/my-oauth-cert-secret created
+----
++
+[NOTE]
+====
+Although the OAuth server runs in the hosted control plane namespace, the serving certificate must exist in the hosted cluster namespace. Secrets that are created in the hosted control plane namespace are not picked up.
+====
+
+. Discover the correct OAuth route:
+
+.. Use the management cluster `kubconfig` file to enter the following command:
++
+[source,terminal]
+----
+$ oc get routes -n ${HC_NAMESPACE}-${CLUSTER_NAME}
+----
+
+.. If the route name is `oauth`, confirm it by entering the following command:
++
+[source,terminal]
+----
+$ oc get route oauth -n ${HC_NAMESPACE}-${CLUSTER_NAME} -o yaml
+----
+
+.. Prepare to extract the OAuth route host by entering the following command:
++
+[source,terminal]
+----
+OAUTH_HOST=$(oc get route oauth \
+  -n ${HC_NAMESPACE}-${CLUSTER_NAME} \
+  -o jsonpath='{.spec.host}')
+----
+
+.. Extract the OAuth route host by entering the following command:
++
+[source,terminal]
+----
+$ echo "${OAUTH_HOST}"
+----
++
+.Example output
+[source,terminal]
+----
+oauth-${HC_NAMESPACE}-${CLUSTER_NAME}.api-custom-cert-sample-hosted.sample-hosted.example.com
+----
+
+. Edit the `HostedCluster` resource:
+
+.. Open the `HostedCluster` resource for editing by entering the following command:
++
+[source,terminal]
+----
+$ oc edit hostedcluster $CLUSTER_NAME -n $HC_NAMESPACE
+----
+
+.. In the resource, configure the named certificates by adding the `servingCerts.namedCertificates` stanza to the `spec.configuration.apiServer` section:
++
+[source,yaml]
+----
+apiVersion: hypershift.openshift.io/v1beta1
+kind: HostedCluster
+metadata:
+  name: <hosted_cluster_name>
+  namespace: <hosted_cluster_namespace>
+spec:
+  configuration:
+    apiServer:
+      audit:
+        profile: Default
+      servingCerts:
+        namedCertificates:
+        - names:
+          - api-custom-cert-sample-hosted.sample-hosted.example.com
+          servingCertificate:
+            name: my-oauth-cert-secret
+# ...
+----
++
+where:
+
+`spec.configuration.apiServer.servingCerts.namedCertificates.names`:: Specifies the actual host name of your OAuth route.
+`spec.configuration.apiServer.servingCerts.servingCertificate.name`:: Specifies the name of your TLS secret. This secret must exist in the hosted cluster namespace.
+
+.. Save and apply the changes. The Control Plane Operator reconciles the changes, the configuration propagates to the control plane, and the OAuth server begins serving the new certificate.
++
+[IMPORTANT]
+====
+No separate OAuth certificate configuration field exists for a hosted cluster.
+====
+
+.Verification
+
+* Verify the certificate being served by the route by entering the following command:
++
+[source,terminal]
+----
+$ echo | openssl s_client \
+  -connect "${OAUTH_HOST}:443" \
+  -servername "${OAUTH_HOST}" \
+  2>/dev/null \
+  | openssl x509 -noout -subject -issuer -ext subjectAltName
+----
++
+.Example output
+[source,terminal]
+----
+subject=CN=openshift-oauth
+issuer=CN=openshift-oauth
+X509v3 Subject Alternative Name: 
+    DNS:oauth-${HC_NAMESPACE}-${CLUSTER_NAME}.api-custom-cert-sample-hosted.sample-hosted.example.com
+----
++
+The output shows that the OAuth route is serving the custom certificate and the certificate comes from the `my-oauth-cert-secret` secret.