# Обновление системы

**Стандартное обновление** - это обновление комплекта приложения (appkit) с применением изменений так, что сервер
приложений перезапускается, а пользователи отключаются на время перезапуска.

Как правило, применяется когда меняется хотя бы один из компонентов:

* `globalserver.zip` (сервер приложений)
* `profile.zip` (профиль конфигурации)
* `applib.zip` (прикладное решение)
* а также когда требуется обновление схемы БД.

**Горячее обновление** - режим, при котором можно обновить **только прикладное решение** без отключения пользователей и
без перезапуска серверов, но при строгих условиях:

* включён флаг `hot_reload: true` в группе ресурсов (resgroup);
* меняется только `applib.zip` (и опционально `appsrc`), а `globalserver.zip` и `profile.zip` остаются без
  изменений;
* если в рамках обновления требуется миграция/обновление схемы БД, поведение зависит от настройки "осушения" кластера
  перед обновлением БД (`drain_cluster_before_db_upgrade`).

```{attention}
Если вы запускаете обновление схемы БД при включённом `drain_cluster_before_db_upgrade: true`, пользователи будут отключены на время обновления БД, даже если горячее обновление включено.
```

## Стандартное обновление

### Вариант A. С использованием nscli

```{important}
При замене архивов в рамках обновления необходимо удалять ранее сформированные файлы хеш-сумм, относящиеся к этим архивам.

Утилита nscli не выполняет автоматический пересчет уже существующих файлов хеш-сумм, поскольку это ограничение введено в целях обеспечения безопасности и контроля целостности поставляемых артефактов.
Данный механизм может быть полезен в рамках процесса CI/CD, когда вместе с обновленным комплектом приложения поставляются файлы хеш-сумм, сгенерированные на этапе сборки (или формирования архивов).

Такой подход повышает надежность поставки, обеспечивает контроль целостности артефактов и снижает риск использования неконсистентных или несанкционированно измененных файлов.
```

1. Для обновления [комплекта приложения](./100_appkit.md#шаг-5-подготовьте-комплект-приложений) (appkit: сервера
   приложений, прикладного решения) подготовьте его и загрузите на NFS-хранилище:

    ```bash
    ./appkit.sh push --namespace gs-ctk --source workspace/appkit --destination appkit/v2
    ```

    - `--namespace gs-ctk` - пространство имен, в котором развертан `gs-ctk`.
    - `--source workspace/appkit` - путь к папке с комплектом на локальной ФС относительно текущей папки.
    - `--destination appkit/v2` - путь к папке, в которую следует поместить комплект,
      относительно [точки монтирования системного хранилища](/040_global-k8s/050_install_nsctl.md).

2. Обновите хеши и пути к комплекту приложения (appkit) в конфигурации при помощи команды:

    ```bash
    # не требует подключения к кластеру, хеши будут посчитаны с комплекта приложений на локальном диске
    ./appkit.sh switch_local --config-path ./config.yaml --resgroup gs-cluster-1 --local-appkit workspace/appkit --remote-appkit appkit/v2
    ```

    - `--config-path ./config.yaml` - путь к конфигурационному ресурсу.
    - `--resgroup gs-cluster-1` - название группы ресурсов.
    - `--local-appkit workspace/appkit` - путь к папке с комплектом на локальной ФС относительно текущей папки
      (`--source` из предыдущего пункта).
    - `--remote-appkit appkit/v2` - путь к папке на системном хранилище, в котором находится комплект (`--destination`
      из предыдущего пункта).

   ИЛИ

    ```bash
    # хеши читаются с комплекта приложений на хранилище в кластере, следовательно требует подключения к кластеру
    ./appkit.sh switch_remote --config-path ./config.yaml --resgroup gs-cluster-1 --namespace gs-ctk --remote-appkit appkit/v2
    ```

    - `--config-path ./config.yaml` - путь к конфигурационному ресурсу.
    - `--resgroup gs-cluster-1` - название группы ресурсов.
    - `--namespace gs-ctk` - пространство имен, в котором развертан `gs-ctk`.
    - `--remote-appkit appkit/v2` - путь к папке на системном хранилище, в котором находится комплект (`--destination`
      из предыдущего пункта).

