git.iko.soy/typeable/octopod
on 1.2.1 help sign in
typeable/octopod/docs/ru/Technical_architecture.md
275 lines 20 kB history raw
1# Technical architecture
3<details>
4 <summary>Table of contents</summary>
6- [Used tools](#used-tools)
7- [App architecture](#app-architecture)
8 - [UI](#ui)
9 - [Octopod Server](#octopod-server)
10 - [PostgreSQL](#postgresql)
11 - [octo CLI](#octo-cli)
12 - [Скрипты управления развертываниями (control scripts)](#скрипты-управления-развертываниями-control-scripts)
13 - [Clean Archive CronJob](#clean-archive-cronjob)
14 - [Kube API Server](#kube-api-server)
15- [Octopod Distribution model](#octopod-distribution-model)
16- [Process view](#process-view)
17 - [Create](#create)
18 - [Create via CLI](#create-via-cli)
19 - [Create via UI](#create-via-ui)
20 - [Update](#update)
21 - [Update via CLI](#update-via-cli)
22 - [Update via UI](#update-via-ui)
23 - [Archive](#archive)
24 - [Archive via CLI](#archive-via-cli)
25 - [Archive via UI](#archive-via-ui)
26 - [Cleanup](#cleanup)
27 - [Cleanup via CLI](#cleanup-via-cli)
28 - [Cleanup via UI](#cleanup-via-ui)
29 - [Restore](#restore)
30 - [Restore via CLI](#restore-via-cli)
31 - [Restore via UI](#restore-via-ui)
32- [How we use it](#how-we-use-it)
33- [Deployment state transitions](#deployment-state-transitions)
35</details>
37## Used tools
39Основная цель *Octopod* ― упрощение управления разными развертываниями сервисов в [_Kubernetes_][kube].
41При разработке рассчитывалось, что сам _Octopod_ тоже будет разворачиваться при помощи [_Kubernetes_][kube].
43## App architecture
45Взаимодействовать с _Octopod_ возможно либо через веб-интерфейс (рассчитано на использование разработчиками, PM, QA и т. д.), либо через консольный клиент [_octo CLI_](#octopod-server) (рассчитано на использования DevOps инженерами и программно, например в CI).
47Все взаимодействие _Octopod_ с самими развертываниями производится через [_скрипты управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts), которые передаются ему при запуске. Это позволяет сделать _Octopod_ очень гибким ― его возможно настроить для работы с практически в любой организацией развертываний.
49Все данные об окружениях развертываний и всех операция совершаемых над ними _Octopod_ хранит в базе данных [_PostgreSQL_](#postgresql).
51![App architecture](../diagrams/images/app-architecture.png)
53### UI
55_UI_ – веб интерфейс,
56используется для управления развертываниями посредством отправки команд управления развертываниями.
57Взаимодействует с [_Octopod Server_](#octopod-server) посредством отправки HTTP/1.1 запросов, а также получает
58события от [_Octopod Server_](#octopod-server) по _Websocket_. Между _UI_ и [_Octopod Server_](#octopod-server) Basic Auth. Написан на Haskell и Reflex-Dom.
60В интерфейсе нет технических деталей системной администрации и оркестрации ― работа с развертываниями производится очень просто. Интерфейс рассчитан на использование разработчиками любого уровня, QA инженерами, PM, а так же людьми без ИТ образования.
62### Octopod Server
64_Octopod Server_ – непосредственно сам сервер, который обрабатывает запросы работы с развертываниями и делегирует базовые операции, модифицирующие развертывания, [_скриптам управления стеджингами (control scripts)_](#скрипты-управления-развертываниями-control-scripts).
66Сервер обрабатывает
67команды управления развертываниями от [_octo CLI_](#octopod-server) и [_UI_](#ui), обновляет состояние развертываний.
68[_octo CLI_](#octopod-server) и [_UI_](#ui) взаимодействуют с ним путем отправки HTTP/1.1 запросов.
69Сервер шлет событие обновления на [_UI_](#ui) по _Websocket_. Сервер взаимодействует с [_Kube API Server_](#kube-api-server)
70через [_скрипты управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts). Для хранения настроек и статусов развертываний,
71и логов действий пользователей используется [_PostgreSQL_](#postgresql). Написан на Haskell. Для работы
72с развертываниями использует [_скрипты управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts).
74### PostgreSQL
76[_PostgreSQL_](https://www.postgresql.org) – РСУБД для хранения настроек и статусов развертываний, и логов
77действий пользователей.
79### octo CLI
81_octo CLI_ – консольный клиент
82используется для управления развертываниями посредством отправки команд управления
83развертываниями. Взаимодействует с [_Octopod Server_](#octopod-server) посредством отправки HTTP/1.1 запросов.
84Написан на Haskell. Между _octo CLI_ и [_Octopod Server_](#octopod-server) аутентификация по сертификату,
85новый сертификаты создается вовремя каждой сборки и упаковываются в контейнеры с _octo CLI_ и [_Octopod Server_](#octopod-server).
87В нем можно делать все операции, которые можно делать в [_UI_](#ui), но также есть доступ к расширенным операциям над развертываниями, таким как просмотр логов деплоя, что может быть полезно при диагностике возникающих проблем.
89Этот клиент рассчитан на использование DevOps инженерами.
91Его также можно использовать если необходимо автоматизировать управление развертываниями. Например, при настройке автоматического обновления развертываний при успешно пройденном CI.
93### Скрипты управления развертываниями (control scripts)
95_Скрипты управления развертываниями (control scripts)_ – контейнер с исполняемыми файлами, в которые инкапсулирована
96логика работы с [_Kube API Server_](#kube-api-server), облачными провайдерами, развертываниями, системами контроля версий и т.д.
98Они нужны для того, чтобы _Octopod_ не был завязан на какую-то конкретную организацию развертываний ― его можно настроить для работы с практически любой организацией развертываний.
100Во время старта пода [_Octopod Server_](#octopod-server) содержимое контейнера с утилитами копируется в ФС контейнера с [_Octopod Server_](#octopod-server),
101поэтому исполняемые файлы должны быть либо интерпретируемы через _Bash_, либо статически слинкованны.
102Логику исполняемых файлов предлагается реализовать пользователям _Octopod_ (смотри [_Control scripts_](Control_scripts.md)).
104### Clean Archive CronJob
106_Clean Archive CronJob_ – CronJob, которая запускается раз в час и через [_octo CLI_](#octopod-server) удаляет заархивированные развертывания старее 14 дней.
108Это сделано из-за того что при архивировании развертываний удаляются только вычислительные его части, _persistent volumes_ не удаляются, и при необходимости развертывание возможно восстановить в том виде, в котором он был до архивирования. Такая возможность пропадает по истечению 14 дней с момент его архивирования.
110### Kube API Server
112[Kube API Server](https://kubernetes.io/docs/concepts/overview/kubernetes-api/) – сервис на стороне [_Kubernetes_][kube], к которому должны обращаться [_скрипты управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts).
114## Octopod Distribution model
116[_octo CLI_](#octo-cli) в виде статически слинкованного исполняемого файла. Собранные исполняемые файлы доступны во вкладке "Releases" этого проекта на GitHub.
118[_Octopod Server_](#octopod-server) и [_UI_](#ui) поставляются упаковынными в один Docker образ. Для [развертывания](Octopod_deployment_with_K8S.md) в [_Kubernetes_][kube] используется набор [_Chart_][chart]-ов. Образы доступны в [нашем registry на _Docker Hub_](https://hub.docker.com/orgs/typeable/repositories).
120Docker образ [_скриптов управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts) пользователь _Octopod_ собирает сам.
122## Process view
124Далее здесь для справки приводятся схемы последовательностей для каждой из базовых операция работы с развертываниями. При их исполнении вызываются [_скрипты управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts). На схеме они помечены как _ControlScripts_.
126### Create
128_create_ – создание нового развертывания.
129 В качестве аргументов принимаются `name`, `tag` и опциональные `overrides` (уровня App или Deployment, открытие или секретные).
131 Переданные аргументы вместе с `project-name`, `base-domain`, `namespace` передаются в качестве аргументов в `create` из [_скриптов управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts).
132 `create` создает новое развертывание в кластере используя полученные аргументы.
133 Например, он может выполнять:
135```bash
136helm upgrade --install --namespace "$namespace" "$name" "$deployment_chart" \
137 --set "global.project-name=$project_name" \
138 --set "global.base-domain=$base-domain" \
139 --set "app.tag=$tag" \
140 --set "app.env.foo=$app_env_override_1" \
141 --set "app.bar=$deployment_override_1" \
142 --wait \
143 --timeout 300
144```
146#### Create via CLI
147![Create](../diagrams/images/technical-architecture-create-via-cli.png)
149#### Create via UI
150![Create](../diagrams/images/technical-architecture-create-via-ui.png)
152### Update
154_update_ – обновление существующего развертывания.
155 В качестве аргументов принимаются `name`, `tag` и опционально изменения `overrides` (уровня App или Deployment, открытие или секретные).
157 Затем из базы достаются `overrides` (уровня App или Deployment, открытие или секретные), они мерджатся с изменениями `overrides`
158 и передаются вместе с `project-name`, `base-domain`, `namespace` в качестве аргументов в `update` из [_скриптов управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts).
159 `update` обновляет существующее развертывание в кластере используя полученные аргументы.
160 Например, он может выполнять:
162```bash
163helm upgrade --install --namespace "$namespace" "$name" "$deployment_chart" \
164 --set "global.project-name=$project_name" \
165 --set "global.base-domain=$base-domain" \
166 --set "app.tag=$tag" \
167 --set "app.env.foo=$app_env_override_1" \
168 --set "app.bar=$deployment_override_1" \
169 --wait \
170 --timeout 300
171```
174#### Update via CLI
175![Update](../diagrams/images/technical-architecture-update-via-cli.png)
177#### Update via UI
178![Update](../diagrams/images/technical-architecture-update-via-ui.png)
180### Archive
182_delete_ – архивирование существующего развертывания.
183 Производится удаление только подов, Persistent Volumes (диски) сохраняются. Отменить действие этой команды можно с помощью команды restore.
184 В качестве аргументов принимается `name`.
186 `name` вместе с `project-name`, `base-domain`, `namespace` передаются в качестве аргументов в `archive` из [_скриптов управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts).
187 `archive` удаляет существующее развертывание в кластере, используя полученные аргументы.
188 Например он может выполнять:
190```bash
191helm delete "$name" --purge
192```
195#### Archive via CLI
196![Archive](../diagrams/images/technical-architecture-archive-via-cli.png)
198#### Archive via UI
199![Archive](../diagrams/images/technical-architecture-archive-via-ui.png)
201### Cleanup
203_cleanup_ – полная очистка развертывания.
204 В качестве аргументов принимаeтся `name`.
206 Например, можно удалять сертификаты, Persistent Volume Claim и Persistent Volumes.
208 `name` вместе с `project-name`, `base-domain`, `namespace` передаются в качестве аргументов в `cleanup` из [_скриптов управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts).
209 `cleanup` выполняет освобождение ресурсов в кластере, которые ранее использовались одним из удаленных развертываний.
210 Например, он может выполнять:
212```bash
213kubectl delete pvc -n "$namespace" "$name-postgres-pvc"
214kubectl delete certificate -n "$namespace" "$name-postgres-cert"
215```
217#### Cleanup via CLI
218![Cleanup](../diagrams/images/technical-architecture-cleanup-via-cli.png)
220#### Cleanup via UI
221![Cleanup](../diagrams/images/technical-architecture-cleanup-via-ui.png)
223### Restore
225_restore_ – восстановление заархивированного развертывания с последними настройками.
226 В качестве аргументов принимается `name`.
228 Из базы достаются недостающие для восстановления `tag` и опциональные `overrides` (уровня App или Deployment, открытие или секретные). Они передаются вместе с `project-name`, `base-domain`, `namespace` в качестве аргументов в `restore` из [_скриптов управления развертываниями (control scripts)_](#скрипты-управления-развертываниями-control-scripts).
229 `restore` выполняет восстановление в кластере ранее удаленного развертывания используя полученные аргументы.
230 Например, он может выполнять:
232```bash
233helm upgrade --install --namespace "$namespace" "$name" "$deployment_chart" \
234 --set "global.project-name=$project_name" \
235 --set "global.base-domain=$base-domain" \
236 --set "app.tag=$tag" \
237 --set "app.env.foo=$app_env_override_1" \
238 --set "app.bar=$deployment_override_1" \
239 --wait \
240 --timeout 300
241```
243#### Restore via CLI
244![Restore](../diagrams/images/technical-architecture-restore-via-cli.png)
246#### Restore via UI
247![Restore](../diagrams/images/technical-architecture-restore-via-ui.png)
249## How we use it
251Мы используем несколько кластеров [_Kubernetes_][kube]: отдельный кластер для каждого приложения, а так же разделяем по кластерам _production_ и _deployment_ окружения.
253В каждый _deployment_ кластер мы устанавливаем _Octopod_, через _Octopod_ осуществляем разворачивание различных версий deployment'ов необходимых для QA.
255## Deployment state transitions
257Существует 6 статусов развертываний:
2581. *Running*
2592. *Failure*
2603. *CreatePending*
2614. *UpdatePending*
2625. *DeletePending*
2636. *Archived*
265_Running_, _Failure_, _Archived_ являются постоянными, т.е. развертывание уже не находится в режиме выполнения команды.
267*CreatePending*, *UpdatePending*, *DeletePending* являются переходными, т.е. развертывание находится в режиме выполнения команды.
269![Deployment Statuses](../diagrams/images/technical-architecture-deployment-states-fsm.png)
271<!-- [kubectl]: https://kubernetes.io/docs/reference/kubectl/ -->
272<!-- [helm]: https://helm.sh -->
273<!-- [kubedog]: https://github.com/werf/kubedog -->
274[kube]: https://kubernetes.io
275[chart]: https://helm.sh/docs/topics/charts/