Skip to content

How to configure the Authorized Cluster Endpoint with a Layer 4 Loadbalancer for a Rancher-provisioned RKE2 or K3s cluster

This document (000021968) is provided subject to the disclaimer at the end of this document.

Environment

  • A Rancher-provisioned RKE2 or K3s cluster with Authorized Cluster Endpoint (ACE) enabled

Situation

You are trying to configure the Authorized Cluster Endpoint (ACE) to provide direct kubectl access to a downstream cluster through a Layer 4 load balancer. You have enabled ACE and provided the FQDN of your load balancer, with the intention of using the cluster's default self-signed certificates.

However, when you use the generated kubeconfig file to connect to the cluster's FQDN, the kubeconfig generated does not contain a CA certificate in certificate-authority-data ( ``) and the connection fails with a TLS certificate validation error, such as:

Unable to connect to the server: tls: failed to verify certificate: x509: certificate signed by unknown authority

Resolution

To resolve this, you must perform a two-step configuration. The first step can be done during cluster provisioning, and the second is done after the cluster is active.

Step 1: Add the FQDN as a TLS Alternate Name (SAN)

Pass the FQDN of the external loadbalancer as a TLS Alternate Name to ensure that the Kuberentes API Server certificates generated by RKE2 are valid for this FQDN.

  • Via Rancher UI:

When creating or editing the cluster, navigate to the Networking tab and add your load balancer's FQDN (e.g., kube-api.my-company.com) to the TLS Alternate Names field. - Via YAML:

Add the tls-san parameter to your cluster configuration YAML.

YAML

spec:
 rkeConfig:
   machineSelectorConfig:
     - config:
         tls-san:
           - kube-api.my-company.com

Step 2: Provide the Cluster CA Certificate to the ACE Configuration

After initial cluster provisioning retrieve the Kubernetes API Server CA Certificate and add this to the CA Certificates field of the ACE configuration. This step tells Rancher which Certificate Authority to use to validate the endpoint.

  1. Retrieve the CA Certificate from a control plane node in your downstream cluster. You will need SSH access to the node.

- For RKE2: /var/lib/rancher/rke2/server/tls/server-ca.crt

- For K3s: /var/lib/rancher/k3s/server/tls/server-ca.crt 2. Copy the entire content of this server-ca.crt file. 3. Update the ACE Configuration in the Rancher UI:

- Navigate to your cluster and click Edit Config.

- In the Cluster Configuration Networking section, scroll to Authorized Cluster Endpoint.

- Paste the copied certificate content into the CA Certificates field.

- Save the changes.

Download a new kubeconfig file. It will now contain the correct certificate-authority-data and will connect successfully.

Cause

The Authorized Cluster Endpoint (ACE) functionality is currently designed for TLS termination at the Loadbalancer (Layer 7 load balancers), in which a user configures a separate CA-signed certificate for this Loadbalancer endpoint (that signs the TLS certificate used on the load balancer itself), and then defines this CA in the ACE configuration for the cluster. As a result, it is not currently possible to automate configuration of the ACE endpoint using the Kubernetes API Server CA Certificate at cluster provisioning time.

When using a Layer 4 load balancer, TLS traffic is passed through directly to the cluster's API server. This creates two requirements that are not automatically configured:

  • The API server's own TLS certificate must include the load balancer's FQDN as a valid Subject Alternative Name (SAN). Without this, the certificate is not considered valid for that hostname.
  • Rancher's kubeconfig generator needs to be explicitly told to trust the cluster's internal, self-signed CA for that FQDN.

Additional Information

Enhancement Request: This manual, multi-step process is a known limitation. An enhancement request exists to streamline this workflow for Layer 4 load balancers, which would automate the steps outlined above.

Disclaimer

This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.