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 written in golang, and packaged as a single cloud-platform binary. You can get the latest version from the releases page of the github repository. Download whichever tarball is appropriate for your development environment, unpack it and put the cloud-platform binary somewhere on your $PATH

If you’re on a Mac, you can do this by running the following commands:

LATEST=$(curl --silent https://github.com/ministryofjustice/cloud-platform-cli/releases/latest | sed 's/.*releases.tag.\(.*\)".*/\1/')
TARBALL="cloud-platform-cli_${LATEST}_darwin_amd64.tar.gz"
wget https://github.com/ministryofjustice/cloud-platform-cli/releases/download/${LATEST}/${TARBALL}
tar xzf ${TARBALL}
mv cloud-platform /usr/local/bin
rm ${TARBALL}

or use Homebrew:

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

After this, you should be able to run:

$ cloud-platform version

…to confirm that your installation is working.

Keeping up to date

The cloud-platform binary will attempt update itself whenever it detects a new version. If you installed it via brew then it’ll be kept up to date when you run brew update/upgrade.

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.

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
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.

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
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-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
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. 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
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 cloud-platform-user. 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>.

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 11 May 2021. It needs to be reviewed again on 11 August 2021 .

This page was set to be reviewed before 11 August 2021. This might mean the content is out of date.