⚠️ When merging pull requests, use the gds-cli: gds git merge-sign alphagov/paas-cf PR_NUMBER ⚠️

GOV.UK Platform as a Service (PaaS) CF creates a deployment of Cloud Foundry (CF) on VMs for GOV.UK PaaS. It builds upon the foundations laid out in paas-bootstrap and it handles the following non-exhaustive list of duties:

• Deploying CF using Concourse
• Configuring CF based on cf-deployment
• Provisioning AWS resources using Terraform. This includes
  • load balancers
  • databases
  • IAM roles and policies
  • DNS records
  • networking
  • S3 buckets
• Configuring Prometheus based on prometheus-boshrelease
• Running continuous platform-level tests
• Deploying and configuring our different service brokers (for example, the RDS broker and Aiven broker)

It does not include the AWS IAM roles which are assumed by different system components. Those are created in the account wide terraform (private repository).

1. What does paas-cf contain?
2. Deploying a new environment
3. Cloud Foundry deployment configuration options
4. Accessing Concourse
5. Finding configuration
6. Utility Scripts

paas-cf separates the responsibility for configuring, deploying, running, and monitoring Cloud Foundry, from those responsibilities held by paas-bootstrap.

This repository does not itself contain the code that runs in an environment (for the most part), but instead serves to compose the different pieces into a cohesive whole. As a result, it contains a variety of pieces that tell only part of the story. The table under the heading Finding configuration outlines some key directories and their purposes.

At a very high level, the create-cloudfoundry Concourse pipeline generates a Bosh manifest which describes the virtual machines and their networking which make up the Cloud Foundry deployment, as well as the software which runs on each machine. The manifest is then submitted to the Bosh director configured in paas-bootstrap.

Before you can get a Cloud Foundry deployment up and running, you will need the following available

• A running deployer-concourse instance from paas-bootstrap
• Make
• Ruby >= 2.7
• GDS CLI
• Access to paas-credentials (private repository) and tools installed
• Connection to GDS VPN
• Permission to assume the Admin role of the relevant AWS account (dev, ci, staging, production)
• AWS_DEFAULT_REGION environment set the desired region for the environment
• cf CLI >=7

These instructions contain placeholders where the exact command may vary. The below table explains the purpose of those placeholders:

1. Log in to CredHub in the environment by running this and following the instructions on screen. This will take you into a new shell session.

   gds aws paas-$ACCOUNT-admin -- make $ENV credhub

2. Upload the secrets to CredHub from the CredHub shell session.

   make $ENV upload-all-secrets

   Note: you do not need to use GDS CLI here because the CredHub shell session contains the AWS credentials in environment variables

3. Exit the CredHub shell session

4. Deploy the pipeline configurations using make. This will upload or update the pipelines. Select the target based on which AWS account you want to work with:

   gds aws paas-$ACCOUNT-admin -- make $ENV pipelines

5. Log in to Concourse. See the Accessing Concourse.

6. Tun the generate-paas-admin-git-keys, generate-paas-billing-git-keys and generate-paas-aiven-broker-git-keys jobs in the job group operator. This will generate and store some SSH keys needed by other jobs.

7. Run the create-cloudfoundry pipeline, starting from the left-hand pipeline-lock job. This will configure and deploy Cloud Foundry. It might take a couple of hours to complete.

There are a handful of configuration options which can change a Cloud Foundry deployment which can only be set at pipeline level. Each of the properties in the below table should be set as Make variables when setting the pipelines:

gds aws paas-$ACCOUNT-admin -- make $ENV pipelines VAR=value

Once deployed, Concourse can be accessed from the URLs below. By default, authentication with Github is enabled.

Non-development URLs are also accessible via the gds paas open command.

The following table outlines some important directories in the repository, their purpose, and when you might need to look in them.

Configure the POLICY_NAME variable within the Makefile with the name of the Permissions Boundary policy that you wish to add to the paas-s3-broker users.

Run this command to add a permissions boundary to paas-s3-broker users:

gds aws paas-<ENV-ROLE> -- make <BUILD_ENV> add_permissions_boundary_to_existing_s3_broker_users ARGS="<--dry-run>"

Replace:

• <ENV-ROLE> with the environment and role that you want to use e.g. prod-admin.
• <BUILD_ENV> with the environment that you want to update e.g. prod-lon.
• Only use the --dry-run flag if you would like the script to run but not change anything.

If the command is successful, the output will look similar to this:

Dry run? false
Policy attached to user: paas-s3-broker-dev05-0a094c73-7ae7-42cc-b028-6c78b93985d7
Policy attached to user: paas-s3-broker-dev05-dad332ff-3557-4f13-a768-5dc0e8421cd4