v1beta1 Example: Cluster with FQDN

Refer to this example to provision a TKGS cluster using one or more fully qualified domain names (FQDN).

FQDN Support

You can use the v1beta1 API to provision a TKG cluster with a fully qualified domain name (FQDN). The Cluster v1beta1 API includes a variable named kubeAPIServerFQDNs that contains at least one FQDN string to be generated in the TLS certificate for the Kubernetes API Server.

When the kubectl vsphere login command is issued for a cluster with FQDN configured, the authentication service will select the first FQDN entry in the list and add it to the kubeconfig as the preferred choice for interacting with the cluster. It is assumed that the first FQDN in the list is resolvable. There are no changes required to the cluster login.

The Kubernetes API certificate that is generated will include all of the FQDNs you have specified in the kubeAPIServerFQDNs variable. The system will not attempt to use any other FQDN in the list other than the first. The system does not attempt to resolve the FQDN. If you want to use a different FQDN from the list, you can manually edit the generated kubeconfig file and add the desired FQDN.

FQDN Requirements

Using an FQDN is optional. The functionality does not change if you do not use an FQDN. The functionality described here is specific to TKG workload clusters. To use an FQDN with Supervisor, refer to that topic in the Supervisor documentation.

Adhere to the following requirements to provision a TKG cluster with an FQDN.

vSphere 8.0 U2 P03 and later environments
Supervisor is updated to the latest patch release
Only v1beta1 API clusters are supported; there is no support for v1alpha3 API clusters
DNS is configured to resolve the chosen FQDN to a valid IP address

Important: The FQDN feature is only available if you are using the v1beta1 API to provision a CAPI Cluster. You cannot provision a TKC using the v1alpha3 API with an FQDN.

FQDN Example

Use the Cluster v1beta1 API to create a Cluster with an FQDN.

The spec.topology.variables.kupeAPIServerFQDNs value is an array of FQDNs.

The system will select the first FQDN in the list, which in this example is demo.fqdn.com.

#cluster-example-fqdn.yaml
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: tkg-cluster-fqdn
  namespace: tkg-ns
spec:
  clusterNetwork:
    services:
      cidrBlocks: ["198.52.100.0/12"]
    pods:
      cidrBlocks: ["192.101.2.0/16"]
    serviceDomain: "cluster.local"
  topology:
    class: tanzukubernetescluster
    version: v1.26.5+vmware.2-fips.1-tkg.1
    controlPlane:
      replicas: 3
    workers:
      machineDeployments:
        - class: node-pool
          name: node-pool-01
          replicas: 3
    variables:
      - name: vmClass
        value: guaranteed-medium
      - name: storageClass
        value: tkgs-storage-class
      - name: defaultStorageClass
        value: tkg-storage-class
      - name: kubeAPIServerFQDNs
        value:
          - demo.fqdn.com
          - explore.fqdn.com

FQDN Verification

Complete the following procedure to verify that the first FQDN in the variable list is included in the kubeconfig file, and that all FQDNs in the variable list are in the TLS certificate for the Kubernetes API Server.

kubectl vsphere login --server=SVCP IP or FQDN --vsphere-username USERNAME --tanzu-kubernetes-cluster-name CLUSTER-NAME --tanzu-kubernetes-cluster-namespace VSPHERE-NS

To view the FQDN in the kubeconfig file.
```
cat ~/.kube/config
```

Verify that the first FQDN variable in the list is included in the kubeconfig.

For example:

apiVersion: v1
clusters:
- cluster:
    insecure-skip-tls-verify: false
    server: https://10.199.155.77:6443
  name: 10.199.155.77
- cluster:
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJ...DQWRLZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXc
    ...
    CkdiL1pua09rOVVjT3BwSStCTE9ZZDR0RGd2eHo...QUp0SUUKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
    server: https://demo.fqdn.com:6443
  name: demo.fqdn.com

Using the vSphere Client, get the IP address for the TKGS cluster at Workload Management > Namespace > Compute > Tanzu Kubernetes clusters > Control Plane Address.

Make a manual DNS entry in the local /etc/hosts file with the IP address and FQDN.

For example:

sudo vi /etc/hosts
127.0.0.1 localhost
127.0.1.1 ubuntu-client-vm
10.199.155.77 demo.fqdn.com
...

Use the openssl s_client command to view the TLS certificate.

echo | openssl s_client -servername hostname -connect FQDN:PORT 2>/dev/null | openssl x509 -text

Where FQDN is the first one in the kubeAPIServerFQDNs variable list.

For example:

echo | openssl s_client -servername hostname -connect demo.fqdn.com:6443 2>/dev/null | openssl x509 -text

In the Subject Alternative Name field you should all FQDNs are included.
```
X509v3 Subject Alternative Name:
    DNS:demo.fqdn.com, DNS:explore.fqdn.com, DNS:kubernetes, DNS:kubernetes.default, DNS:kubernetes.default.svc, DNS:kubernetes.def
```
Because the TLS certificate for the Kubernetes API Server includes all FQDNs in the kubeAPIServerFQDNs list, you could manually update the kubeconfig file to use the second (or third, etc.) FQDN in the list, and it would work (assuming it's resolvable).