Last updated: 14 May 2025

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:
- fulladmin: has read-write “cluster-admin” access to everything in the cluster, across all namespaces, including secrets
- developer: has read-write access to most things in the apps and datagovuk namespaces, but cannot view or modify secrets
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> is integration, staging, or production
- <role> is developer, or fulladmin

Note: About using the correct role

You should always assume the correct role for the job. For the majority of tasks, you should try to assume the developer role first.

Only “Production Admin” users can assume the fulladmin role, and should only do so if they have proven the developer role is insufficient. Usage of the fulladmin role is monitored and may cause a notification to be raised in 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 set name to govuk-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> is integration, staging, or production
- <role> is fulladmin or developer
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.