Access a GOV.UK EKS cluster
There are 3 GOV.UK clusters: integration, staging and production. These correspond to the integration, staging and production GOV.UK environments, which belong to the integration, staging and production AWS accounts respectively.
Prerequisites
This document assumes that you have already followed the steps in Get started developing on GOV.UK.
Obtain AWS credentials for your role in the cluster’s AWS account
Choose the AWS IAM role that you will use to access the cluster:
readonly
: has read-only access to AWS and the Kubernetesapps
anddatagovuk
namespaces. In AWS, access to secrets and objects in S3 is not granted.developer
: has read-write access to most things in theapps
anddatagovuk
namespaces, and can read the value of secrets with the2ndline/
orgovuk/
prefixes. It cannot modify the secrets in any way.fulladmin
: has read-write “cluster-admin” access to everything in the cluster, across all namespaces, including secretsplatformengineer
: also has read-write “cluster-admin access to everything in the cluster, across all namespaces, including secrets, but can be used by Platform Engineers on a regular basis without requiring an approval process
Obtain AWS credentials using
gds-cli
for the desired GOV.UK environment and role:eval $(gds aws govuk-<govuk-environment>-<role> -e --art 8h) export AWS_REGION=eu-west-1
where:
<govuk-environment>
isintegration
,staging
, orproduction
<role>
isdeveloper
, orfulladmin
Note: About using the correct role
You should always assume the correct role for the job. By default, you should use the readonly
role because it will give you access to all the information you need, without elevated privileges. If your task will require you to restart a pod or deployment, for example, you can use the developer
role. Platform Engineers may use the platformengineer
role if they need to perform actions in the EKS cluster that require "Cluster Admin” permissions but don’t need Admin access to other AWS services.
Only “Platform Engineer” and “Production Admin” users can assume the fulladmin
role, and should only do so if they have proven the developer
or platformengineer
roles are insufficient. Usage of the fulladmin
role is monitored and may cause an alert to be raised in the future.
Access a cluster for the first time
If it’s your first time accessing the cluster through kubectl, add the
govuk
cluster to your kubectl configuration in~/.kube/config
:aws eks update-kubeconfig --name govuk
To make it easier to switch between clusters, namespaces or users, you can rename the new context to match the name of the environment:
Edit the
name
field of the last context in~/.kube/config
. For example, for the staging environment you could setname
togovuk-staging
.See the Kubernetes documentation on configuring access to multiple clusters for more information.
Set the current context:
kubectl config use-context <govuk-environment>
Where
govuk-environment
is the name of the context from step 2.Set the default namespace
kubectl config set-context --current --namespace=apps
Check that you can access the cluster:
kubectl get deploy/frontend
You should see output similar to:
NAME READY UP-TO-DATE AVAILABLE AGE frontend 2/2 2 2 399d
Access a cluster that you have accessed before
To switch to a cluster that you have previously configured in ~/.kube/config
as above:
Obtain AWS credentials using
gds-cli
for the desired GOV.UK environment and role:eval $(gds aws govuk-<govuk-environment>-<role> -e --art 8h) export AWS_REGION=eu-west-1
where:
<govuk-environment>
isintegration
,staging
, orproduction
<role>
isreadonly
,developer
,fulladmin
orplatformengineer
Switch to the corresponding kubectl context:
kubectl config use-context <govuk-environment>
You can list the available contexts by running:
kubectl config get-contexts
Working with multiple clusters at once
If you are working between multiple clusters, you may choose to use the GDS CLI and Kubectl commands like this:
gds aws govuk-[environment]-developer -- kubectl --context govuk-[environment] -n apps get pods
With this, you won’t need to keep exporting and juggling different AWS credentials when swapping back and forth between environments or clusters.