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

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

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

2.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 RHEL machine does not have one, run the following command:
```
$ mkdir -p ~/.kube/
```
Copy the generated local access kubeconfig file to the ~/.kube/ directory by running the following command:
```
$ sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config
```
Update the permissions on your ~/.kube/config file by running the following command:
```
$ chmod go-r ~/.kube/config
```

Verification

Verify that MicroShift is running by entering the following command:
```
$ oc get all -A
```

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

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

2.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:
```
$ cat /etc/microshift/config.yaml
```
Optional: You can show the contents of the remote-access kubeconfig file. Run the following command:
```
$ cat /var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig
```
Important
Additional remote access kubeconfig files must include one of the server names listed in the 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:
```
$ 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:
```
$ 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.

2.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]$ 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]$ oc get all -A
```

2.4.2. Accessing the MicroShift cluster remotely

Use the following procedure to access the MicroShift cluster from a remote workstation 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 RHEL machine does not have one by running the following command:
```
[user@workstation]$ mkdir -p ~/.kube/
```
As user@workstation, set a variable for the hostname of your MicroShift host by running the following command:
```
[user@workstation]$ 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]$ ssh <user>@$MICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/$MICROSHIFT_MACHINE/kubeconfig" > ~/.kube/config
```

Note

To generate kubeconfig files for this step, see the "Generating additional kubeconfig files for remote access" link in the additional resources section.

As user@workstation, update the permissions on your ~/.kube/config file by running the following command:
```
$ chmod go-r ~/.kube/config
```

Verification

As user@workstation, verify that MicroShift is running by entering the following command:
```
[user@workstation]$ oc get all -A
```

Chapter 2. Cluster access with kubeconfig

2.1. Kubeconfig files for configuring cluster access

2.2. Local access kubeconfig file

2.2.1. Accessing the MicroShift cluster locally

2.3. Remote access kubeconfig files

2.3.1. Remote access customization

2.4. Generating additional kubeconfig files for remote access

2.4.1. Opening the firewall for remote access to the MicroShift cluster

2.4.2. Accessing the MicroShift cluster remotely

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links