[BOP-1466] Client bundle docs

[byDimasik]

Description

In addition to the MKE Dashboard, users can use kubectl to access and manipulate the MKE 4 cluster. To use kubectl, each user needs a kubeconfig file. This article describes how MKE 4 cluster admins can create kubeconfig files for themselves or other users.

Comparison with MKE 3 client bundles

In MKE 3, users could download client certificate bundles that included a kubeconfig file in addition to certificate files used to configure Docker CLI. In MKE 4, there is no need for a bundle, just the kubeconfig file is sufficient as it already has all necessary certificates embedded.

In MKE 3, client bundles could be created by admin users for any other users, or by non-admin users only for themselves. Previously created client bundles could be viewed and revoked.

Currently, in MKE 4, only admin users are able to create kubeconfig files. Previously created kubeconfig files cannot be viewed or revoked. Thus, the expiration time of the certificates used in the kubeconfig files should be set appropriately.

Below is the table that lists all major differences between MKE 3 client bundles and MKE 4 kubeconfig files:

Feature	MKE 3 client bundles	MKE 4 kubeconfig files
Create by admins for other users	✅	✅
Create by admins for themselves	✅	✅
Create by non-admins for other users	❌	❌
Create by non-admins for themselves	✅	❌
View previously created bundles	✅	❌
Revoke previously created bundles	✅	❌
Set expiration time of certificates	❌	✅
Can be generated from MKE UI	✅	❌
Non-admin certs are issued by a separate CA that is trusted by kube API server, but not trusted by other components like kubelet	✅	❌

Create

The only way to create a kubeconfig file for a specific user is to run the shell script below as an admin user. You should run the script below from the same place where you previously configured your MKE 4 cluster with mkectl apply. Alternatively, you may run the script if another admin previously issued you a kubeconfig file with admin-level permissions.

Prerequisites

• openssl
• kubectl

Steps

0. If you haven't already, create a new user ("Access Control" -> "Users") and assign them a role ("Access Control" -> "Permissions")
1. In a terminal session where you are already able to use kubectl as an MKE 4 cluster administrator, set the following variables:

   # username of the target user 
   USERNAME=
   
   # expiration time in days
   EXPIRES_IN_DAYS=7
   
   # expiration time in seconds is automatically calculated from EXPIRES_IN_DAYS
   EXPIRES_IN_SECONDS=$((EXPIRES_IN_DAYS * 24 * 60 * 60))
   
   # the default kubeconfig location for MKE 4 clusters created by mkectl apply. Do not change unless you know what you're doing
   KUBECONFIG=~/.mke/mke.kubeconf

   Make sure you set the expiration time to a reasonable value. You will not be able to revoke the certificates used by the new kubeconfig file. The default value is 7 days.
2. Run the following commands in the terminal session. It will create a kubeconfig file in the same directory <username>.kubeconfig

   export KUBECONFIG
   
   openssl genrsa -out $USERNAME.key 2048
   openssl req -new -key $USERNAME.key -out $USERNAME.csr -subj "/CN=$USERNAME"
   
   CSR_CONTENT=$(cat $USERNAME.csr | base64 | tr -d '\n')
   CSR_NAME=$USERNAME-csr-$(LC_ALL=C tr -dc A-Za-z0-9 </dev/urandom | head -c 10; echo)
   
   cat <<EOF | envsubst | kubectl apply -f -
   apiVersion: certificates.k8s.io/v1
   kind: CertificateSigningRequest
   metadata:
     name: $CSR_NAME
   spec:
     request: $CSR_CONTENT
     signerName: kubernetes.io/kube-apiserver-client
     expirationSeconds: $EXPIRES_IN_SECONDS
     usages:
     - client auth
   EOF
   
   kubectl certificate approve "$CSR_NAME"
   kubectl get csr "$CSR_NAME" -o jsonpath='{.status.certificate}' | base64 --decode > $USERNAME.crt
   
   kubectl config view --minify --flatten > $USERNAME.kubeconfig
   kubectl config unset users --kubeconfig=$USERNAME.kubeconfig > /dev/null
   kubectl config unset contexts --kubeconfig=$USERNAME.kubeconfig > /dev/null
   
   kubectl config set-credentials $USERNAME --client-certificate=$USERNAME.crt --client-key=$USERNAME.key --embed-certs=true --kubeconfig=$USERNAME.kubeconfig
   kubectl config set-context mke-$USERNAME --cluster=mke --user=$USERNAME --kubeconfig=$USERNAME.kubeconfig
   kubectl config use-context mke-$USERNAME --kubeconfig=$USERNAME.kubeconfig
   
   rm $USERNAME.crt $USERNAME.csr $USERNAME.key

3. You can now send the generated <username>.kubeconfig file to the target user. They can use it to access the MKE 4 cluster with kubectl --kubeconfig.

Warning

The certificates issued with these steps may be used to access kubelet because the signer we used to sign our certs is the same as the kubelet client CA. To prevent any security risks, admins should ensure that kubelet is not accessible from outside of the cluster.

List

Currently, there is no way to list previously created kubeconfig files.

Revoke

Currently, there is no way to revoke previously created kubeconfig files.

[rleap-m]

Since I heard it mentioned about the tedium of producing the kubeconfig files in the TOI just thought I'd drop a link to the script I created which will create the kubeconfig files for migrated MKE3 admins here for ease of reference:

create_mke_cluster_admin_kubeconfig_files.sh

Cheers!