Skip to main content

How to use kubectl to connect to the cluster

The aim of this guide is to help you install and configure kubectl, the official command-line tool for Kubernetes.

kubectl is used to deploy and manage applications on Kubernetes and is fundamental for anyone who wants to interact with the Cloud Platform.

After working through this guide you should be able to use kubectl to query and update your namespace(s) on the Cloud Platform.

Installation

Please read the official documentation on how to install kubectl.

Before you begin

You must use a kubectl version that is within one minor version difference of your cluster. For example, a v1.15 client should work with v1.14, v1.15, and v1.16 master. Check the current value in the infrastructure repository to avoid unforeseen issues.

Authentication

After installing kubectl, you need to authenticate to the Cloud Platform.

To do this, you must have a GitHub account to which your ...@digital.justice.gov.uk email address has been added.

The Cloud Platform uses GitHub for authentication and authorisation, and access to different namespaces (e.g. pvb-production, cla-staging) is granted according to GitHub team membership (e.g. ‘PVB’ and ‘CLA’ teams).

Your account must be a member of the Ministry of Justice Organisation on GitHub. If you are not already in the organisation, you can add yourself (provided you have added your MoJ email address to your GitHub account) using this link.

How do I connect to the kubernetes cluster?

We use Auth0 to bridge between GitHub’s OAuth2, and OIDC authentication, which Kubernetes supports. Kuberos generates a config file, containing access credentials. You need to download this file and store it on your laptop, as ~/.kube/config

  1. Click on this link
  2. Go through the ‘Sign in with GitHub’ process

    NB: Be careful when you reach the authorization step:

    GitHub Authorize MoJ

  3. Authorise ‘live-1:kubernetes’ to access your ‘justice-cloud-platform’ tenant

  4. Use the ‘Download Config File’ button

  5. Rename the downloaded file to ~/.kube/config

  6. Run this command:

kubectl config use-context live-1.cloud-platform.service.justice.gov.uk

You should now be able to run kubectl commands. Try running kubectl get namespaces to list the namespaces in the cluster.

Troubleshooting: “current” context

If you see an error like this when executing kubectl commands: The connection to the server localhost:8080 was refused

Check that your “current” context is set, by running:

kubectl config get-contexts

If the output looks like this (i.e. there is no * indicating that the live-1 context is set as the current context:

CURRENT   NAME                                           CLUSTER                                        AUTHINFO                 NAMESPACE
          live-1.cloud-platform.service.justice.gov.uk   live-1.cloud-platform.service.justice.gov.uk   <your github e-mail>

Then you need to set the context with the use-context command mentioned above.

Using multiple kubeconfigs

During migration from live-1 to live, you will have multiple kubeconfig files (one per cluster) but you may want to use them all at once, with kubectl that work with multiple contexts at once.

To do that, you need to merge the kubeconfigs into a single file, following the steps outlined below.

Grab a new set of credentials for live from login.live.cloud-platform.service.justice.gov.uk.

You’ll download a new config.yaml. Copy that to your .kube folder:

    mv ~/Downloads/config.yaml ~/.kube/config-live

Note: You have the same user but a different token for “live-1” and “live” kubeconfig, merging the two configs will only keep the user for the first one it encounters, to avoid that you will need to use a different “user” name in the “live-1” and “live” kubeconfig.

Amend the “user” in config-live as shown below

contexts:
- context:
    cluster: live.cloud-platform.service.justice.gov.uk
    user: <firstname>.<lastname>@live
  name: live.cloud-platform.service.justice.gov.uk
current-context: ""
kind: Config
preferences: {}
users:
- name: <firstname>.<lastname>@live

Copy your existing live-1 credentials into a separate file:

    cp ~/.kube/config ~/.kube/config-live-1

Amend the “user” in config-live-1 as shown below

contexts:
- context:
    cluster: live-1.cloud-platform.service.justice.gov.uk
    user: <firstname>.<lastname>@live-1
  name: live-1.cloud-platform.service.justice.gov.uk
current-context: ""
kind: Config
preferences: {}
users:
- name: <firstname>.<lastname>@live-1

Then, run this command to merge the two config files together into a new config file and replace your old config with the new merged config.

KUBECONFIG=~/.kube/config-live-1:~/.kube/config-live kubectl config view --flatten > /tmp/config && mv /tmp/config ~/.kube/config

Now using the single config file, you can switch between live-1 and live context

For live-1:

kubectl config use-context live-1.cloud-platform.service.justice.gov.uk

For live:

kubectl config use-context live.cloud-platform.service.justice.gov.uk

Where to go from here?

Now that you’ve setup kubectl, you might want to look at this handy cheatsheet.

Once you are ready to deploy applications you will need to create a namespace first.

This page was last reviewed on 1 July 2021. It needs to be reviewed again on 1 October 2021 .
This page was set to be reviewed before 1 October 2021. This might mean the content is out of date.