prerequisite-secrets.md

Prerequisite secrets

The platform requires some prerequisite secrets to fully function. We store these secrets in AWS Secret Manager, using the Kubernetes External Secrets Operator

The secrets listed here are either:

1. generated by external systems and imported into our platform, for example GitHub OAuth secrets; or
2. generated manually and used between different components of our platform; for example OAuth shared secret between ArgoCD (continuous delivery tool) and Dex (federated OpenID Connect provider). We don't have a method yet to auto-generate these
3. GOV.UK app specific secrets, referred to in the app-config helm chart of the govuk-helm-charts GitHub repository. These are usually copied across from govuk-secrets

You can list the canonical source of all the required platform secrets in the govuk-helm-charts GitHub repository.

The purpose of this document is to give information about:

1. how to generate/obtain these secrets
2. the JSON format used when adding the secrets to AWS Secret Manager

The format of a secret (given after) will aid you in creating one from scratch:
name of the secret in AWS Secrets Manager: description

{
  <key_1>: <secret_1>,
  <key_2>: <secret_2>
}

In addition, there are:

Externally generated platform secrets

1. govuk/dex/github: shared OAuth secret between Dex and GitHub. Created via GitHub admin portal.

   {
     "clientID": "<secret_1>",
     "clientSecret": "<secret_2>"
   }
   

2. govuk/logit-host: used by FileBeat in Kubernetes cluster to access the Logit stack. Obtained from the Logit portal.

{
  "host": "<secret_1>",
  "port": "<secret_2>
}

3. govuk/slack-webhook-url: Slack URL used to post on Slack channel #govuk-deploy-alerts. Obtained from GDS/CO IT, who manage Slack.

{
  url": "<secret_1>"
}

4. govuk/alertmanager/pagerduty-routing-key: routing key used to access PagerDuty.

Obtained from the Integration Key value of the Events API V2 integrations for the service in PagerDuty.

<secret_1>

Manually generated platform secrets

1. govuk/dex/argocd: shared OAuth secret between Dex and ArgoCD. You can generate it manually using OpenSSL; for example openssl rand -hex 16.

   {
     "clientID": "<secret_1>",
     "clientSecret": "<secret_2>"
   }
   

2. govuk/dex/argo-workflows: shared OAuth secret between Dex and Argo-workflows. You can generate it manually using OpenSSL; for example openssl rand -hex 16.

   {
     "clientID": "<secret_1>",
     "clientSecret": "<secret_2>"
   }
   

3. govuk/dex/grafana: shared OAuth secret between Dex and Grafana. You can generate it manually using OpenSSL; for example openssl rand -hex 16.

   {
     "clientID": "<secret_1>",
     "clientSecret": "<secret_2>"
   }
   

4. govuk/dex/alert-manager: shared OAuth secret between Dex and Alertmanager. You can generate it manually using OpenSSL; for example openssl rand -hex 16.

   {
     "clientID": "<secret_1>",
     "clientSecret": "<secret_2>",
     :cookieSecret": "<secret_3>"
   }
   

5. govuk/dex/prometheus: shared OAuth secret between Dex and Alertmanager. You can generate it manually using OpenSSL; for example openssl rand -hex 16.

{
  "clientID": "<secret_1>",
  "clientSecret": "<secret_2>",
  cookieSecret: <secret_3>
}

6. govuk/fastly/api: The Fastly exporter uses this in Kubernetes to scrape Fastly metrics. The secret gets created in the Fastly management web console, using a the API key belonging to a user account which has access only to the Fastly service associated with a particular GOV.UK environment.

   {
     "token": "<secret_1>"
   }
   

7. govuk/github/govuk-ci: used by ArgoCD to access GOV.UK GitHub repositories. Created via GitHub portal of user govuk-ci.

   {
     "token": "<secret_1>",
     "username": "govuk-ci"
   }