How apps are deployed
We deploy a GOV.UK app to the GOV.UK Kubernetes platform as a set of Kubernetes resources.
Examples of resources include a deployment, a service, or an ingress. A deployment resource creates Pods that run the underlying app containers.
Helm charts group and describe Kubernetes resources. We define and store GOV.UK app Helm charts in the govuk-helm-charts repo.
We use Argo CD to automate the deployment of our Helm charts.
Argo CD does not use the Helm tool to interact with the Kubernetes cluster. Argo CD instead uses the Helm template to generate a set of resource configurations and applies the changes to the cluster directly.
Argo CD continuously monitors Kubernetes and the govuk-helm-charts repo to make sure they stay in sync. The govuk-helm-charts repo is the source of truth.
An Argo Application represents a deployed Helm chart in a particular environment. We define an Argo Application for each of the GOV.UK apps.
Each of these Argo Applications are created and managed by a parent Argo Application. This is known as an App of Apps.
In the govuk-helm-charts repo, the app-config Helm chart defines the Argo Application that defines our other Argo Applications.
Deploying a release of a GOV.UK app
A release is a tagged commit that represents a deployable version of the code for an app. Typically, the continuous integration (CI) pipeline will build a container image for that release and tag the image with the associated Git commit simple hashing algorithm (SHA).
The deployment process is as follows.
To manually deploy a release, you update the image tag reference in the
govuk-helm-chartsrepo.An Argo CD PreSync hook pre-compiles the assets and uploads them to S3 as a Kubernetes Job. This PreSync hook occurs before the main Sync operation that updates the application containers.
A Kubernetes Job runs database migration as part of the Sync operation.
We do not guarantee the database migrations will occur before the new containers access the database. As best practice database migrations should be forward and backwards compatible by one version.
Argo CD updates the Kubernetes deployment with the new image tag. Kubernetes then co-ordinates the deployment by creating new application containers using the new image tag and cleans up the old containers.
After the Sync operation, Argo CD triggers the post-sync Argo Workflow to run end-to-end tests for the app.
Continuous deployment of a release of a GOV.UK app
The continuous deployment (CD) process is an automatic deployment process. A release of a GOV.UK app triggers the CD process, for example when we merge a pull request.
A new release is automatically generated by our continuous integration (CI) pipeline when a user or process adds a new successful commit to the main branch. GitHub Actions creates a GitHub release with a version number.
Then GitHub Actions builds the new image and pushes that new image to GitHub Container Registry (GHCR) and calls the deploy-image Argo Workflow.
Argo Workflows then updates the image tag value for integration in the govuk-helm-charts repo for the new release.
Argo CD automatically deploys the new release to the integration environment and then runs the end-to-end tests for the app in integration.
If the end-to-end tests are successful in integration and if promoting to the next environment is enabled then the post-sync Argo Workflow will continue and call the deploy-image Argo Workflow for the next environment. Argo CD deploys the release to the staging environment and runs end-to-end tests in staging.
If the end-to-end tests are successful in staging and if promoting to the next environment is enabled then the post-sync Argo Workflow will continue and call the deploy-image Argo Workflow for the next environment. Argo CD deploys the release to the production environment and runs the end-to-end test in production.
When the deploy-image Argo Workflow updates the image tag value, it creates and merges a branch into the main branch for the govuk-helm-charts repo without raising a pull request.
Join the #govuk-deploy-alerts Slack channel to get a notification when an app is deployed and whether the deployment succeeded or failed.
If your app deployment failed, you should check the Argo CD logs to see why.
Check the Argo CD logs
You must sign into Argo CD to view the Argo CD logs.
The environment you need to sign into depends on where the app deployment failed.
Check the Argo CD integration environment
If your app deployment failed in integration, sign into the Argo CD integration environment using your GitHub account.
To sign into integration, your GitHub account must be part of the GOV.UK team on alphagov.
Check the Argo CD staging and production environments
If your app deployment failed in staging or production, sign into the Argo CD staging environment or Argo CD production environment using your GitHub account.
To sign into staging or production, your GitHub account must be part of the GOV.UK production team on alphagov.
See the documentation on getting production access for more information.