Connecting to the Cloud Platform’s Kubernetes cluster

To use the Ministry of Justice’s Cloud Platform, you need to connect to the Cloud Platform’s Kubernetes cluster.

This guide will take you through installing and configuring kubectl. kubectl is the official command line tool for Kubernetes.

Once installed and configured, you can use kubectl to deploy and manage your applications on the Cloud Platform, in addition to the Cloud Platform CLI.

Installing `kubectl`

You should install a version of kubectl that is within one minor version of the Cloud Platform’s Kubernetes cluster.

The Cloud Platform’s current Kubernetes cluster version is 1.24. Therefore, you should install kubectl version 1.23, 1.24, or 1.25.

There is official documentation on how to install kubectl, including how to install a specific version:

Authenticating with the Cloud Platform’s Kubernetes cluster

Once you’ve installed kubectl, you will need to authenticate with the Cloud Platform’s Kubernetes cluster.

You will need to:

be part of the ministryofjustice GitHub organisation
be part of the correct GitHub team(s) for your service

Joining the GitHub organisation

You can request access to the ministryofjustice GitHub organisation by:

contacting the Operations Engineering team, or
getting your line manager to submit a ServiceNow request under the “GitHub for D&T staff - Add/Amend/Remove” item

Joining the correct GitHub teams

You can find the correct GitHub team to join by:

finding your services namespace in cloud-platform-environments
in your namespace directory, view the 00-namespace.yaml file
there will be a cloud-platform.justice.gov.uk/team-name key with a value of the GitHub team name to join
ask your team to add you to the listed GitHub team

Generating a kubeconfig file

To access the Cloud Platform’s Kubernetes cluster through kubectl, you will need to generate a kubeconfig file.

The kubeconfig file stores an authentication token for Kubernetes clusters.

To generate a kubeconfig file for the Cloud Platform’s Kubernetes cluster:

Browse to the login URL for the Cloud Platform
Select “Continue with GitHub”
Login to GitHub (if you’re not already logged in)
Authorise the “MOJ Cloud Platforms Auth0 (prod)” application in GitHub
Accept live:kubernetes requesting access to your justice-cloud-platform account
Select “Download config file”
Move the config file to the location expected by kubectl: ~/.kube/config:
```
$ mkdir ~/.kube
$ mv ~/Downloads/kubecfg.yaml ~/.kube/config
```
Reduce the permissions on the file by running:
```
$ chmod 600 ~/.kube/config
```

Tell kubectl to use this configuration by running:

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

Verify the configuration file by running:

$ kubectl get namespaces

Your output should be similar to:

NAME                                              STATUS   AGE
abundant-namespace-dev                            Active   100d
...

Troubleshooting: “current” context

If you see an error like this when executing kubectl commands:

The connection to the server localhost:8080 was refused

A common reason for this is that the “current” context has not been set. Check it by running:

kubectl config get-contexts

If current context is set correctly, you’ll see a *, like this:

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

If the * is missing, then you need to set the context with the use-context command mentioned above.

Using multiple kubeconfigs

You can have two kubeconfig files, corresponding to different clusters, which is useful when working on multiple clusters. This is a guide to being able to manage multiple kubeconfigs, so you can conveniently switch the cluster that kubectl connects to.

Essentially we will merge the kubeconfigs into a single file, and use kubectl config use-context to switch between them.

Assuming you already have a kubeconfig for a test cluster, download another kubeconfig for live from login.cloud-platform.service.justice.gov.uk.

Move the kubeconfig to your .kube folder:

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

Edit ~/.kube/config-live, and change the username in two places, from <firstname>.<lastname>@digital.justice.gov.uk to <firstname>.<lastname>@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
```
Explanation: If we don’t rename the username, then the merge will overwrite one of the them and their token, which is different between the clusters.
Copy your existing test cluster credentials into a separate file:
```
cp ~/.kube/config ~/.kube/config-test
```

Edit ~/.kube/config-test, and change the username in two places, from <firstname>.<lastname>@digital.justice.gov.uk to <firstname>.<lastname>@test, as shown below:

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

Merge the two config files together into a new config file and replace your old config with the new merged config:

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

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

For test:

kubectl config use-context test.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 23 July 2023. It needs to be reviewed again on 23 October 2023 by the page owner #cloud-platform .

This page was set to be reviewed before 23 October 2023 by the page owner #cloud-platform. This might mean the content is out of date.