Chapter 4. Cluster access with kubeconfig Learn about how kubeconfig files are used with MicroShift deployments. CLI tools use kubeconfig files to communicate with the API server of a cluster. These files provide cluster details, IP addresses, and other information needed for authentication. 4.1. Kubeconfig files for configuring cluster access The two categories of kubeconfig files used in MicroShift are local access and remote access. Every time MicroShift starts, a set of kubeconfig files for local and remote access to the API server are generated. These files are generated in the /var/lib/microshift/resources/kubeadmin/ directory using preexisting configuration information. Each access type requires a different authentication certificate signed by different Certificate Authorities (CAs). The generation of multiple kubeconfig files accommodates this need. You can use the appropriate kubeconfig file for the access type needed in each case to provide authentication details. The contents of MicroShift kubeconfig files are determined by either default built-in values or a config.yaml file. Note A kubeconfig file must exist for the cluster to be accessible. The values are applied from built-in default values or a config.yaml , if one was created. Example contents of the kubeconfig files /var/lib/microshift/resources/kubeadmin/ ├── kubeconfig 1 ├── alt-name-1 2 │ └── kubeconfig ├── 1.2.3.4 3 │ └── kubeconfig └── microshift-rhel9 4 └── kubeconfig 1 Local host name. The main IP address of the host is always the default. 2 Subject Alternative Names for API server certificates. 3 DNS name. 4 MicroShift host name. 4.2. Local access kubeconfig file The local access kubeconfig file is written to /var/lib/microshift/resources/kubeadmin/kubeconfig . This kubeconfig file provides access to the API server using localhost . Choose this file when you are connecting the cluster locally. Example contents of kubeconfig for local access clusters: - cluster: certificate-authority-data: <base64 CA> server: https://localhost:6443 The localhost kubeconfig file can only be used from a client connecting to the API server from the same host. The certificates in the file do not work for remote connections. 4.2.1. Accessing the MicroShift cluster locally Use the following procedure to access the MicroShift cluster locally by using a kubeconfig file. Prerequisites You have installed the oc binary. Procedure Optional: to create a ~/.kube/ folder if your Red Hat Enterprise Linux (RHEL) machine does not have one, run the following command: USD mkdir -p ~/.kube/ Copy the generated local access kubeconfig file to the ~/.kube/ directory by running the following command: USD sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config Update the permissions on your ~/.kube/config file by running the following command: USD chmod go-r ~/.kube/config Verification Verify that MicroShift is running by entering the following command: USD oc get all -A 4.3. Remote access kubeconfig files When a MicroShift cluster connects to the API server from an external source, a certificate with all of the alternative names in the SAN field is used for validation. MicroShift generates a default kubeconfig for external access using the hostname value. The defaults are set in the <node.hostnameOverride> , <node.nodeIP> and api.<dns.baseDomain> parameter values of the default kubeconfig file. The /var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig file uses the hostname of the machine, or node.hostnameOverride if that option is set, to reach the API server. The CA of the kubeconfig file is able to validate certificates when accessed externally. Example contents of a default kubeconfig file for remote access clusters: - cluster: certificate-authority-data: <base64 CA> server: https://microshift-rhel9:6443 4.3.1. Remote access customization Multiple remote access kubeconfig file values can be generated for accessing the cluster with different IP addresses or host names. An additional kubeconfig file generates for each entry in the apiServer.subjectAltNames parameter. You can copy remote access kubeconfig files from the host during times of IP connectivity and then use them to access the API server from other workstations. 4.4. Generating additional kubeconfig files for remote access You can generate additional kubeconfig files to use if you need more host names or IP addresses than the default remote access file provides. Important You must restart MicroShift for configuration changes to be implemented. Prerequisites You have created a config.yaml for MicroShift. Procedure Optional: You can show the contents of the config.yaml . Run the following command: USD cat /etc/microshift/config.yaml Optional: You can show the contents of the remote-access kubeconfig file. Run the following command: USD cat /var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig Important Additional remote access kubeconfig files must include one of the server names listed in the Red Hat build of MicroShift config.yaml file. Additional kubeconfig files must also use the same CA for validation. To generate additional kubeconfig files for additional DNS names SANs or external IP addresses, add the entries you need to the apiServer.subjectAltNames field. In the following example, the DNS name used is alt-name-1 and the IP address is 1.2.3.4 . Example config.yaml with additional authentication values dns: baseDomain: example.com node: hostnameOverride: "microshift-rhel9" 1 nodeIP: 10.0.0.1 apiServer: subjectAltNames: - alt-name-1 2 - 1.2.3.4 3 1 Hostname 2 DNS name 3 IP address or range Restart MicroShift to apply configuration changes and auto-generate the kubeconfig files you need by running the following command: USD sudo systemctl restart microshift To check the contents of additional remote-access kubeconfig files, insert the name or IP address as listed in the config.yaml into the cat command. For example, alt-name-1 is used in the following example command: USD cat /var/lib/microshift/resources/kubeadmin/alt-name-1/kubeconfig Choose the kubeconfig file to use that contains the SAN or IP address you want to use to connect your cluster. In this example, the kubeconfig containing`alt-name-1` in the cluster.server field is the correct file. Example contents of an additional kubeconfig file clusters: - cluster: certificate-authority-data: <base64 CA> server: https://alt-name-1:6443 1 1 The /var/lib/microshift/resources/kubeadmin/alt-name-1/kubeconfig file values are from the apiServer.subjectAltNames configuration values. Note All of these parameters are included as common names (CN) and subject alternative names (SAN) in the external serving certificates for the API server. 4.4.1. Opening the firewall for remote access to the MicroShift cluster Use the following procedure to open the firewall so that a remote user can access the MicroShift cluster. This procedure must be completed before a workstation user can access the cluster remotely. For this procedure, user@microshift is the user on the MicroShift host machine and is responsible for setting up that machine so that it can be accessed by a remote user on a separate workstation. Prerequisites You have installed the oc binary. Your account has cluster administration privileges. Procedure As user@microshift on the MicroShift host, open the firewall port for the Kubernetes API server ( 6443/tcp ) by running the following command: [user@microshift]USD sudo firewall-cmd --permanent --zone=public --add-port=6443/tcp && sudo firewall-cmd --reload Verification As user@microshift , verify that MicroShift is running by entering the following command: [user@microshift]USD oc get all -A 4.4.2. Accessing the MicroShift cluster remotely Use the following procedure to access the MicroShift cluster from a remote location by using a kubeconfig file. The user@workstation login is used to access the host machine remotely. The <user> value in the procedure is the name of the user that user@workstation logs in with to the MicroShift host. Prerequisites You have installed the oc binary. The user@microshift has opened the firewall from the local host. Procedure As user@workstation , create a ~/.kube/ folder if your Red Hat Enterprise Linux (RHEL) machine does not have one by running the following command: [user@workstation]USD mkdir -p ~/.kube/ As user@workstation , set a variable for the hostname of your MicroShift host by running the following command: [user@workstation]USD MICROSHIFT_MACHINE=<name or IP address of MicroShift machine> As user@workstation , copy the generated kubeconfig file that contains the host name or IP address you want to connect with from the RHEL machine running MicroShift to your local machine by running the following command: [user@workstation]USD ssh <user>@USDMICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/USDMICROSHIFT_MACHINE/kubeconfig" > ~/.kube/config Note To generate the kubeconfig files for this step, see Generating additional kubeconfig files for remote access . As user@workstation , update the permissions on your ~/.kube/config file by running the following command: USD chmod go-r ~/.kube/config Verification As user@workstation , verify that MicroShift is running by entering the following command: [user@workstation]USD oc get all -A

