Table of contents
The main goal of Octopod is to simplify deployment in Kubernetes.
When developing Octopod we were expecting Octopod itself to also be deployed with Kubernetes.
Users can interact with Octopod through:
- the Web UI (expected to be used by developers, project managers, QA engineers, etc.)
- the octo CLI (expected to be used by DevOps engineers and programmatically, e. g. on CI)
Interaction between Octopod and Kubernetes is done entirely through the control scripts. This allows Octopod to be adapted for use in practically any deployment setup.
Octopod stores all data about deployments and all performed operations in PostgreSQL.
Web UI – the user interface used to manipulate deployments. It interacts with Octopod Server through HTTP/1.1 requests and receives events from Octopod Server through Websockets. Authentication between Web UI and Octopod Server is done through Basic Auth. The Basic Auth token is read from a JSON config which is requested when the page is loaded. Access to the config should be configured through Ingress.
The interface does not contain technical details related to administering deployments ― managing deployments is done in a simple way. The interface is geared towards being used by developers of any level, QA engineers, project managers, and people without a technical background.
Octopod Server – the server that processes deployment management requests and delegates Kubernetes-specific logic to control scripts.
The server receives commands from the octo CLI and the Web UI through HTTP/1.1 and updates the state of deployments. The server also sends updates to the Web UI through Websockets. Octopod Server interacts with Kube API Server through the control scripts. Settings, deployment states and user action logs are stored in PostgreSQL.
PostgreSQL – DBMS used to store settings, deployment states and user action logs.
octo CLI – a command-line interface used to manage deployments. It sends HTTP/1.1 requests to Octopod Server. The requests are authenticated through SSL certificates.
It can perform all actions available in the Web UI, but also has access to view deployment logs.
The CLI is expected to be used by DevOps engineers, but can also be used if it is necessary to automate deployment management in some way, for example in CI scripts.
Control scripts – a Docker Container with executables which encapsulates all of the logic of interacting with the Kube API Server, cloud providers, deployments, version control, etc.
This is necessary to make Octopod itself independent from any particular deployment setup ― it can be set up to work with practically any setup.
When the Octopod Server Pod starts, the contents of the control scripts container are copied into the Octopod Server container file system. This means that the executables need to be either statically linked or interpreted through Bash since it needs to be executed in the Octopod Server container environment.
These scripts need to be implemented to deploy Octopod.
Clean Archive CronJob – a CronJob which is run every hour. It deletes archived deployments older than 14 days. It is done by calling octo CLI.
It is necessary because "deleting" (archiving) deployments should only free the occupied computational resources, Persistent Volumes should not be freed when deleting a deployment. This gives us a window of time in which a deployment can be recovered in the state it was in before being archived.
Kube API Server – an API server in Kubernetes which should be called from control scripts.
octo CLI is distributed as a statically linked executable. The prebuilt binaries can be found in the "Releases" tab of the GitHub repository.
Octopod Server and Web UI are distributed as a single Docker Image. Charts are used to deploy it in Kubernetes.
A Docker Image with control scripts should be provided by the user. They are available in our Docker Hub registry.
Here we provide sequence diagrams for every basic operation that can be performed in Octopod. These operations call control scripts. On the diagrams, they are labeled as ControlScripts.
Create – creates a new deployment. The main inputs include the name of the deployment, the Docker Image tag and optional overrides. A more detailed description can be found in the control scripts documentation.
The arguments are forwarded to the create script which in turn creates the deployment in the Kubernetes cluster. It might call something like:
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 300Create via CLI sequence diagram
Create via UI sequence diagram
Update – updates an existing deployment. The main inputs include the name of the deployment, the Docker Image tag and optional overrides. A more detailed description can be found in the control scripts documentation.
Overrides are read from the database and merged with the new changes. All arguments are forwarded to the update script which in turn updates the specified deployment with the new parameters in the Kubernetes cluster. It might call something like:
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 300Update via CLI sequence diagram
Update via UI sequence diagram
Delete – archives a deployment. It should only free the computational resources (Pods). Persistent Volumes should not be deleted ― they are cleared in the cleanup process. This operation can be undone with the restore command.
The main argument is the name that identifies the deployment. A more detailed description can be found in the control scripts documentation.
The arguments are forwarded to the delete script which in turn frees the computational resources. It might call something like:
helm delete "$name" --purgeArchive via CLI sequence diagram
Archive via UI sequence diagram
Cleanup – releases all resources captured by the deployment.
The main argument is the name that identifies the deployment. A more detailed description can be found in the control scripts documentation. It can only be called after archive has been executed.
The arguments are forwarded to the cleanup script which in turn frees all resources captured by the given deployment. It might call something like:
kubectl delete pvc -n "$namespace" "$name-postgres-pvc"
kubectl delete certificate -n "$namespace" "$name-postgres-cert"Cleanup via CLI sequence diagram
Cleanup via UI sequence diagram
restore – restores an archived deployment in the state it was last in. Calls the same script that is called in create.
The main argument is the name that identifies the deployment. A more detailed description can be found in the control scripts documentation. It can only be called after archive has been executed.
All necessary setup information is read from the database: overrides and the Docker Image tag. The arguments are forwarded to the create script which in turn recreates the deployment. It might call something like:
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 300Restore via CLI sequence diagram
Restore via UI sequence diagram
We deploy several separate Kubernetes clusters:
- We have separate clusters for every product we deploy
- We also separate production and staging clusters
That makes two clusters per product.
So we get a cluster matrix similar to the following table, where each cell is a separate cluster:
| Staging (Has Octopod installed) | Production (Octopod not installed) | |
|---|---|---|
| Cactus shop | 🟩 🐙 Cluster A | 🟨 Cluster B |
| Pottery service | 🟦 🐙 Cluster C | 🟪 Cluster D |
| ... | ... | ... |
Every color depicts a separate cluster. A 🐙 indicates that Octopod is installed in that cluster.
Every staging cluster has a separate Octopod installation with separate interfaces to manage the deployments.
A deployment can exist in one of six states:
- Running
- Failure
- CreatePending
- UpdatePending
- DeletePending
- Archived
Running, Failure, Archived states are "permanent", meaning the deployment is not in the process of executing a command.
CreatePending, UpdatePending, DeletePending states are temporary, meaning the deployment is currently in the process of executing a deployment command.
