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.