Skip to content

Commit 1619bb1

Browse files
lahinsonlahinson
authored
Merge pull request #97408 from lahinson/osdocs-12845-hcp-custom-kube-api-server
[OSDOCS-12845]: Adding HCP certs assembly and Kube API server module
2 parents b09ec9c + 7943df2 commit 1619bb1

File tree

5 files changed

+152
-6
lines changed

5 files changed

+152
-6
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2550,6 +2550,8 @@ Topics:
25502550
File: disconnected-install-ibmz-hcp
25512551
- Name: Monitoring user workload in a disconnected environment
25522552
File: hcp-dc-monitor
2553+
- Name: Configuring certificates for hosted control planes
2554+
File: hcp-certificates
25532555
- Name: Updating hosted control planes
25542556
File: hcp-updating
25552557
- Name: High availability for hosted control planes

‎hosted_control_planes/hcp-certificates.adoc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="hcp-certificates"]
3+
include::_attributes/common-attributes.adoc[]
4+
= Configuring certificates for {hcp}
5+
:context: hcp-certificates
6+
7+
toc::[]
8+
9+
With {hcp}, the steps to configure certificates differ from those of standalone {product-title}.
10+
11+
include::modules/hcp-custom-cert.adoc[leveloffset=+1]
12+
13+
include::modules/hcp-kube-api-server-cert.adoc[leveloffset=+1]
14+
15+
include::modules/hcp-ts-custom-dns.adoc[leveloffset=+1]
16+
17+
//include::modules/hcp-ingress-cert.adoc[leveloffset=+1]

‎modules/hcp-custom-cert.adoc‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
// Module included in the following assemblies:
22
//
3-
// * hosted-control-planes/hcp-deploy/hcp-deploy-aws.adoc
4-
// * hosted-control-planes/hcp-deploy/hcp-deploy-bm.adoc
5-
// * hosted-control-planes/hcp-deploy/hcp-deploy-non-bm.adoc
6-
// * hosted-control-planes/hcp-deploy/hcp-deploy-virt.adoc
3+
// * hosted-control-planes/hcp-certificates.adoc
74

85
:_mod-docs-content-type: PROCEDURE
96
[id="hcp-custom-cert_{context}"]
@@ -20,7 +17,7 @@ You can configure a custom certificate during either day-1 or day-2 operations.
2017
** `tls.crt`: The certificate
2118
** `tls.key`: The private key
2219
23-
* 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.
20+
* 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 conflicts 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.
2421
2522
* The certificate must be valid for the external API endpoint.
2623
@@ -66,6 +63,6 @@ $ oc apply -f <hosted_cluster_config>.yaml
6663

6764
* Check the API server pods to ensure that the new certificate is mounted.
6865
69-
* Test the conncetion to the API server by using the custom domain name.
66+
* Test the connection to the API server by using the custom domain name.
7067
7168
* Verify the certificate details in your browser or by using tools such as `openssl`.

