Chapter 7. Configuring certificates for hosted control planes

Procedure

1. 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>

2. 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.

3. Apply the changes to your HostedCluster configuration by entering the following command:

   $ oc apply -f <hosted_cluster_config>.yaml

Procedure

1. 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.

   Example command to configure the DNS record

   $ dig + short kubeAPIServerDNSName

2. 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.

3. 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.

4. Retrieve the kubeconfig secret by using the CLI or the console.

   1. 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

   2. To retrieve the secret by using the console, go to your hosted cluster and click Download Kubeconfig.

      Note

      You cannot consume the new kubeconfig secret by using the show login command option in the console.

Procedure

1. Identify your hosted cluster namespace:

   1. Export the namespace where your hosted cluster is running by entering the following command:

      $ export HC_NAMESPACE=<hosted_cluster_namespace>

   2. Export the hosted cluster name by entering the following command:

      $ export CLUSTER_NAME=<hosted_cluster_name>

2. Generate a quick test certificate by entering the following command:

   $ 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.

3. Confirm that the file exists by entering the following command:

   $ ls tls.crt tls.key

4. If you have not already created the TLS secret in the hosted cluster namespace, create the secret by entering the following command:

   $ oc create secret tls my-oauth-cert-secret \
     --cert=path/to/tls.crt \
     --key=path/to/tls.key \
     -n $HC_NAMESPACE

   Example output

   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.

5. Discover the correct OAuth route:

   1. Use the management cluster kubconfig file to enter the following command:

      $ oc get routes -n ${HC_NAMESPACE}-${CLUSTER_NAME}

   2. If the route name is oauth, confirm it by entering the following command:

      $ oc get route oauth -n ${HC_NAMESPACE}-${CLUSTER_NAME} -o yaml

   3. Prepare to extract the OAuth route host by entering the following command:

      OAUTH_HOST=$(oc get route oauth \
        -n ${HC_NAMESPACE}-${CLUSTER_NAME} \
        -o jsonpath='{.spec.host}')

   4. Extract the OAuth route host by entering the following command:

      $ echo "${OAUTH_HOST}"

      Example output

      oauth-${HC_NAMESPACE}-${CLUSTER_NAME}.api-custom-cert-sample-hosted.sample-hosted.example.com

6. Edit the HostedCluster resource:

   1. Open the HostedCluster resource for editing by entering the following command:

      $ oc edit hostedcluster $CLUSTER_NAME -n $HC_NAMESPACE

   2. In the resource, configure the named certificates by adding the servingCerts.namedCertificates stanza to the spec.configuration.apiServer section:

      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.

   3. 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.

Procedure

1. Verify that the DNS record is properly configured and resolved.

2. 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 -

3. Ensure that network connectivity to the custom domain is working.

4. In the HostedCluster resource, verify that the status shows the correct custom kubeconfig information, as shown in the following example:

   Example HostedCluster status

   status:
     customKubeconfig:
       name: sample-hosted-custom-admin-kubeconfig

5. 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