1# Technical architecture
5The main goal of _Octopod_ is to simplify deployment in [_Kubernetes_][kube].
7When developing _Octopod_ we were expecting _Octopod_ itself to also be deployed with [_Kubernetes_][kube].
11Users can interact with _Octopod_ through:
121. the [_Web UI_](#-web-ui) (expected to be used by developers, project managers, QA engineers, etc.)
132. the [_octo CLI_](#-octo-cli) (expected to be used by DevOps engineers and programmatically, e. g. on CI)
15Interaction between _Octopod_ and [_Kubernetes_][kube] is done entirely through the [_control scripts_](#-control-scripts). This allows _Octopod_ to be adapted for use in practically any deployment setup.
17_Octopod_ stores all data about deployments and all performed operations in [_PostgreSQL_](#-postgresql).
19
23_Web UI_ – the user interface used to manipulate deployments. It interacts with [_Octopod Server_](#-octopod-server) through HTTP/1.1 requests and receives events from [_Octopod Server_](#-octopod-server) through _Websockets_. Authentication between _Web UI_ and [_Octopod Server_](#-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_][ingress].
25The 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.
29_Octopod Server_ – the server that processes deployment management requests and delegates [_Kubernetes_][kube]-specific logic to [_control scripts_](#-control-scripts).
32The server receives commands from the [_octo CLI_](#-octo-cli) and the [_Web UI_](#-web-ui) through HTTP/1.1 and updates the state of deployments. The server also sends updates to the [_Web UI_](#-web-ui) through _Websockets_. _Octopod Server_ interacts with [_Kube API Server_](#kube-api-server) through the [_control scripts_](#-control-scripts). Settings, deployment states and user action logs are stored in [_PostgreSQL_](#-postgresql).
36[_PostgreSQL_](https://www.postgresql.org) – DBMS used to store settings, deployment states and user action logs.
40_octo CLI_ – a command-line interface used to manage deployments. It sends HTTP/1.1 requests to [_Octopod Server_](#-octopod-server). The requests are [authenticated through the `Authorization` header](Security_model.md#octo-cli-authentication).
42It can perform all actions available in the [_Web UI_](#-web-ui), but also has access to view deployment logs.
44The 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](Integration.md).
48_Control scripts_ – a _Docker Container_ with executables which encapsulates all of the logic of interacting with the [_Kube API Server_](#kube-api-server), cloud providers, deployments, version control, etc.
50This is necessary to make _Octopod_ itself independent from any particular deployment setup ― it can be set up to work with practically any setup.
52When the [_Octopod Server_](#-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.
54These [scripts need to be implemented](Control_scripts.md) to deploy _Octopod_ unless the set of generic scripts is used.
59[Kube API Server](https://kubernetes.io/docs/concepts/overview/kubernetes-api/) – an API server in [_Kubernetes_][kube] which should be called from [_control scripts_](#-control-scripts).
61## 📦 Octopod Distribution model
63[_octo CLI_](#-octo-cli) is distributed as a *statically linked executable*. The prebuilt binaries can be found in the "Releases" tab of the GitHub repository.
65[_Octopod Server_](#-octopod-server) and [_Web UI_](#-web-ui) are distributed as a single _Docker Image_. [_Charts_][chart] are used [to deploy](Octopod_deployment_guide.md) it in [_Kubernetes_][kube].
67A _Docker Image_ with [_control scripts_](#-control-scripts) should be provided by the user. They are available in [our _Docker Hub_ registry](https://hub.docker.com/orgs/typeable/repositories).
71Here we provide sequence diagrams for every basic operation that can be performed in _Octopod_. These operations call [_control scripts_](#-control-scripts). On the diagrams, they are labeled as _Control Scripts_.
73### ✨ Deployment creation
75
78### 🔧 Deployment update
80
84
89
93
95## 👨💻👩💻 How we use it
97We deploy several separate [_Kubernetes_][kube] clusters:
98- We have separate clusters for every product we deploy
99- We also separate _production_ and _staging_ clusters
101That makes two clusters per product.
103So we get a cluster matrix similar to the following table, where each cell is a separate cluster:
105| | Staging (Has _Octopod_ installed) | Production (_Octopod_ not installed) |
106| ------------------- | --------------------------------- | ------------------------------------ |
107| **Cactus shop** | 🟩 🐙 Cluster *A* | 🟨 Cluster *B* |
108| **Pottery service** | 🟦 🐙 Cluster *C* | 🟪 Cluster *D* |
111Every color depicts a separate cluster. A 🐙 indicates that _Octopod_ is installed in that cluster.
113Every _staging_ cluster has a separate _Octopod_ installation with separate interfaces to manage the deployments.
115## 🗂️ Deployment state transitions
117A deployment can exist in one of six states:
125_Running_, _Failure_, _Archived_ states are "permanent", meaning the deployment is not in the process of executing a command.
127*CreatePending*, *UpdatePending*, *DeletePending* states are temporary, meaning the deployment is currently in the process of executing a deployment command.
129
131[kube]: https://kubernetes.io
132[chart]: https://helm.sh/docs/topics/charts/
133[ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/
138 <i>Star the project of you like it</i>
141<p align="center"><a href="https://typeable.io"><img src="../../img/typeable_logo.svg" width="177px"></img></a></p>
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