
## Компоненты системы

| Компонент                 | Описание                                                                                                                       |
|---------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| Zakroma-Storage           | Управляющий слой, обеспечивающий S3-протокол.                                                                                  |
| Zakroma-ZDS               | Нижний слой хранения (минимальное требование — 3 узла в режиме Erasure Coding, 1 узел - в режиме без избыточного кодирования). |
| Keycloak                  | Система управления аутентификацией и авторизацией (используется для Admin UI и доступа к Zakroma).                             |
| Nginx                     | Proxy-сервер, выступающий в качестве фронтенда для Zakroma-Storage.                                                            |
| PostgreSQL                | СУБД для метаданных Zakroma-Storage и Keycloak.                                                                                |
| Kafka (опционально)       | Система обмена сообщениями, используемая сервисами Zakroma (требуется для различных служебных операций, опционально).          |
| Kafka-UI<br>(опционально) | Интерфейс управления и мониторинга Kafka-кластером через веб-приложение.                                                       |

## Компоненты, устанавливаемые с помощью Ansible ролей

| Название        |                                                Поддерживаемые версии                                                |
|-----------------|:-------------------------------------------------------------------------------------------------------------------:|
| Zakroma-Storage |                                                        2.6.0                                                        |
| Zakroma-ZDS     |                                                        1.6.2                                                        |
| Keycloak        |                                                         26                                                          |
| Nginx           | в зависимости от дистрибутива Linux <br>(устанавливается из стандартных репозиториев хостовой операционной системы) |
| Java            | в зависимости от дистрибутива Linux <br>(устанавливается из стандартных репозиториев хостовой операционной системы) |
| Kafka           |                                                        3.8.1                                                        |
| Kafka-UI        |                                                        0.7.2                                                        |


## Поддерживаемые дистрибутивы Linux

| Название   | Поддерживаемые версии |
|------------|-----------------------|
| Debian     | 10, 11, 12            |
| Ubuntu     | 20, 22, 24            |
| AlmaLinux  | 8, 9                  |
| RedOs      | 7, 8                  |
| RHEL       | 8, 9                  |
| ALT Server | 10.4 (Mendelevium)    |

### Структура дистрибутива

Дистрибутив поставляется архивом вида`zakroma-roles-<ВЕРСИЯ_РЕЛИЗА_АРХИВА_С_ANSIBLE_РОЛЯМИ>.tar.gz`

```yaml  
.
├── ansible.cfg
├── CHANGELOG.md
├── collections
│   └── ansible_collections
├── files
│   └── realm.json
├── inventories
│   ├── base-cluster
│   │   ├── group_vars
│   │   │   ├── certificates.yml
│   │   │   ├── java.yml
│   │   │   ├── kafka-ui-nginx.yml
│   │   │   ├── kafka-ui.yml
│   │   │   ├── kafka.yml
│   │   │   ├── keycloak.yml
│   │   │   ├── zakroma-storage-nginx.yml
│   │   │   ├── zakroma-storage.yml
│   │   │   └── zakroma-zds-ec.yml
│   │   └── hosts
│   ├── multicluster
│   │   ├── cluster-1
│   │   │   ├── group_vars
│   │   │   │   ├── certificates.yml
│   │   │   │   ├── java.yml
│   │   │   │   ├── kafka-ui-nginx.yml
│   │   │   │   ├── kafka-ui.yml
│   │   │   │   ├── kafka.yml
│   │   │   │   ├── keycloak.yml
│   │   │   │   ├── zakroma-storage-nginx.yml
│   │   │   │   ├── zakroma-storage.yml
│   │   │   │   └── zakroma-zds-ec.yml
│   │   │   └── hosts
│   │   └── cluster-2
│   │       ├── group_vars
│   │       │   ├── certificates.yml
│   │       │   ├── java.yml
│   │       │   ├── kafka-ui-nginx.yml
│   │       │   ├── kafka-ui.yml
│   │       │   ├── kafka.yml
│   │       │   ├── keycloak.yml
│   │       │   ├── zakroma-storage-nginx.yml
│   │       │   ├── zakroma-storage.yml
│   │       │   └── zakroma-zds-ec.yml
│   │       └── hosts
│   └── single-node
│       ├── group_vars
│       │   ├── certificates.yml
│       │   ├── java.yml
│       │   ├── kafka-ui-nginx.yml
│       │   ├── kafka-ui.yml
│       │   ├── kafka.yml
│       │   ├── keycloak.yml
│       │   ├── zakroma-storage-nginx.yml
│       │   ├── zakroma-storage.yml
│       │   └── zakroma-zds-fs.yml
│       └── hosts
├── playbooks
│   ├── sample-play-copy-certificates.yml
│   ├── sample-play-java.yml
│   ├── sample-play-kafka-ui-nginx.yml
│   ├── sample-play-kafka-ui.yml
│   ├── sample-play-kafka.yml
│   ├── sample-play-keycloak-copy-realm.yml
│   ├── sample-play-keycloak.yml
│   ├── sample-play-zakroma-storage-nginx.yml
│   ├── sample-play-zakroma-storage.yml
│   ├── sample-play-zakroma-zds-ec.yml
│   └── sample-play-zakroma-zds-fs.yml
├── README.md
└── roles
```

