6All _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.
8Control scripts can be roughly split into two categories: (1) control scripts involved in the deployment lifecycle and (2) service control scripts which handle everything else.
10## Deployment lifecycle scripts
12_stdout_ and _stderr_ output from the most important scripts involved in the deployment lifecycle will be collected and stored. DevOps engineers can then view these logs from the _octo CLI_, should that be needed.
14All of the _scripts_ in this category receive the exact same set of command line arguments.
16There are four "static" arguments that are passed to all *scripts* in this category. The first three arguments come from the [_Kubernetes ConfigMap_][configmap]:
17* `--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.
18* `--base-domain` – the base domain. It can be useful for generating the URLs of deployments.
19* `--namespace` – The namespace in which the deployment should be created.
20* `--name` – The name of the deployment supplied in the _Web UI_. It can be useful for generating the deployment URL.
22Additionally, _scripts_ in this category receive the deployment configuration – a set of key/value pairs. There are two types of configurations that can be set from the _Web UI_: deployment
23configuration and application configuration.
25Both types of configurations can have any number of key/value pairs. Every pair is passed a separate command line argument:
27* `--application-config <KEY>=<VALUE>` represents an application configuration key/value pair.
28* `--deployment-config <KEY>=<VALUE>` represents an deployment configuration key/value pair.
30Any of these two command line arguments can be passed any number of times.
32So, a _script_ might be called something like this:
35create --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button" --application-config "EMAIL_TOKEN=123123" --application-config "SECRET_BUTTON_ENABLED=True" --deployment-config "FANCY_DATABASE=True"
42Creates a new deployment in the _Kubernetes_ cluster.
44#### Sample implementation
47helm upgrade --install --namespace "$namespace" "$name" "$deployment_chart" \
48 --set "global.project-name=$project_name" \
49 --set "global.base-domain=$base-domain" \
50 --set "app.tag=$tag" \
51 --set "app.env.foo=$app_env_override_1" \
52 --set "app.bar=$deployment_override_1" \
61This script is called right before [`create`](#-create) and [`update`](#-update) scripts to check that the given set of arguments is valid input for other commands. This is run synchronously and the _stdout_ text is report to the user in the _Web UI_. This means that the command should run relatively fast. You can check thing like that the needed arguments are present and that the required docker tags exist in the docker registry.
63As with other commands, exit code `0` indicates that everything is fine and a non-zero exit code indicates that something is wrong and _stdout_ should be shown to the user.
69This 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.
71The script should return the metadata as a two-column CSV table to _stdout_:
74app,https://foo.example.com
75api,https://api.foo.example.com
78#### Sample implementation
81echo "app,https://${name}.example.com"
82echo "api,https://api.${name}.example.com"
88Updates a deployment in _Kubernetes_ to a new *Docker Image tag*.
90#### Sample implementation
93helm upgrade --install --namespace "$namespace" "$name" "$deployment_chart" \
94 --set "global.project-name=$project_name" \
95 --set "global.base-domain=$base-domain" \
96 --set "app.tag=$tag" \
97 --set "app.env.foo=$app_env_override_1" \
98 --set "app.bar=$deployment_override_1" \
107"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.
109Deleting the _Persistent Volume Claims_ should be done in the [`cleanup`](#-cleanup) script.
111This script should in some sense be the inverse of [`create`](#-create) (up to _Persistent Volumes_).
113A good way of doing this is to scale the number of replicas of your server to 0.
115#### Sample implementation
118helm delete "$name" --purge
125This command should undo whatever the [`archive`](#-archive) command did. So, if the [`archive`](#-archive) command scaled the server to 0 replicas, this command should scale it back up to the number of replicas required for normal operation.
131This script checks the status of the deployment.
133If 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.
135You can specify exactly what error occured using exit codes:
136- `1` – a generic failure.
137- `2` – the deployment is partially down (some containers are unhealthy).
138- `3` – tag mismatch, the deployment has not been updated to the expected version.
140#### Sample implementation
143echo "{\"Deployments\": [{\"ResourceName\": \"app-${name}\", \"Namespace\": \"${namespace}\"}], \"StatefulSets\": [{\"ResourceName\": \"db-${name}\", \"Namespace\": \"${namespace}\"}]}" | \
144 kubedog multitrack -t 3
151Cleans up any persistent resources a deployment might have allocated, such as _Persistent Volumes_.
153This script will always be called **after** [`archive`](#-archive) has been called on the given deployment.
155#### Sample implementation
158kubectl delete pvc -n $namespace -l "app=$name"
165This script checks that a given deployment really has been archived and is no longer running.
167If 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.
169#### Sample implementation
175## Service control scripts
181This script is called **once** during the creation of the `Octopod Server` *Kubernetes Pod* to set up the proper environment to execute all other scripts.
183It is guaranteed that this script will be called **before** any of the other scripts.
185You 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.
187Unlike all other scripts, this script receives no arguments.
189#### Sample implementation
193echo -e "Host github.com\nHostname github.com\nPort 22\nUser git\nIdentityFile $HOME/.ssh/deploy.key" > $HOME/.ssh/config
194echo "MY_DEPLOY_KEY" > $HOME/.ssh/deploy.key"
201This script gets called every time a deployment changes its status (apart from creation and deletion). It might be useful if you want to send notifications about certain deployment status transitions. The complete list of statuses and their transitions can be found in the [technical architecture document](Technical_architecture.md#️-deployment-state-transitions).
203It is optional and can be omitted altogether.
205This script receives the following additional command-line arguments as input:
206* `--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.
207* `--base-domain` – the base domain. It can be useful for generating the URLs of deployments.
208* `--namespace` – The namespace in which the deployment should be created.
209* `--name` – The name of the deployment supplied in the _Web UI_. It can be useful for generating the deployment URL.
210* `--old-status` – The previous status the deployment was in.
211* `--new-status` – The new status the deployment transitioned to.
213The last two arguments can have one of the following values:
217- `PartialAvailability`
224#### Execution example
226The script might be called something like this:
229notification --project-name "Cactus store" --base-domain "cactus-store.com" --namespace "cactus" --name "orange-button" --old-status "UpdatePending" --new-status "Running"
232### 🎛🔧 deployment_config
236This script is used to generate default deployment configuration key/value pairs. This configuration is shown to the user in the _Web UI_ with the ability to modify it.
238The key/value pairs are read from the _stdout_ stream of the script. It should be formatted as a CSV file with two columns.
240This script receives the following arguments:
242* `--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.
243* `--base-domain` – the base domain. It can be useful for generating the URLs of deployments.
244* `--namespace` – The namespace in which the deployment should be created.
246#### Sample implementation
250echo "application_api_version,1.0"
253### 🎛🔧🔑 deployment_config_keys
257This script is used to get the set of keys that the deployment configuration can have. This is useful to suggest possible values when the user wants to add new values to in the _Web UI_.
259The keys are read from the _stdout_ stream of the script. It should be formatted as a CSV file with one column (a list separated by newlines).
261This script receives the same arguments as the [`deployment_config`](#-deployment_config) command.
264#### Sample implementation
268echo "application_api_version"
269echo "database_version"
272### 🎛📱 application_config
276This script is used to generate default application configuration key/value pairs. This configuration is shown to the user in the _Web UI_ with the ability to modify it.
278The key/value pairs are read from the _stdout_ stream of the script. It should be formatted as a CSV file with two columns.
280This script receives the same arguments as the [`deployment_config`](#-deployment_config) command.
282Additionally, the script receives the deployment configuration key/value pairs as described in the ["Deployment lifecycle scripts" section](#deployment-lifecycle-scripts): any number of `--deployment-config <KEY>=<VALUE>` arguments.
284#### Sample implementation
288echo "application_api_version,1.0"
291### 🎛📱🔑 application_config_keys
295This script is used to get the set of keys that the application configuration can have. This is useful to suggest possible values when the user wants to add new values to in the _Web UI_.
297The keys are read from the _stdout_ stream of the script. It should be formatted as a CSV file with one column (a list separated by newlines).
299This script receives the same arguments as the [`application_config` script](#-application_config).
301#### Sample implementation
305echo "application_api_version"
306echo "database_version"
312 <i>Star the project of you like it</i>
315<p align="center"><a href="https://typeable.io"><img src="../../img/typeable_logo.svg" width="177px"></img></a></p>
317[configmap]: https://kubernetes.io/docs/concepts/configuration/configmap/
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list