Access an MKE cluster

Access an MKE cluster

Note

UCP is now MKE.

The product formerly known as Universal Control Plane (UCP) is now Mirantis Kubernetes Engine (MKE).

MKE web interface

Mirantis Kubernetes Engine allows you to manage your cluster in a visual way, from your browser.

MKE secures your cluster by using role-based access control. From the browser, administrators can:

  • Manage cluster configurations

  • Manage the permissions of users, teams, and organizations

  • See all images, networks, volumes, and containers

  • Grant permissions to users for scheduling tasks on specific nodes (with the MKE license)

Non-admin users can only see and change the images, networks, volumes, and containers, and only when they’re granted access by an administrator.

CLI access

With Mirantis Kubernetes Engine you can continue using the tools you know and love like the Docker CLI client and kubectl. You just need to download and use a MKE client bundle.

A client bundle contains a private and public key pair that authorizes your requests in MKE. It also contains utility scripts you can use to configure your Docker and kubectl client tools to talk to your MKE deployment.

Download client certificates

To use the Docker CLI with MKE, download a client certificate bundle by using the MKE web UI.

  1. Navigate to the My Profile page.

  2. In the left pane, click Client Bundles and choose New Client Bundle to download the certificate bundle.

Use client certificates

Once you’ve downloaded a client certificate bundle to your local computer, you can use it to authenticate your requests.

Navigate to the directory where you downloaded the user bundle, and extract the zip file into a directory. Then use the utility script appropriate for your system:

cd client-bundle && eval "$(<env.sh)"
# Run this from an elevated prompt session
cd client-bundle && env.cmd

The client bundle utility scripts update the environment variables DOCKER_HOST to make your client tools communicate with your MKE deployment, and the DOCKER_CERT_PATH environment variable to use the client certificates that are included in the client bundle you downloaded. The utility scripts also run the kubectl config command to configure kubectl.

To confirm that your client tools are now communicating with MKE, run:

docker version --format '{{.Server.Version}}'
kubectl config current-context

The expected Docker server version starts with ucp/, and the expected kubectl context name starts with ucp_.

You can now use the Docker and kubectl clients to create resources in MKE.

Use client certificates with Docker contexts

You may change your context directly using the bundle .zip files contained in the MKE bundle. Navigate to the directory where you downloaded the user bundle and use docker context import to add the new context:

cd client-bundle && docker context import myucp ucp-bundle-$USER.zip"

Client certificates for administrators

MKE issues different types of certificates depending on the user:

  • User certificate bundles: only allow running docker commands through a MKE manager node.

  • Admin user certificate bundles: allow running docker commands on the Mirantis Container Runtime of any node.

Download client certificates by using the REST API

You can also download client bundles by using the MKE REST API. In this example, we use curl to make the web requests to the API, jq to parse the responses, and unzip to unpack the zip archive.

To install these tools on an Ubuntu distribution, you can run:

sudo apt-get update && sudo apt-get install curl jq unzip

Then you get an authentication token from MKE and use it to download the client certificates.

# Create an environment variable with the user security token
AUTHTOKEN=$(curl -sk -d '{"username":"<username>","password":"<password>"}' https://<mke-ip>/auth/login | jq -r .auth_token)

# Download the client certificate bundle
curl -k -H "Authorization: Bearer $AUTHTOKEN" https://<mke-ip>/api/clientbundle -o bundle.zip

# Unzip the bundle.
unzip bundle.zip

# Run the utility script.
eval "$(<env.sh)"

# Confirm that you can see MKE containers:
docker ps -af state=running

On Windows Server 2016, open an elevated PowerShell prompt and run:

$AUTHTOKEN=((Invoke-WebRequest -Body '{"username":"<username>", "password":"<password>"}' -Uri https://`<mke-ip`>/auth/login -Method POST).Content)|ConvertFrom-Json|select auth_token -ExpandProperty auth_token

[io.file]::WriteAllBytes("ucp-bundle.zip", ((Invoke-WebRequest -Uri https://`<mke-ip`>/api/clientbundle -Headers @{"Authorization"="Bearer $AUTHTOKEN"}).Content))

Docker Build and MKE

When using a MKE client bundle and buildkit, follow the instructions provided in Restrict services to worker nodes to make sure that builds are not accidentally scheduled on manager nodes.

Kubernetes CLI

MKE deploys Kubernetes as part of an MKE installation. Deploy, manage, and monitor Kubernetes workloads from the MKE dashboard. Users can also interact with the Kubernetes deployment through the Kubernetes command-line tool named kubectl.

To access the MKE cluster with kubectl, install the MKE client bundle.

Important

Kubernetes on Docker Desktop for Mac and Docker Desktop for Windows

Docker Desktop for Mac and Docker Desktop for Windows provide a standalone Kubernetes server that runs on your development machine, with kubectl installed by default. This installation is separate from the Kubernetes deployment on a MKE cluster. Learn how to deploy to Kubernetes on Docker Desktop for Mac.

Install the kubectl binary

To use kubectl, install the binary on a workstation which has access to your MKE endpoint.

Important

Must install compatible version

Kubernetes only guarantees compatibility with kubectl versions that are +/-1 minor versions away from the Kubernetes version.

First, find which version of Kubernetes is running in your cluster. This can be found within the Mirantis Kubernetes Engine dashboard or at the MKE API endpoint version. You can also find the Kubernetes version using the Docker CLI. You need to source a client bundle and type the docker version command.

From the MKE dashboard, click About within the Admin menu in the top left corner of the dashboard. Then navigate to Kubernetes.

Once you have the Kubernetes version, install the kubectl client for the relevant operating system.

You can download the binary from the kubernetes.io portal.

If you have curl installed on your system, you use these commands in Powershell.

Using kubectl with an MKE cluster

MKE provides users unique certificates and keys to authenticate against the Docker and Kubernetes APIs. Instructions on how to download these certificates and how to configure kubectl to use them can be found in CLI-based access.

Install Helm on MKE

Helm is the package manager for Kubernetes. Tiller is the Helm server. Before installing Helm on MKE, you must meet the following requirements:

  • You must be running an MKE 3.1 or higher cluster.

  • You must have kubectl configured to communicate with the cluster (usually this is done via a client bundle).

To use Helm and Tiller with MKE, you must grant the default service account within the kube-system namespace the necessary roles. Enter the following kubectl commands in this order:

kubectl create rolebinding default-view --clusterrole=view --serviceaccount=kube-system:default --namespace=kube-system

kubectl create clusterrolebinding add-on-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default

It is recommended that you specify a Role and RoleBinding to limit Tiller’s scope to a particular namespace, as described in the Helm documentation.