# Развертывание кластера одним чартом

## О подходе

`gs-ctk` - это инструмент развёртывания Global ERP, который мы рекомендуем интегрировать в CI/CD-процессы заказчика. Ниже показано, как создать Helm-чарт, использующий gs-ctk в качестве зависимости, и настроить минимальный пайплайн (на примере GitLab CI/CD). Такой подход позволяет описывать всё состояние системы в Git и не хранить данные на CI/CD-воркере.

*Преимущества*:

- Чарт и `values.yaml` хранятся в Git-репозитории.
- Параметры легко переопределяются через переменные CI/CD (секреты передаются отдельно).
- CI/CD-воркеру нужен только [Helm](https://helm.sh/) (и базовые пакеты ОС).
- Исключается конфигурационный дрифт между средами.

```{note}
Конкретная реализация пайплайна значительно зависит от вашей инфраструктуры. Здесь предлагается лишь концепция такого пайплайна. Если вам требуется детальная инструкция по развертыванию и настройке Global ERP в условиях кластера Kubernetes, читайте [инструкцию по установке](../040_global-k8s/020_install.md).
```

```{warning}
Данный пайплайн касается лишь развертывания Global ERP, но не сборки прикладного решения. О настройке сборки через GitLab CI/CD читайте [здесь](https://help.globalerp.ru/books/GsfCli/SNAPSHOT/html/035_%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0_gitlab_CI_%D0%B4%D0%BB%D1%8F_%D1%81%D0%B1%D0%BE%D1%80%D0%BA%D0%B8_%D0%BF%D1%80%D0%BE%D0%B5%D0%BA%D1%82%D0%BE%D0%B2_gsf-cli.html).
```

## Инструкция по подготовке и развёртыванию

### Шаг 1. Подготовьте `values.yaml`

Вся конфигурация системы (включая параметры развёртывания gs-ctk и описание ресурсов кластера) задаётся в одном файле values.yaml.

Подробнее о параметрах чарта, включая поле `helmResgroup` и управление секретами, читайте [здесь](./030_chart.md).

Минимальный пример (поместите в корень вашего репозитория или чарта):

```yaml
# Параметры для чарта gs-ctk
imagePullSecret: docker-secret
imageRepository: dockerhub.global-system.ru
systemVolume:
  nfs:
    path: /sys
    server: nfs.local

addSecrets: true # создать стандартные секреты
  
# Описание конфигурационного ресурса (NamespacedGlobalConfiguration)
helmResgroup:
  enabled: true # создать ресурс из чарта
  name: gs-cluster-1

  # База данных
  database_alias: test
  database_url: jdbc:postgresql://database.local/global

  # Параметры комплекта приложений (placeholder'ы подставятся в пайплайне)
  appkit:
    applib_sha256: "applib_placeholder"
    globalserver_sha256: "globalserver_placeholder"
    profile_sha256: "profile_placeholder"
    state: "started"
    appkit_path: "path_placeholder"
  appvol:
    path: /app
    server: nfs.local
    type: nfs
  database_schema_version: "database_schema_version_placeholder" # можно привязать к версии applib

  # Книги ресурсов (пример)
  resbooks:
  - name: global-server-excl
    type: global_server_excl
  - name: global-server-share
    replicas: 1
    type: global_server_share
  - name: grafana
    service:
      external_ip: 172.23.30.216
      type: ip
    type: grafana
  - name: haproxy
    replicas: 1
    service:
      annotations: {}
      host: ""
      ingress_class: traefik
      type: ingress
    type: haproxy
  - name: rabbitmq
    type: rabbitmq
    vhost: globalrabbitmq
  - name: scheduler
    type: global_scheduler
  - name: jgroups-dns
    type: jgroups_dns

  timezone: Europe/Moscow
  java_version: "21"
```

```{tip}
Все параметры, которые могут меняться между развёртываниями, выносите в переменные CI/CD (например, версии артефактов, пароли). В файле values.yaml оставляйте только неизменяемую структуру.
```

### Шаг 2. Создайте репозиторий с необходимыми файлами

В вашем GitLab-репозитории должны быть как минимум:

- values.yaml — подготовленный выше файл.
- gs-ctk-version.txt — файл, в котором закреплена версия чарта gs-ctk (например, SNAPSHOT или 6.1.0). Это удобно для автоматического скачивания чарта из репозитория артефактов.

Структура репозитория:

```text
/
├── gs-ctk-version.yaml
└── values.yaml
```

### Шаг 3. Управление секретами

Для безопасной передачи секретов и учётных данных в пайплайн зайдите в Settings → CI/CD → Variables вашего репозитория и добавьте следующие переменные (обязательно с флагом Masked):

- `KUBECONFIG` — содержимое файла ~/.kube/config для доступа к целевому кластеру Kubernetes.
- `ADMIN_PASSWORD` — пароль администратора Global ERP.
- другие переменные с секретами для переопределения (учетная запись СУБД, токен планировщика), в данной инструкции мы опустим их создание и использование.

```{warning}
Никогда не храните секреты в values.yaml в открытом виде. Все чувствительные данные передавайте через переменные CI/CD или другие безопасные инструменты, такие как SOPS или внешние операторы типа Sealed Secrets.
```

### Шаг 4. Настройте пайплайн (файл `.gitlab-ci.yml`)

Добавьте в корень репозитория файл .gitlab-ci.yml. Он будет автоматически скачивать комплект приложений, загружать его на NFS и развёртывать систему через Helm.

```yaml
stages:
  - deploy

variables:
  APPKIT_PATH: "appkit/v1"

deploy:
  stage: deploy
  image: alpine/helm:latest
  before_script:
    - apk add --no-cache kubectl coreutils wget tar
    # Настройка доступа к Kubernetes
    - mkdir -p ~/.kube
    - echo "${KUBECONFIG}" > ~/.kube/config
    - chmod 600 ~/.kube/config
  script:
    # 1. Скачивание комплекта приложений
    - wget https://repo.example.net/appkit-SNAPSHOT.tar.gz -O appkit.tar.gz
    - tar -xzvf appkit.tar.gz -C appkit/

    # 2. Скачивание Helm-чарта gs-ctk
    - wget "https://repo.example.net/gs-ctk-chart-$(cat gs-ctk-version.txt).tgz" -O gs-ctk.tgz

    # 3. Загрузка комплекта на NFS (через под nsctl, если он уже существует)
    - |
      if kubectl get ns gs-ctk &>/dev/null; then
        POD_NAME=$(kubectl get pods --namespace gs-ctk -l app=nsctl -o jsonpath='{.items[0].metadata.name}')
        if [ -n "$POD_NAME" ]; then
          kubectl cp --namespace gs-ctk appkit/ "$POD_NAME:/root/nsctl/workspace/mnt/sys/${APPKIT_PATH}"
        fi
      fi

    # 4. Установка/обновление через Helm
    - |
      helm upgrade --install gs-ctk gs-ctk.tgz \
        --namespace gs-ctk --create-namespace \
        -f values.yaml \
        --set helmResgroup.appkit.applib_sha256="$(cat appkit/applib.zip.sha256)" \
        --set helmResgroup.appkit.globalserver_sha256="$(cat appkit/globalserver.zip.sha256)" \
        --set helmResgroup.appkit.profile_sha256="$(cat appkit/profile.zip.sha256)" \
        --set helmResgroup.database_schema_version="$(cat appkit/applib.zip.sha256)" \
        --set helmResgroup.appkit.path="${APPKIT_PATH}" \
        --set secrets.gs-admin-auth.stringData.password="${ADMIN_PASSWORD}"
```

*Пояснения к скрипту*:

- Шаг 1–2 — загрузка артефактов и чарта из вашего репозитория бинарных артефактов (замените URL на реальные).

- Шаг 3 — здесь мы будем загружаем комплект, используя уже развернутый под nsctl, из-за чего кластер может развернуться не с первой, а со второй попытки. Мы выбрали этот способ, потому что он более универсален для нашего примера, так как делегирует задачу подключения к NFS на Kubernetes, но вы можете использовать вариант более подходящий вашей инфраструктуре и лишенный этого недостатка.

- Шаг 4 — команда helm upgrade --install. Обратите внимание, как подставляются:

  - sha256-суммы артефактов (читаются из распакованного комплекта); их можно создать при помощи `sha256sum`, подробнее читайте [здесь](../040_global-k8s/120_upgrade.md#вариант-b-без-nscli-вручную).

  - пароль администратора (ADMIN_PASSWORD) — прямо из переменной GitLab.

## Дополнительные советы

- *Обновление версии чарта*
  Измените число в gs-ctk-version.txt и запустите пайплайн — Helm обновит gs-ctk до нужной версии.

- *Кастомизация конфигурационного ресурса*
  Если вам не хватает гибкости `helmResgroup`, вы можете сделать свой чарт, использующий чарт gs-ctk, как зависимость, что позволит вам сделать шаблон ресурса `GlobalConfiguration`/`NamespacedGlobalConfiguration`.