3. Переключите [показатель версии базы данных
   `database_schema_version`](../040_global-k8s/010_whatis.md#комплект-группы-appkit-и-версия-схемы), чтобы запустить
   обновление базы данных при следующем применении ресурса:

   ```bash
   ./appkit.sh upgrade --config-path ./config.yaml --resgroup gs-cluster-1
   ```

4. Повторно примените ресурс:

   ```bash
   kubectl apply -f ./config.yaml
   ```

```{tip}

Для отслеживания статуса обновления и чтения логов, используйте команду:

~~~bash
./appkit.sh wait_upgrade --namespace gs-ctk --resgroup gs-cluster-1
~~~

```

### Вариант B. Без nscli (вручную)

Этот вариант делает то же самое по сути, но без использования утилиты.

1. Сформируйте комплект приложения

   Необходимо подготовить три zip-архива:

    * `globalserver.zip`
    * `applib.zip`
    * `profile.zip`

   ```{attention}
   Архивы должны содержать **содержимое** соответствующих папок, а не саму папку верхнего уровня (то есть внутри `applib.zip` лежат модули, а не директория `applib/` целиком). 
   ```

2. Сгенерируйте sha256-файлы рядом с архивами

   Рядом с каждым архивом должен лежать файл `*.sha256` с sha256-суммой (первое слово, отделенное от остальных пробелом
   или табуляцией, должно быть хеш-суммой, остальные не учитываются).

   Пример скрипта:

   ```bash
   for archive in appkit/*.zip
   do
     sha256sum "$archive" > "$archive.sha256"
   done
   ```

3. Загрузите архивы и хеш-суммы на системное NFS-хранилище

   Загрузите в новый каталог вида `appkit/v2` (необходимо сделать инкремент текущей версии appkit).

4. Обновите конфигурацию

   В конфигурационном ресурсе обновите:

    * путь к комплекту (`path`)
    * хеши: `applib_sha256`, `appsrc_sha256` (если используется), `globalserver_sha256`, `profile_sha256`
    * счётчики: `globalserver_instance` и `database_schema_version`

5. Примените ресурс:

   ```bash
   kubectl apply -f config.yaml
   ```

## Горячее обновление

Система поддерживает выпуск горячих обновлений (hotfix). Горячее обновление имеет смысл, когда **меняется только
`applib.zip`** (и/или `appsrc`), а `globalserver.zip` и
`profile.zip` остаются прежними. Иначе необходимо использовать стандартное обновление.

Возможность горячего обновления можно проверить заранее командой `check_hot_reload` (см. раздел
[Проверка возможности горячего обновления](#проверка-возможности-горячего-обновления)).

Функция управляется параметрами в `GlobalConfiguration`:

```yaml
apiVersion: global-system.ru/v1
kind: GlobalConfiguration
metadata:
  name: config
spec:
  resgroups:
    - hot_reload: true
      drain_cluster_before_db_upgrade: false
```

Ключевые параметры:

* `hot_reload`

    * `true` - разрешает горячее обновление, если изменяется только `applib.zip`, а сервер приложений (globalserver.zip)
      и профиль (profile.zip) остаются без изменений. Обновления применяется без перезапуска серверов.
    * `false` - любое обновление приводит к перезапуску и отключению пользователей

* `drain_cluster_before_db_upgrade`

    * `true` (рекомендуется, по умолчанию) - перед обновлением БД кластер "осушается" (новые соединения не принимаются,
      текущие завершаются). Это гарантирует согласованность данных и отсутствие конфликтов.
    * `false` - Обновление БД выполняется в фоне, пока пользователи продолжают работу.

  ```{warning}
  Параллельная работа пользователей и процесс обновления могут конфликтовать, что потенциально приводит к ошибкам и неполному применению изменений в БД.
  ```

```{note}

Если вы инициируете обновление БД при помощи `./appkit.sh upgrade` при включенном осушении кластера (`drain_cluster_before_db_upgrade = true`), то пользователи будут отключены на время обновления БД независимо от того, включено горячее обновление (`hot_reload`) или нет.

```

### Проверка возможности горячего обновления

Перед горячим обновлением проверьте, что целевой комплект приложений можно применить без перезапуска серверов. Проверка запускает Job выделенного сервера приложений: кластер не осушается, конфигурация группы ресурсов не изменяется.

```bash
./appkit.sh check_hot_reload --namespace gs-ctk --resgroup gs-cluster-1 --remote-appkit appkit/v2
```

* `--namespace gs-ctk` - пространство имен, в котором развернут `gs-ctk`.
* `--resgroup gs-cluster-1` - название группы ресурсов.
* `--remote-appkit appkit/v2` - путь к проверяемому комплекту на системном хранилище (относительный или абсолютный).
  Если параметр не указан, проверяется комплект, который уже используется группой ресурсов.
* `--run-id <идентификатор>` - идентификатор запуска для именования каталога логов. По умолчанию используется
  время в UTC.
* `--format json` - вывод результата в машиночитаемом виде.

Коды завершения:

* `0` - горячее обновление возможно;
* `1` - горячее обновление невозможно;
* `2` - ошибка выполнения проверки.

Если целевой комплект изменяет `globalserver.zip` или `profile.zip`, проверка сразу возвращает код `1`, не запуская
Job. Причина отказа выводится в текстовом режиме, а при `--format json` - в поле `reason`. В JSON-выводе также
доступны поля `status`, `possible`, `run_id`, `report`, `report_path`, `stdout_path` и, при наличии,
`schema_changes`.

Отчет и журнал проверки сохраняются на системном NFS в каталоге
`hot_reload_check_logs/<название группы>/<run_id>/` (`report.json`, `stdout.log`). Одновременно для одной группы
ресурсов может выполняться только одна проверка. Каталоги проверок старше 7 дней удаляются автоматически.

```{important}
Для проверки требуется gs-ctk версии не ниже 6.3.0, сервер приложений (ApplicationServer) версий 1.27.0-rc16, 1.28.0-ms13 или новее и модуль btk
версии не ниже 1.58.91.1133.
```

Проверка не изменяет настройки группы ресурсов. Для выполнения горячего обновления флаг `hot_reload` должен быть включён.

### Вариант A. Горячее обновление с использованием nscli

1. Включите hot reload и настройте "осушение":

   Используйте интерактивный мастер для настройки параметров группы ресурсов:

   ```bash
   ./configmgr.sh configure_resgroup --config-path config.yaml --resgroup gs-cluster-1
   ```

   ```text

   Настройка группы ресурсов: gs-cluster-1
   =======================================

   ...
   Включить горячие обновления?[да,нет]:да
   Осушать кластер перед запуском обновления?[да,нет]:нет
   ...

   ```

   Или точечно командами:

   ```bash
   # Включение/выключение горячего обновления
   ./appkit.sh allow_hot_reload --config-path config.yaml --resgroup gs-cluster-1
   ./appkit.sh disallow_hot_reload --config-path config.yaml --resgroup gs-cluster-1

   # Управление осушением кластера перед обновлением БД
   ./appkit.sh drain_before_upgrade --config-path config.yaml --resgroup gs-cluster-1
   ./appkit.sh do_not_drain_before_upgrade --config-path config.yaml --resgroup gs-cluster-1
   ```

2. Загрузите на хранилище обновленные компоненты.

   Для того, чтобы скопировать на сетевое хранилище только нужные компоненты (например, только прикладное решение),
   используйте аргумент `--items` команды `./appkit.sh push`:

   ```bash
   ./appkit.sh push --namespace gs-ctk --source workspace/appkit --destination appkit/v2 --items applib,appsrc
   ```

   ```{warning}
   В комплекте приложений должны быть все три компонента: `applib`, `globalserver` и `profile`. Установка фильтра при помощи `--items` позволяет обновить (перезаписать) один компонент, но не отменяет необходимость в других. Если по указанному `--destination` в команде выше не было комплекта приложений, то загружен будет только `applib` и, при наличии, `appsrc`, а остальные компоненты будут отсутствовать и `switch_remote` выдаст ошибку.
   ```

3. Проверьте возможность горячего обновления:

   ```bash
   ./appkit.sh check_hot_reload --namespace gs-ctk --resgroup gs-cluster-1 --remote-appkit appkit/v2
   ```

   Команда должна завершиться с кодом `0`. Если проверка вернула код `1`, горячее обновление невозможно - используйте [стандартное обновление](#стандартное-обновление).

4. Обновите хеши компонентов в конфигурационном файле:

   ```bash
   ./appkit.sh switch_remote --config-path ./config.yaml --resgroup gs-cluster-1 --namespace gs-ctk --remote-appkit appkit/v2
   ```

5. Обновите целевую версию схемы:

   ```bash
   ./appkit.sh upgrade --config-path ./config.yaml --resgroup gs-cluster-1
   ```

6. Примените ресурс:

   ```bash
   kubectl apply -f config.yaml
   ```

После этого начнётся обновление прикладного решения (и при необходимости БД) в соответствии с выбранными флагами.

### Вариант B. Горячее обновление без nscli (вручную)

1. Включите hot reload и настройте "осушение" в `GlobalConfiguration`.

2. Сформируйте архив `applib.zip` (и при необходимости `appsrc`).

3. Сгенерируйте `applib.zip.sha256` рядом с архивом (пример скрипта тот же, что и в обычном обновлении).

4. Загрузите архив и `applib.zip.sha256` на системное NFS-хранилище.

5. В конфигурационном ресурсе обновите:

    * путь к комплекту (`path`);
    * `applib_sha256` (и `appsrc_sha256`, если используется `appsrc`);
    * счётчики: `globalserver_instance` и `database_schema_version`

6. Примените ресурс:

   ```bash
   kubectl apply -f config.yaml
   ```

## Режимы обновления базы данных

Есть два режима обновления базы данных:

* Через запуск мигратора на поде global_server_excl по команде nsctl.
* Через ресурс Kubernetes типа Job с запуском отдельного пода.

По умолчанию используется первый способ, но второй способ имеет ряд преимуществ:

1. Процесс обновления запускается через nsctl, но не зависит от него.
2. Запуск временного сервера приложения позволяет изолировать ошибки, связанные с нагоном релиза.

В будущем, запуск через Job заменит собой запуск мигратора на поде global_server_excl.

Чтобы выбрать режим, используйте интерактивный мастер для настройки параметров группы ресурсов:

```bash
./configmgr.sh configure_resgroup --config-path config.yaml --resgroup gs-cluster-1
```

```text

Настройка группы ресурсов: gs-cluster-1
=======================================

...
Включить обновление при помощи ресурса Kubernetes типа Job?[да,нет]:да
Укажите размер кучи Java (Xmx) для Job обновления:3500M
Введите запрос CPU для globalserver:2
Введите запрос MEMORY для globalserver:4G
Введите лимиты CPU для globalserver:2
Введите лимиты MEMORY для globalserver:4G
Введите запрос CPU для systemagent:1
Введите запрос MEMORY для systemagent:250M
Введите лимиты CPU для systemagent:1
Введите лимиты MEMORY для systemagent:500M
...

```

Режим также можно изменить, установив значение параметра группы ресурсов `upgrade_job.enabled` в `true` или `false`.

При включенном обновлении через Job после выполнения `./appkit.sh upgrade` (или изменения параметра группы ресурсов
`database_schema_version` другим способом) и применения конфигурационного ресурса, nsctl должен удалить старый Job
вместе с созданным им подом, и создать новый.

Job и под обновления можно определить по метке (label) `global-system.ru/is-upgrade-job-pod-for`, значение которого
соответствует названию группы ресурсов. Название Job состоит из префикса `upgrade-job-` и названия группы ресурсов,
например, `upgrade-job-gs-cluster-1`.

Название Job обновления состоит из префикса `upgrade-job-` и названия группы ресурсов, например, `upgrade-job-gs-cluster-1`.

По тем же меткам определяется Job [проверки горячего обновления](#проверка-возможности-горячего-обновления): у него
метка `global-system.ru/dedicated-app-server-job-type` имеет значение `hot-reload-check`, а название состоит из
префикса `hot-reload-check-job-` и названия группы ресурсов, например, `hot-reload-check-job-gs-cluster-1`.

## Обновление кластерных утилит

1. Сохраните текущие данные

```bash
mv ~/nscli/workspace ~/workspace_backup
cp ~/nscli/config.yaml ~/config.yaml_backup
```

```{note}
По умолчанию конфигурационный файл находится в ~/nscli/config.yaml.
Если у вас используется другой путь или имя файла - сохраните соответствующий .yaml.
```

2. Скачайте и распакуйте новую версию

```bash
cd ~
wget --backups=1 --user=<пользователь> --ask-password "https://repo.global-system.ru/artifactory/general/ru/bitec/gs-ctk-nscli/SNAPSHOT/gs-ctk-nscli-SNAPSHOT.zip"
unzip -o gs-ctk-nscli-SNAPSHOT.zip -d nscli
chmod +x nscli/bin/*.sh
./nscli/bin/install.sh
```

3. Восстановите сохранённые данные

```bash
rm -rf ~/nscli/workspace
mv ~/workspace_backup ~/nscli/workspace
cp ~/config.yaml_backup ~/nscli/config.yaml
```

4. Обновите кластер

```
helm upgrade gs-ctk ~/nscli/helm_chart -f values.yaml
```