Cloud Platform CLI

The Cloud Platform Command Line Interface (CLI) lets you create and manage Cloud Platform namespaces and resources directly from the terminal, without needing to manually write Kubernetes YAML files or Terraform.

It also simplifies some common tasks that are needed to interact with the Cloud Platform.

Installing the Cloud Platform CLI

Homebrew

You can install the Cloud Platform CLI via Homebrew:

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

Manual installation

If you don’t use Homebrew, you can manually install the Cloud Platform CLI.

macOS

Intel (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("darwin_amd64")) | .browser_download_url'))

Apple Silicon (M1, M2, 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'))

Verify your installation

To check the Cloud Platform CLI has installed correctly, you can run:

$ cloud-platform version

Keeping up to date

To check if you’re using the latest version of Cloud Platform CLI, you can run:

$ cloud-platform version

If you installed the Cloud Platform CLI using Homebrew, you can run:

$ brew update && brew upgrade cloud-platform-cli

If you installed the Cloud Platform CLI using a different method, reinstall the CLI by following the Manual installation instructions.

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

Send a message to the #ask-cloud-platform channel to ask for a review of the 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

cd namespaces/live.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

cd namespaces/live.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

cd namespaces/live.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

cd namespaces/live.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 10 February 2023. It needs to be reviewed again on 10 May 2023 .

This page was set to be reviewed before 10 May 2023. This might mean the content is out of date.