Access and manage the cluster with kubectl#

In addition to the MKE 4 Dashboard, you can access and manage your MKE 4 cluster using kubectl with a kubeconfig file.

In MKE 4, the kubeconfig file uses mkectl as an exec-based authentication plugin for the MKE 4 cluster. As such, to access the cluster using kubectl you must have mkectl installed and available in your PATH environment variable.

Run the following command to verify mkectl installation:

mkectl version

The mkectl version must be v4.1.2 or later.

Notes

The default kubeconfig path is ~/.mke/mke.kubeconf for all commands.
mkectl recognizes the KUBECONFIG environment variable for the kubeconfig path.
You can change the kubeconfig path using the --kubeconfig flag or the KUBECONFIG environment variable.
The precedence order for the kubeconfig path is:

(1) --kubeconfig flag

(2) KUBECONFIG environment variable

(3) ~/.mke/mke.kubeconf (default value)
If you are an admin user who previously provisioned the cluster with the mkectl apply command, your kubeconfig file already exists at ~/.mke/mke.kubeconf.

To create a kubeconfig file for other cluster users, use the mkectl kubeconfig command with a valid mke4.yaml configuration file:
```
mkectl kubeconfig -f mke4.yaml > /path/to/kube.conf
```

Obtain the kubeconfig file#

To generate the kubeconfig file for use with kubectl, you can:

Log in to MKE 4 using mkectl
Download the kubeconfig file from the MKE 4 Dashboard

Use mkectl to generate the kubeconfig file:#

Log in using mkectl:
```
mkectl login --cluster-ca-file /path/to/cluster-ca.pem --ca-file /path/to/client-ca.pem
```
Tip

Two CA certificates are available for mkectl login:
- cluster-ca.pem: CA certificate for the Kubernetes API server
- client-ca.pem: CA certificate for the ingress controller
After you create a cluster with mkectl apply, MKE 4 admins can find both certificates in the ~/.mke/ directory. Any user can download them from the /ca and /cluster-ca endpoints of the MKE 4 address. To determine which certificate to pass to each option, refer to Choose the CA certificates for mkectl login.

If your cluster uses custom ingress TLS certificates that your system already trusts, you can omit the --ca-file option.
At the prompt, enter the cluster address. This will cause your browser to open at the MKE 4 login page.
Log in to MKE 4. Doing so will create the kubeconfig file at the ~/.mke/mke.kubeconf default location.
Use the kubeconfig file by:
- Specifying the KUBECONFIG environment variable:
```
export KUBECONFIG=~/.mke/mke.kubeconf
```
— OR —
- Using the --kubeconfig flag:
```
kubectl --kubeconfig ~/.mke/mke.kubeconf cluster-info
```

The mkectl login command requires two CA certificates: one to verify the MKE gateway, and one to verify the Kubernetes API server. MKE 4 serves both certificates without authentication:

Endpoint	Certificate
`https://<mke-address>/ca`	CA of the MKE gateway, which serves the MKE 4 Dashboard and authentication on port `443`
`https://<mke-address>/cluster-ca`	Kubernetes cluster CA that k0s generates

Always pass the /ca certificate to --ca-file. The certificate to pass to --cluster-ca-file, and the value to pass to --address, depend on how you configure TLS for the cluster:

TLS configuration	`--address`	`--cluster-ca-file`
Default certificates	`.spec.apiServer.externalAddress`	`/cluster-ca`
Custom certificates, `domainName` set to a DNS name	`.spec.certificates.domainName`	`/ca`
Custom certificates, `domainName` set to an IP address	`.spec.certificates.domainName`	`/cluster-ca`

Note

With a DNS domain name, the Kubernetes API server uses TLS Server Name Indication (SNI) to select and present the custom certificate. With an IP address domain name, the API server presents the k0s-generated certificate unless the IP address is assigned to the controller node. An IP address domain name also requires additional configuration. For details, refer to TLS verification fails when the custom TLS domain name is an IP address.

To log in with the correct CA certificates:

Download the MKE gateway CA certificate:

curl --fail --silent --show-error --insecure --output ca.pem https://<mke-address>/ca

Download the Kubernetes cluster CA certificate:

curl --fail --silent --show-error --insecure --output cluster-ca.pem https://<mke-address>/cluster-ca

Log in, passing the cluster CA certificate that matches your TLS configuration:
```
mkectl login --address <address> --ca-file ca.pem --cluster-ca-file <ca.pem-or-cluster-ca.pem>
```
The mkectl login command validates the generated kubeconfig file against port 6443. If you pass the wrong cluster CA certificate, the login fails.

Warning

The --insecure option skips verification of the certificate that serves the download. Verify each downloaded certificate before you use it. For instructions, refer to Retrieve the MKE CA certificates.

Download the kubeconfig file using the MKE 4 Dashboard:#

Log in to the MKE 4 Dashboard.
Click your username in top right corner to display the dropdown menu.
Click My Profile in the dropdown menu to go to the My Profile screen.```
Click the Download Kubeconfig button in the Kubeconfig section.

The kubeconfig file downloads as mke.kubeconfig, with an accompanying notification that contains user instruction.

Example mke.kubeconfig file:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <base64-encoded-cluster-ca>
    server: https://<cluster-external-address>:6443
  name: mke
contexts:
- context:
    cluster: mke
    user: mkectl
  name: mke
current-context: mke
kind: Config
users:
- name: mkectl
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - get-token
      - --address=<cluster-external-address>
      - --ca-data=<base64-encoded-ingress-ca>
      command: mkectl
      env: null
      interactiveMode: Never
      provideClusterInfo: false

Set kubeconfig file expiration#

For authentication, MKE 4 kubeconfig files use OAuth 2.0 refresh tokens. By default, refresh tokens do not expire; thus, to enhance security, you should set an expiration time for the tokens in the mke4.yaml configuration file.

Once the refresh token expires, users can still run operations on the cluster until the ID token expires. For this reason, Mirantis recommends that you set a very short expiration time for the ID tokens and a longer expiration time for the refresh tokens.

When the refresh token is expired or revoked by the admin, the kubectl command prompts relogin by opening the MKE 4 login page in the browser. Refer to Authentication configuration for more details.

Revoke Access#

Cluster admins can see and revoke the refresh tokens that are issued to users.

To view the list of refresh tokens:

kubectl --kubeconfig ~/.mke/mke.kubeconf get refreshtoken -n mke -o custom-columns="TOKEN ID:.metadata.name,USERNAME:.claims.email,CLIENT:.clientID"

Example output:

TOKEN ID                    USERNAME   CLIENT
seofzsgiah42cyw5vk6qovhe7   alice      mkectl
abcsefcyw5vghkqskb24bzzz8   bob        mkectl
vpqsefld54fpgkqskb24bpeh5   bob        mke-dashboard

To revoke a refresh token, delete the token by its ID:

kubectl --kubeconfig ~/.mke/mke.kubeconf delete refreshtoken <TOKEN ID> -n mke

Following this, the user can only get a new refresh token by logging back into the system.