Control_scripts.md

Control scripts

Table of contents

• General behavior
• Scripts
  • 🔁 init
    • Description
    • Sample implementation
  • ✨ create
    • Description
    • Execution example
    • Sample implementation
  • 🔧 update
    • Description
    • Execution example
    • Sample implementation
  • 🗃 archive
    • Description
    • Execution example
    • Sample implementation
  • ✅ check
    • Description
    • Execution example
    • Sample implementation
  • 🚮 cleanup
    • Description
    • Execution example
    • Sample implementation
  • 🗃✅ archive_check
    • Description
    • Execution example
    • Sample implementation
  • 🐋✅ tag_check
    • Description
    • Execution example
  • 👀 info
    • Description
    • Execution example
    • Sample implementation

General behavior

All control scripts receive input as CLI arguments. After executing the required logic they must finish with an exit code of 0 if no errors have occurred and the required actions have all completed. If there was an error and some steps were not executed, the script should exit with an exit code distinct from 0. Any non-zero exit code will indicate an error.

Everything the scripts write to stdout and stderr will be collected and stored. DevOps engineers can then view these logs from the octo CLI, should that be needed.

NOTE: Logs from check, archive_check and tag_check are not collected because they are called very often.

There are four arguments that are passed to all scripts. The first three arguments come from the Kubernetes ConfigMap:

• --project-name – the name of the project. It is supplied mostly for informational purposes and can be useful for sending notifications if that is necessary.
• --base-domain – the base domain. It can be useful for generating the URLs of deployments.
• --namespace – The namespace in which the deployment should be created.
• --name – The name of the deployment supplied in the Web UI. It can be useful for generating the deployment URL.

NOTE: If an argument is marked with a ⭐, it means that the argument can be passed any number of times.

Scripts

🔁 init

Description

This script is called once during the creation of the Octopod Server Kubernetes Pod to set up the proper environment to execute all other scripts.

It is guaranteed that this script will be called before any of the other scripts.

You could, for example, set up access to your version control system, cloud providers, etc. This can be achieved by saving the configuration into files in the $HOME directory.

Unlike all other scripts, this script receives no arguments.

Sample implementation

mkdir $HOME/.ssh
echo -e "Host github.com\nHostname github.com\nPort 22\nUser git\nIdentityFile $HOME/.ssh/deploy.key" > $HOME/.ssh/config
echo "MY_DEPLOY_KEY" > $HOME/.ssh/deploy.key"

✨ create

Description

Creates a new deployment in the Kubernetes cluster.

This script receives the following additional command-line arguments as input:

• --tag – The Docker Image tag that should be deployed. (In practice you can use some other string that identifies a version of your system to deploy – you will need to process it accordingly in the script.)
• --app-env-override ⭐ – App-level overrides. These overrides should be passed to the server being deployed. These overrides are specified in the Web UI. They are passed in the format of KEY=VALUE pairs.
• --deployment-override ⭐ – Deployment-level overrides. These overrides should be used to set up the deployment environment itself, rather than be passed to the server being deployed. These overrides are specified in the Web UI. They are passed in the format of KEY=VALUE pairs.

Execution example

The script might be called something like this:

create --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button" --tag "c9bbc3fcc69e5aa094bca110c6f79419ab7be77a" --app-env-override "EMAIL_TOKEN=123123" --app-env-override "SECRET_BUTTON_ENABLED=True" --deployment-override "FANCY_DATABASE=True"

Sample implementation

helm upgrade --install --namespace "$namespace" "$name" "$deployment_chart" \
    --set "global.project-name=$project_name" \
    --set "global.base-domain=$base-domain" \
    --set "app.tag=$tag" \
    --set "app.env.foo=$app_env_override_1" \
    --set "app.bar=$deployment_override_1" \
    --wait \
    --timeout 300

🔧 update

Description

Updates a deployment in Kubernetes to a new Docker Image tag.

This script receives the same additional command-line arguments as create:

