Last updated: 24 Feb 2024

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:

- `admin`: has read-write access to everything in the cluster, including secrets
- `poweruser`: has read-write access to everything in the `apps` namespace, but cannot view or modify secrets
- `readonly`: can read everything in the `apps` namespace, except for 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 admin, poweruser, or readonly

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 admin, poweruser, or readonly
Switch to the corresponding kubectl context:
```
 kubectl config use-context <govuk-environment>
```
You can list the available contexts by running:
```
 kubectl config get-contexts
```