The Cloud Platform CLI

The cloud platform cli is a command-line tool to help you work with the cloud platform.

The idea is to enable you to manage resources in your environment without always needing to craft your terraform or kubernetes yaml files by hand, and to simplify some common tasks (like checking the github teams in your kube config file).

Installation

The CLI tool is a single binary: cloud-platform.

If you’re on a Mac, you can install it using homebrew:

brew install ministryofjustice/cloud-platform-tap/cloud-platform-cli

Alternatively, install the binary into your $PATH (choose from the GitHub releases for your system):

# Mac - Intel
tar xzv -C /usr/local/bin/ -f <(curl -sL $(curl -sL https://api.github.com/repos/ministryofjustice/cloud-platform-cli/releases/latest | jq -r '.assets[] | select(.browser_download_url | match("darwin_amd64")) | .browser_download_url'))

# Mac - Apple Silicon - M1 etc
tar xzv -C /usr/local/bin/ -f <(curl -sL $(curl -sL https://api.github.com/repos/ministryofjustice/cloud-platform-cli/releases/latest | jq -r '.assets[] | select(.browser_download_url | match("darwin_arm64")) | .browser_download_url'))

# Linux - 64 bit
tar xzv -C /usr/local/bin/ -f <(curl -sL $(curl -sL https://api.github.com/repos/ministryofjustice/cloud-platform-cli/releases/latest | jq -r '.assets[] | select(.browser_download_url | match("linux_amd64")) | .browser_download_url'))

Checking your install

To check the CLI is installed, see if this runs successfully:

$ cloud-platform version

Keeping up to date

You should always use the latest version. To check, run:

$ cloud-platform version

If you’re not on the latest version, you’ll see this message:

Update required. Current version: 1.XX.X, Latest version: 1.YY.Y

To upgrade the cloud platform cli, if you installed it with homebrew:

brew update && brew upgrade cloud-platform-cli

Or if you installed the binary directly, for example at /usr/local/bin/cloud-platform, replace it with the latest binary by doing another install

Functions

This describes the current capabilities of the CLI tool.

Create an environment
Add an ECR to your namespace
Add an RDS to your namespace
Add an S3 Bucket to your namespace
Add a service account to your namespace
Check your kubernetes config file

Create an environment

Start from the root of a working copy of the environments repository
Create a new branch
Run cloud-platform environment create

You will be prompted to answer some questions about the environment (i.e. namespace) that you are creating. Once the process is complete, you will have a new namespace folder in your working copy.
git add and git commit the new files, and raise a PR

After the cloud platform team have approved your PR, please merge it, and your namespace will be created a few minutes later.

In order to access your environments you need to authenticate and use kubectl to connect to the cluster

The other cloud-platform environment ... commands, which manage resources in your namespace, all assume that your namespace conforms to the templates generated by this command.

Add an ECR to your namespace

Start from the root of a working copy of the environments repository
Create a new branch
cd into your namespace folder

Non production environment:

cd namespaces/live.cloud-platform.service.justice.gov.uk/<your-namespace>

Production environment:

cd namespaces/live-1.cloud-platform.service.justice.gov.uk/<your-namespace>

Run cloud-platform environment ecr create

This will create a resources/ecr.tf file in your working copy.
git add and git commit the new file, and raise a PR

After the cloud platform team have approved your PR, please merge it, and your ECR will be created a few minutes later.

When your ECR has been created, you will see a new kubernetes secret in your namespace called ecr-repo-[namespace name]. This secret contains the credentials you will need in order to use your ECR.

The CLI tool assumes you already have a resources/variables.tf file below your namespace folder, and that this defines all the variables which appear in the template ecr.tf file. If this is not the case, you may need to amend the generated file.

It also assumes you already have a resources/variables.tf, resources/main.tf and resources/versions.tf file below your namespace folder, and that this defines all the variables, provider declarations and configurations needed for the ecr.tf file. If this is not the case, you may need to amend those files by comparing with the template files

Add an RDS to your namespace

Start from the root of a working copy of the environments repository
Create a new branch
cd into your namespace folder

Non production environment:

cd namespaces/live.cloud-platform.service.justice.gov.uk/<your-namespace>

Production environment:

cd namespaces/live-1.cloud-platform.service.justice.gov.uk/<your-namespace>

Run cloud-platform environment rds create

This will create a resources/rds.tf file in your working copy.
git add and git commit the new file, and raise a PR

After the cloud platform team have approved your PR, please merge it, and your RDS will be created a little while later (it usually takes about 20 minutes for an RDS instance to be created).

When your RDS has been created, you will see a new kubernetes secret in your namespace called rds-postgresql-instance-output. This secret contains the credentials you will need in order to access your database.

The CLI tool assumes you already have a resources/variables.tf file below your namespace folder, and that this defines all the variables which appear in the template rds.tf file. If this is not the case, you may need to amend the generated file.

Add an S3 Bucket to your namespace

Start from the root of a working copy of the environments repository
Create a new branch
cd into your namespace folder

Non production environment:

cd namespaces/live.cloud-platform.service.justice.gov.uk/<your-namespace>

Production environment:

cd namespaces/live-1.cloud-platform.service.justice.gov.uk/<your-namespace>

Run cloud-platform environment s3 create

This will create a resources/s3.tf file in your working copy.
git add and git commit the new file, and raise a PR

After the cloud platform team have approved your PR, please merge it, and your S3 bucket will be created a little while later.

When your S3 bucket has been created, you will see a new kubernetes secret in your namespace called s3-bucket-output. This secret contains the credentials you will need in order to access your s3 bucket.

The CLI tool assumes you already have a resources/variables.tf file below your namespace folder, and that this defines all the variables which appear in the template s3.tf file. If this is not the case, you may need to amend the generated file.

Add a service account to your namespace

Start from the root of a working copy of the environments repository
Create a new branch
cd into your namespace folder

Non production environment:

cd namespaces/live.cloud-platform.service.justice.gov.uk/<your-namespace>

Production environment:

cd namespaces/live-1.cloud-platform.service.justice.gov.uk/<your-namespace>

Run cloud-platform environment serviceaccount create

This will create a resources/serviceaccount.tf file in your working copy.
git add and git commit the new file, and raise a PR

By default your service account name will be cd-serviceaccount. If you’d like to specify the name of your service account resource, you can define it in the serviceaccount_name terraform variable.

See the module documentation for more information about the options available.

After the cloud platform team have approved your PR, please merge it, and your service account resource will be created.

You can query your new resource using the command kubectl get serviceaccount -n <namespace>.

The CLI tool assumes you already have a resources/variables.tf, resources/main.tf and resources/versions.tf file below your namespace folder, and that this defines all the variables, provider declarations and configurations needed for the resources/serviceaccount.tf file. If this is not the case, you may need to amend those files by comparing with the template files

GitHub Actions Secrets

If you are using GitHub Actions for your deployment pipeline, the serviceaccount module can automatically manage GitHub Actions Secrets containing the certificate and token required to authenticate to the cluster and issue commands for your namespace.

In the resources/serviceaccount.tf file, you should see this section:

  # Uncomment and provide repository names to create github actions secrets
  # containing the ca.crt and token for use in github actions CI/CD pipelines
  # github_repositories = ["my-repo"]

To use this feature, uncomment the last line, and set the list of repositories in which you want the GitHub Actions Secrets to be created.

e.g. if you have two GitHub repositories in your project, called ministryofjustice/frontend and ministryofjustice/backend, you would change the last line to:

github_repositories = ["frontend", "backend"]

Once your PR is merged, those repositories should have secrets named: KUBE_CERT, and KUBE_TOKEN. You can use these secrets in your GitHub Actions pipelines.

See the module documentation for more information.

Check your kubernetes config file

You can use the CLI tool to verify the github teams listed in your id-token in your ~/.kube/config file. Missing github teams are sometimes a reason why people are unable to access objects in their namespaces.

To check your kube config id-token, run this command:

$ cloud-platform kubecfg id-token-claims

You should see output similar to this:

{
        "aud": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "email": "david@whatever.com",
        "email_verified": true,
        "exp": 9999999999,
        "https://k8s.integration.dsd.io/groups": [
                "github:webops",
                "github:technical-architects",
                "github:moj-cjse"
        ],
        "iat": 9999999999,
        "iss": "https://justice-cloud-platform.eu.auth0.com/",
        "name": "David Salgado",
        "nickname": "digitalronin",
        "picture": "https://avatars2.githubusercontent.com/u/2338?v=4",
        "sub": "github|2338",
        "updated_at": "2020-04-27T09:44:33.971Z"
}

The github teams are listed under https://k8s.integration.dsd.io/groups as above.

Base64 decode a kubernetes secret

cloud-platform decode-secret -n <namespace_name> -s <secret_name>

e.g.

cloud-platform decode-secret -n dstest -s rds-instance-output

{
    "apiVersion": "v1",
    "data": {
        "access_key_id": "AKIAXXXXXXXXXXXXXXXX",
        "database_name": "db2axxxxxxxxxxxxxx",
        "database_password": "xxxxxxxxxxxxxxxx",
        "database_username": "xxxxxxxxxx",
        "rds_instance_address": "cloud-platform-1111111111111111.cdwm328dlye6.eu-west-2.rds.amazonaws.com",
        "rds_instance_endpoint": "cloud-platform-1111111111111111.cdwm328dlye6.eu-west-2.rds.amazonaws.com:3306",
        "secret_access_key": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq",
        "url": "postgres://xxxxxxxxxx:XXXXXXXXXXXXXXXX@cloud-platform-1111111111111111.cdwm328dlye6.eu-west-2.rds.amazonaws.com:5432/db2axxxxxxxxxxxxxx"
    },
    "kind": "Secret",
    "metadata": {
        "creationTimestamp": "2020-06-19T13:43:31Z",
        "name": "rds-instance-output",
        "namespace": "dstest",
        "resourceVersion": "276902169",
        "selfLink": "/api/v1/namespaces/poornima-dev/secrets/rds-instance-output",
        "uid": "1f4243d8-ee57-4756-af09-5a8084a89988"
    },
    "type": "Opaque"
}

Export AWS Credentials

You can use the CLI to set AWS credentials as shell variables, to make it easier to access AWS resources from the command-line.

For example, if you want to run a command like aws rds describe-db-instances on your RDS instance, you first have to set these environment variables:

AWS_REGION - to “eu-west-2”
ACCESS_KEY_ID - to the value for your RDS instance
SECRET_ACCESS_KEY - to the value for your RDS instance

To make this easier, if you run decode-secret with the --export-aws-credentials flag (or -e for short), you will get output like this:

$ cloud-platform decode-secret -n dstest -s rds-instance-output -e
export AWS_REGION="eu-west-2"
export AWS_ACCESS_KEY_ID="XXXXXXXXXXXXXXXXXXXX"
export AWS_SECRET_ACCESS_KEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

If you wrap the command in eval, it will set the variables in your current shell, so you can do things like this:

$ eval(cloud-platform decode-secret -n dstest -s rds-instance-output -e)
$ aws rds describe-db-instances --db-instance-identifier=cloud-platform-xxxxxxxxxxxxxxxx

This page was last reviewed on 18 January 2022. It needs to be reviewed again on 18 April 2022 .

This page was set to be reviewed before 18 April 2022. This might mean the content is out of date.