***

- **ansible.cfg**  
  Файл конфигурации Ansible, в котором задаются параметры работы (например, пути к инвентарям, настройки подключения,
  параметры логирования и т.д.).
- **CHANGELOG.md**  
  Журнал изменений проекта. Здесь фиксируются версии, внесённые правки, улучшения и исправления ошибок.
- **collections/**  
  Каталог, содержащий Ansible collections – наборы ролей, плагинов и модулей, объединённых в пакеты для удобного
  повторного использования и распространения.
- **files/realm.json**  
  JSON-файл, содержащий сконфигурированный REALM для Keycloak.
- **inventories/**  
  Каталог с инвентарями Ansible, разделёнными по различным сценариям развёртывания:
    - **base-cluster/**
      Инвентарь для развёртывания базового кластера:
        - **group_vars/** – переменные групп хостов для базового кластера:
            - **certificates.yml** – переменные для копирования сертификатов на целевые хосты.
            - **java.yml** – переменные для установки Java.
            - **kafka-ui-nginx.yml**  – переменные для установки и конфигурирования Nginx для Kafka-UI.
            - **kafka-ui.yml** – переменные для установки и конфигурирования Kafka-UI.
            - **kafka.yml** – переменные для установки и конфигурирования Kafka.
            - **keycloak.yml** – переменные для установки и конфигурирования Keycloak.
            - **zakroma-storage-nginx.yml** – переменные для установки и конфигурирования Nginx для Zakroma-Storage.
            - **zakroma-storage.yml** – переменные для установки и конфигурирования Zakroma-Storage.
            - **zakroma-zds-ec.yml** – переменные для установки и конфигурирования Zakroma-ZDS.
        - **hosts** – определение хостов для базового кластера.
    - **multicluster/**  
      Инвентарь для мультикластерного развёртывания:
        - **cluster-1/** и **cluster-2/**  
          Для каждого кластера:
            - **group_vars/** – аналогичные файлы с переменными (такие же файлы, как в base-cluster).
            - **hosts** – определение хостов для конкретного кластера.
    - **single-node/**  
      Инвентарь для развёртывания на одном узле:
        - **group_vars/** – файлы с переменными для одиночного узла. Отличительной особенностью является наличие файла *
          *zakroma-zds-fs.yml** (нижний слой хранения без Erasure Coding).
        - **hosts** – файл с описанием единственного узла.
- **playbooks/**  
  Каталог с playbook'ов, необходимых для применение ролей или выполнение конкретных задач:
    - **sample-play-copy-certificates.yml** – playbook для копирования сертификатов.
    - **sample-play-java.yml** – playbook для установки Java.
    - **sample-play-kafka-ui-nginx.yml** – playbook для установки и конфигурирования Nginx для Kafka-UI.
    - **sample-play-kafka-ui.yml** – playbook для установки и конфигурирования Kafka UI.
    - **sample-play-kafka.yml** – playbook для установки и конфигурирования Kafka.
    - **sample-play-keycloak-copy-realm.yml** – playbook для копирования realm-конфигурации в Keycloak.
    - **sample-play-keycloak.yml** – playbook для установки и конфигурирования Keycloak.
    - **sample-play-zakroma-storage-nginx.yml** – playbook для установки и конфигурирования Nginx для Zakroma-Storage.
    - **sample-play-zakroma-storage.yml** – playbook для установки и конфигурирования Zakroma-Storage.
    - **sample-play-zakroma-zds-ec.yml** – playbook для установки и конфигурирования Zakroma-ZDS в режиме EC (с
      применением Erasure Coding)
    - **sample-play-zakroma-zds-fs.yml** – playbook для установки и конфигурирования Zakroma-ZDS в режиме FS (без
      Erasure Coding).
- **README.md**  
  Основной файл с описанием проекта, содержащий обзор, инструкции по установке, использованию и общую информацию о
  проекте.
- **roles/**  
  Каталог, где располагаются Ansible роли.


Состав поставки для установки через Ansible

4.2.0 Установка базового кластера


### Демо-стенд (Single-Node Deployment)

- Предназначен для демонстрации возможностей платформы Zakroma и её компонентов.
- Идеально подходит для ознакомления с функциональностью системы и внутренних тестов.
- Разворачивается на одном сервере, что упрощает настройку и сокращает требования к инфраструктуре.

| Сервер    | Компоненты                                                                              |
|-----------|-----------------------------------------------------------------------------------------|
| `Server1` | Zakroma-Storage, Zakroma-ZDS, Nginx,Keycloak,PostgreSQL, Kafka и Kafka-UI (опционально) |

см. [Описание установки демо-стенда](https://zakroma.ru/knowledgeBase/devops/article/readme-single-node-4-2-0?version=Закрома.Хранение).

### Базовый кластер

- Отказоустойчивый кластер хранилища. Подходит как для тестовых окружений, так и производственных систем.

| Сервер    | Компоненты                                               |
|-----------|----------------------------------------------------------|
| `Server1` | PostgreSQL                                               |
| `Server2` | Keycloak                                                 |
| `Server3` | Zakroma-Storage, Zakroma-ZDS (Erasure Coding 2+1), Nginx |
| `Server4` | Zakroma-Storage, Zakroma-ZDS (Erasure Coding 2+1), Nginx |
| `Server5` | Zakroma-Storage, Zakroma-ZDS (Erasure Coding 2+1), Nginx |
| `Server6` | Kafka и Kafka-UI (опционально)                           |

### Базовый кластер (Zakroma-ZDS в режиме Erasure Coding вынесен на отдельные сервера)

| Сервер    | Компоненты                       |
|:----------|----------------------------------|
| `Server1` | PostgreSQL                       |
| `Server2` | Keycloak                         |
| `Server3` | Zakroma-ZDS (Erasure Coding 2+1) |
| `Server4` | Zakroma-ZDS (Erasure Coding 2+1) |
| `Server5` | Zakroma-ZDS (Erasure Coding 2+1) |
| `Server6` | Zakroma-Storage, Nginx           |
| `Server7` | Kafka и Kafka-UI (опционально)   |

см. [Описание установки базового кластера](https://zakroma.ru/knowledgeBase/devops/article/readme-base-cluster-4-2-0?version=Закрома.Хранение).

### Мультикластер

- Несколько независимых кластеров
- Позволяет организовать распределённое хранение, георезервирование и масштабирование на уровне нескольких кластеров.
- Рекомендован при необходимости высокой доступности и геораспределения (например, кластеры в разных ЦОД).

| Сервер     | Компоненты                                               | Cluster |
|------------|----------------------------------------------------------|:-------:|
| `Server1`  | PostgreSQL                                               |    1    |
| `Server2`  | Keycloak                                                 |    1    |
| `Server3`  | Zakroma-Storage, Nginx, Zakroma-ZDS (Erasure Coding 2+1) |    1    |
| `Server4`  | Zakroma-Storage, Nginx, Zakroma-ZDS (Erasure Coding 2+1) |    1    |
| `Server5`  | Zakroma-Storage, Nginx, Zakroma-ZDS (Erasure Coding 2+1) |    1    |
| `Server6`  | Kafka и Kakfa-UI                                         |    1    |
| `Server7`  | PostgreSQL                                               |    2    |
| `Server8`  | Keycloak                                                 |    2    |
| `Server9`  | Zakroma-Storage, Nginx, Zakroma-ZDS (Erasure Coding 2+1) |    2    |
| `Server10` | Zakroma-Storage, Nginx, Zakroma-ZDS (Erasure Coding 2+1) |    2    |
| `Server11` | Zakroma-Storage, Nginx, Zakroma-ZDS (Erasure Coding 2+1) |    2    |
| `Server12` | Kafka и Kakfa-UI                                         |    2    |

см. [Описание установки мультикластерного варианта установки](https://zakroma.ru/knowledgeBase/devops/article/readme-multicluster-4-2-0?version=Закрома.Хранение).

***
Количество серверов каждого компонента может меняться в зависимости от требуемого объёма хранения, уровня отказоустойчивости и производительности.
Также возможно объединять или совмещать некоторые из компонентов на меньшем количестве машин для тестовых стендов или не очень нагруженных систем.
***

Варианты развертывания


## 1. Отключение SELinux

Убедитесь, что **SELinux** отключён.

## 2. Проверка и настройка DNS

1. Убедитесь, что все серверы могут правильно разрешать доменные имена (через DNS или `/etc/hosts`).
2. Создайте соответствующие **DNS A-записи**, указывающие на IP-адреса хостов, где будут развернуты сервисы:

Для **базового кластера** и **Single Node**:
```  
*.ps.zakroma.local            → хост(ы) с Zakroma-Storage (для обращения к S3 по path-style)  
zakroma-gateway.zakroma.local → хост(ы) с Zakroma-Storage  
zakroma-admin.zakroma.local   → хост(ы) с Zakroma-Storage  
keycloak.zakroma.local        → хост(ы) с Keycloak  
kafka.zakroma.local           → хост(ы) с Kafka (опционально)
kafka-ui.zakroma.local        → хост(ы) с Kafka-ui (опционально)
```  

Для **мультикластера**:
```   
*.ps.cluster-1.zakroma.local            → хост(ы) с Zakroma-Storage (для обращения к S3 по path-style)  
zakroma-gateway.cluster-1.zakroma.local → хост(ы) с Zakroma-Storage  
zakroma-admin.cluster-1.zakroma.local   → хост(ы) с Zakroma-Storage  
zakroma-cdn.cluster-1.zakroma.local     → хост(ы) с Zakroma-Storage  
keycloak.cluster-1.zakroma.local        → хост(ы) с Keycloak  
kafka-1.cluster-1.zakroma.local         → хост(ы) с Kafka
kafka-ui.cluster-1.zakroma.local        → хост(ы) с Kafka-ui
  
*.ps.cluster-2.zakroma.local            → хост(ы) с Zakroma-Storage (для обращения к S3 по path-style)  
zakroma-gateway.cluster-2.zakroma.local → хост(ы) с Zakroma-Storage  
zakroma-admin.cluster-2.zakroma.local   → хост(ы) с Zakroma-Storage  
zakroma-cdn.cluster-2.zakroma.local     → хост(ы) с Zakroma-Storage  
keycloak.cluster-2.zakroma.local        → хост(ы) с Keycloak
kafka-1.cluster-2.zakroma.local         → хост(ы) с Kafka
kafka-ui.cluster-2.zakroma.local        → хост(ы) с Kafka-ui
```  

В инструкции используется **пример домена** `zakroma.local`.    
Вы можете заменить его на собственную доменную зону, соответствующую вашей инфраструктуре (например, `zakroma.company.com` или `zakroma.internal`).
## 3. Подготовка сертификатов (TLS/SSL)

Сгенерируйте и/или получите сертификаты для следующих доменных имен:

Для **базового кластера**:
```  
*.ps.zakroma.local  
zakroma-gateway.zakroma.local  
zakroma-admin.zakroma.local  
keycloak.zakroma.local
kafka-ui.zakroma.local (опционально)
```  

Для **мультикластера**:
```   
*.ps.cluster-1.zakroma.local  
zakroma-gateway.cluster-1.zakroma.local  
zakroma-admin.cluster-1.zakroma.local  
zakroma-cdn.cluster-1.zakroma.local  
keycloak.cluster-1.zakroma.local
kafka-ui.cluster-1.zakroma.local
  
*.ps.cluster-2.zakroma.local  
zakroma-gateway.cluster-2.zakroma.local  
zakroma-admin.cluster-2.zakroma.local  
zakroma-cdn.cluster-2.zakroma.local  
keycloak.cluster-2.zakroma.local
kafka-ui.cluster-2.zakroma.local
```  

Эти сертификаты будут использоваться для безопасного доступа к Zakroma и Keycloak по HTTPS.

## 4. Подготовка для работы с Ansible

1. Проверьте, что доступно **SSH-подключение** к каждому хосту.
2. Убедитесь, что пользователь имеет привилегированный (sudo) доступ.
3. Установите или обновите **Ansible** до версии **2.15.0** или выше.

## 5. Настройка PostgreSQL

Настройте PostgreSQL согласно [официальной инструкции](https://zakroma.ru/knowledgeBase/storage/article/nastrojka-postgre-sql).

## 6. Подготовка дисков и точек монтирования для Zakroma-ZDS

1. Подготовьте дисковое пространство (например, используйте LVM или отдельные разделы).
2. Смонтируйте разделы на серверах, где будет использоваться Zakroma-ZDS.
3. Добавьте точки монтирования в `/etc/fstab`, используя **UUID**.
4. Рекомендуемые параметры:
   - Файловая система: **XFS** или **EXT4**.
   - Использование групп томов (**Volume Groups**) для большей гибкости управления.