Commands:
/var/lib/microshift/resources/kubeadmin/ ├── kubeconfig 1 ├── alt-name-1 2 │ └── kubeconfig ├── 1.2.3.4 3 │ └── kubeconfig └── microshift-rhel9 4 └── kubeconfig
clusters: - cluster: certificate-authority-data: <base64 CA> server: https://localhost:6443
mkdir -p ~/.kube/
sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config
chmod go-r ~/.kube/config
oc get all -A
clusters: - cluster: certificate-authority-data: <base64 CA> server: https://microshift-rhel9:6443
cat /etc/microshift/config.yaml
cat /var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig
dns: baseDomain: example.com node: hostnameOverride: "microshift-rhel9" 1 nodeIP: 10.0.0.1 apiServer: subjectAltNames: - alt-name-1 2 - 1.2.3.4 3
sudo systemctl restart microshift
cat /var/lib/microshift/resources/kubeadmin/alt-name-1/kubeconfig
clusters: - cluster: certificate-authority-data: <base64 CA> server: https://alt-name-1:6443 1
[user@microshift]USD sudo firewall-cmd --permanent --zone=public --add-port=6443/tcp && sudo firewall-cmd --reload
[user@microshift]USD oc get all -A
[user@workstation]USD mkdir -p ~/.kube/
[user@workstation]USD MICROSHIFT_MACHINE=<name or IP address of MicroShift machine>
[user@workstation]USD ssh <user>@USDMICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/USDMICROSHIFT_MACHINE/kubeconfig" > ~/.kube/config
chmod go-r ~/.kube/config
[user@workstation]USD oc get all -A