‎modules/hcp-kube-api-server-cert.adoc‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted-control-planes/hcp-certificates.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-kube-api-server-cert_{context}"]
7+
= Configuring the Kubernetes API server for a hosted cluster
8+
9+
If you want to customize the Kubernetes API server for your hosted cluster, complete the following steps.
10+
11+
.Prerequisites
12+
13+
* You have a running hosted cluster.
14+
15+
* You have access to modify the `HostedCluster` resource.
16+
17+
* You have a custom DNS domain to use for the Kubernetes API server.
18+
+
19+
** The custom DNS domain must be properly configured and resolvable.
20+
** The DNS domain must have valid TLS certificates configured.
21+
** Network access to the domain must be properly configured in your environment.
22+
** The custom DNS domain must be unique across your hosted clusters.
23+
24+
* You have a configured custom certificate. For more information, see "Configuring a custom API server certificate in a hosted cluster".
25+
26+
.Procedure
27+
28+
. In your provider platform, configure the DNS record so that the `kubeAPIServerDNSName` URL points to the IP address that the Kubernetes API server is being exposed to. The DNS record must be properly configured and resolvable from your cluster.
29+
+
30+
.Example command to configure the DNS record
31+
[source,terminal]
32+
----
33+
$ dig + short kubeAPIServerDNSName
34+
----
35+
36+
. In your `HostedCluster` specification, modify the `kubeAPIServerDNSName` field, as shown in the following example:
37+
+
38+
[source,yaml]
39+
----
40+
apiVersion: hypershift.openshift.io/v1beta1
41+
kind: HostedCluster
42+
metadata:
43+
name: <hosted_cluster_name>
44+
namespace: <hosted_cluster_namespace>
45+
spec:
46+
configuration:
47+
apiServer:
48+
servingCerts:
49+
namedCertificates:
50+
- names: <1>
51+
- api-custom-cert-sample-hosted.sample-hosted.example.com
52+
servingCertificate: <2>
53+
name: sample-hosted-kas-custom-cert
54+
kubeAPIServerDNSName: api-custom-cert-sample-hosted.sample-hosted.example.com <3>
55+
# ...
56+
----
57+
<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.
58+
<2> The name of the secret that contains the custom certificate.
59+
<3> This field accepts a URI that will be used as the API server endpoint.
60+
61+
. Apply the configuration by entering the following command:
62+
+
63+
[source,terminal]
64+
----
65+
$ oc -f <hosted_cluster_spec>.yaml
66+
----
67+
+
68+
After the configuration is applied, the HyperShift Operator generates a new `kubeconfig` secret that points to your custom DNS domain.
69+
70+
. Retrieve the `kubeconfig` secret by using the CLI or the console.
71+
+
72+
.. To retrieve the secret by using the CLI, enter the following command:
73+
+
74+
[source,terminal]
75+
----
76+
$ kubectl get secret <hosted_cluster_name>-custom-admin-kubeconfig \
77+
-n <cluster_namespace> \
78+
-o jsonpath='{.data.kubeconfig}' | base64 -d
79+
----
80+
81+
+
82+
.. To retrieve the secret by using the console, go to your hosted cluster and click **Download Kubeconfig**.
83+
+
84+
[NOTE]
85+
====
86+
You cannot consume the new `kubeconfig` secret by using the **show login command** option in the console.
87+
====

‎modules/hcp-ts-custom-dns.adoc‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted-control-planes/hcp-certificates.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-ts-custom-dns_{context}"]
7+
= Troubleshooting accessing a hosted cluster by using a custom DNS
8+
9+
If you encounter issues when you access a hosted cluster by using a custom DNS, complete the following steps.
10+
11+
.Procedure
12+
13+
. Verify that the DNS record is properly configured and resolved.
14+
15+
. Check that the TLS certificates for the custom domain are valid, verifying that the SAN is correct for your domain, by entering the following command:
16+
+
17+
[source,terminal]
18+
----
19+
$ oc get secret \
20+
-n clusters <serving_certificate_name> \
21+
-o jsonpath='{.data.tls\.crt}' | base64 \
22+
-d |openssl x509 -text -noout -
23+
----
24+
25+
. Ensure that network connectivity to the custom domain is working.
26+
27+
. In the `HostedCluster` resource, verify that the status shows the correct custom `kubeconfig` information, as shown in the following example:
28+
+
29+
.Example `HostedCluster` status
30+
[source,yaml]
31+
----
32+
status:
33+
customKubeconfig:
34+
name: sample-hosted-custom-admin-kubeconfig
35+
----
36+
37+
. Check the `kube-apiserver` logs in the `HostedControlPlane` namespace by entering the following command:
38+
+
39+
[source,terminal]
40+
----
41+
$ oc logs -n <hosted_control_plane_namespace> \
42+
-l app=kube-apiserver -f -c kube-apiserver
43+
----

0 commit comments

Comments
 (0)