• --tag – The Docker Image tag that should be deployed. (In practice you can use some other string that identifies a version of your system to deploy – you will need to process it accordingly in the script.)
• --app-env-override ⭐ – App-level overrides. These overrides should be passed to the server being deployed. These overrides are specified in the Web UI. They are passed in the format of KEY=VALUE pairs.
• --deployment-override ⭐ – Deployment-level overrides. These overrides should be used to set up the deployment environment itself, rather than be passed to the server being deployed. These overrides are specified in the Web UI. They are passed in the format of KEY=VALUE pairs.

Execution example

The script might be called something like this:

update --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button" --tag "c9bbc3fcc69e5aa094bca110c6f79419ab7be77a" --app-env-override "EMAIL_TOKEN=123123" --app-env-override "SECRET_BUTTON_ENABLED=True" --deployment-override "FANCY_DATABASE=True"

Sample implementation

helm upgrade --install --namespace "$namespace" "$name" "$deployment_chart" \
    --set "global.project-name=$project_name" \
    --set "global.base-domain=$base-domain" \
    --set "app.tag=$tag" \
    --set "app.env.foo=$app_env_override_1" \
    --set "app.bar=$deployment_override_1" \
    --wait \
    --timeout 300

🗃 archive

Description

"Archives" a deployment. This script should only free the computational resources used by the deployment ― it should remove the Kubernetes Pods, but not remove any Persistent Volumes associated with the deployment. It is done this way to provide a period of time in which the user can recover a deployment in the state it was in.

Deleting the Persistent Volume Claims should be done in the cleanup script.

This script should in some sense be the inverse of create (up to Persistent Volumes).

This script receives only the default command-line arguments as input.

Execution example

The script might be called something like this:

archive --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button"

Sample implementation

helm delete "$name" --purge

✅ check

Description

This script checks the status of the deployment.

If the script exits with 0, it means that the deployment is healthy and up. If the script exits with a non-zero exit code, it means that the deployment is not healthy or down.

This script receives only the default command-line arguments as input.

Execution example

The script might be called something like this:

check --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button"

Sample implementation

echo "{\"Deployments\": [{\"ResourceName\": \"app-${name}\", \"Namespace\": \"${namespace}\"}], \"StatefulSets\": [{\"ResourceName\": \"db-${name}\", \"Namespace\": \"${namespace}\"}]}" | \
    kubedog multitrack -t 3

🚮 cleanup

Description

Cleans up any persistent resources a deployment might have allocated, such as Persistent Volumes.

This script will always be called after archive has been called on the given deployment.

This script receives only the default command-line arguments as input.

Execution example

The script might be called something like this:

cleanup --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button"

Sample implementation

kubectl delete pvc -n $namespace -l "app=$name"

🗃✅ archive_check

Description

This script checks that a given deployment really has been archived and is no longer running.

If the scripts exits with 0, it means that the deployment has been archived successfully. If the script exits with a non-zero exit code, it means that the deployment has not been archived.

This script receives only the default command-line arguments as input.

Execution example

The script might be called something like this:

archive_check --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button"

Sample implementation

helm status $name

🐋✅ tag_check

Description

This script is called right before create and update scripts to check that a given Docker Image tag exists. This can be useful since it can be very easy to make a typo in the Docker Image tag and deployments are typically not instant. Implementing this script would allow the user of the Web UI to instantly get an error specifically about a wrong Docker Image tag.

This script receives the following additional command-line arguments as input:

• --tag – The Docker Image tag that should be checked.

Execution example

The script might be called something like this:

tag_check --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button" --tag "c9bbc3fcc69e5aa094bca110c6f79419ab7be77a"

👀 info

Description

This script returns user-facing metadata about a deployment. Currently, the metadata consists of URLs that are relevant for the deployment. Things like the deployment URL, the URL to view logs, and the database URL.

The script should return the metadata as a two-column CSV table:

app,https://foo.example.com
api,https://api.foo.example.com

This script receives only the default command-line arguments as input.

Execution example

The script might be called something like this:

info --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button"

Sample implementation

echo "app,https://${name}.example.com"
echo "api,https://api.${name}.example.com"