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
Note: This only works if Homebrew is installed on your computer, please visit Homebrew home page for up-to-date instructions on how to install it.
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
andgit 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
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
andgit 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 templateecr.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
andresources/versions.tf
file below your namespace folder, and that this defines all the variables, provider declarations and configurations needed for theecr.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
andgit 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 templaterds.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
andgit 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 templates3.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
andgit 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
andresources/versions.tf
file below your namespace folder, and that this defines all the variables, provider declarations and configurations needed for theresources/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