$ oc create secret tls sample-hosted-kas-custom-cert \
--cert=path/to/cert.crt \
--key=path/to/key.key \
-n <hosted_cluster_namespace>
With hosted control planes, the steps to configure certificates differ from those of standalone OKD.
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.
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
: The 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 conflicts can occur. The only exception to this rule is when you use AWS 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.
Create a secret with your custom certificate by entering the following command:
$ oc create secret tls sample-hosted-kas-custom-cert \
--cert=path/to/cert.crt \
--key=path/to/key.key \
-n <hosted_cluster_namespace>
Update your HostedCluster
configuration with the custom certificate details, as shown in the following example:
spec:
configuration:
apiServer:
servingCerts:
namedCertificates:
- names: (1)
- api-custom-cert-sample-hosted.sample-hosted.example.com
servingCertificate: (2)
name: sample-hosted-kas-custom-cert
1 | The list of DNS names that the certificate is valid for. |
2 | The name of the secret that contains the custom certificate. |
Apply the changes to your HostedCluster
configuration by entering the following command:
$ oc apply -f <hosted_cluster_config>.yaml
Check the API server pods to ensure that the new certificate is mounted.
Test the connection to the API server by using the custom domain name.
Verify the certificate details in your browser or by using tools such as openssl
.
If you want to customize the Kubernetes API server for your hosted cluster, complete the following steps.
You have a running hosted cluster.
You have access to modify the HostedCluster
resource.
You have a custom DNS domain to use for the Kubernetes API server.
The custom DNS domain must be properly configured and resolvable.
The DNS domain must have valid TLS certificates configured.
Network access to the domain must be properly configured in your environment.
The custom DNS domain must be unique across your hosted clusters.
You have a configured custom certificate. For more information, see "Configuring a custom API server certificate in a hosted cluster".
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.
$ dig + short kubeAPIServerDNSName
In your HostedCluster
specification, modify the kubeAPIServerDNSName
field, as shown in the following example:
apiVersion: hypershift.openshift.io/v1beta1
kind: HostedCluster
metadata:
name: <hosted_cluster_name>
namespace: <hosted_cluster_namespace>
spec:
configuration:
apiServer:
servingCerts:
namedCertificates:
- names: (1)
- api-custom-cert-sample-hosted.sample-hosted.example.com
servingCertificate: (2)
name: sample-hosted-kas-custom-cert
kubeAPIServerDNSName: api-custom-cert-sample-hosted.sample-hosted.example.com (3)
# ...
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. |
2 | The name of the secret that contains the custom certificate. |
3 | This field accepts a URI that will be used as the API server endpoint. |
Apply the configuration by entering the following command:
$ oc -f <hosted_cluster_spec>.yaml
After the configuration is applied, the HyperShift Operator generates a new kubeconfig
secret that points to your custom DNS domain.
Retrieve the kubeconfig
secret by using the CLI or the console.
To retrieve the secret by using the CLI, enter the following command:
$ kubectl get secret <hosted_cluster_name>-custom-admin-kubeconfig \
-n <cluster_namespace> \
-o jsonpath='{.data.kubeconfig}' | base64 -d
To retrieve the secret by using the console, go to your hosted cluster and click Download Kubeconfig.
You cannot consume the new |
If you encounter issues when you access a hosted cluster by using a custom DNS, complete the following steps.
Verify that the DNS record is properly configured and resolved.
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:
$ oc get secret \
-n clusters <serving_certificate_name> \
-o jsonpath='{.data.tls\.crt}' | base64 \
-d |openssl x509 -text -noout -
Ensure that network connectivity to the custom domain is working.
In the HostedCluster
resource, verify that the status shows the correct custom kubeconfig
information, as shown in the following example:
HostedCluster
statusstatus:
customKubeconfig:
name: sample-hosted-custom-admin-kubeconfig
Check the kube-apiserver
logs in the HostedControlPlane
namespace by entering the following command:
$ oc logs -n <hosted_control_plane_namespace> \
-l app=kube-apiserver -f -c kube-apiserver