Использование ADCM Installer

ADCM Installer представляет собой написанный на языке Go инструмент для облегчения процессов установки, обновления и настройки инсталляций ADCM. Он позволяет расширить функциональность Docker Compose за счет хранения секретов (secrets).

ADCM Installer включает следующие пакеты:

  • Docker Compose — управляет жизненным циклом Docker-контейнеров.

  • age-encryption — кодирует и декодирует конфиденциальные данные (например, имя пользователя и пароль для подключения к базе данных).

Подробности возможных сценариев использования ADCM Installer приведены в разделе Сценарии использования.

Начало работы с ADCM Installer

ПРИМЕЧАНИЕ
В случае использования CentOS версия операционной системы должна быть не ниже версии 8.

Следуйте инструкциям ниже для установки ADCM Installer:

  1. Установите Docker. Для получения подробной информации обратитесь к документации Docker.

  2. Загрузите файл adi в директорию /usr/local/bin и настройте для него права доступа следующим образом:

    $ sudo wget -O /usr/local/bin/adi https://github.com/arenadata/adcm-installer/releases/tag/<version>/adi
    $ sudo chmod +x /usr/local/bin/adi

    где <version> — версия ADCM Installer.

    Дождитесь завершения загрузки файла.

Чтобы получить краткую справочную информацию о командах ADCM Installer, выполните следующую команду:

$ adi --help

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

Command line tool for installing Arenadata products

Usage:
  adcm-installer [flags]
  adcm-installer [command]

Available Commands:
  adcm-versions List versions of Arenadata products
  apply         Apply a configuration by file name
  completion    Generate the autocompletion script for the specified shell
  components    Manage installed components
  delete        Delete resources by file name or installation name
  help          Help about any command
  init          Initialize a new configuration
  list          List running ADCM installation
  secrets       Manage secrets

Flags:
  -h, --help      help for adcm-installer
      --version   Print the version and exit

Сценарии использования

ADCM Installer поддерживает следующие команды:

  • init

  • apply

  • completion

  • list

  • adcm-versions

  • secrets

  • delete

Описание команд и примеры их использования приведены ниже.

Инициализация файла конфигурации

Команда init создает файл конфигурации, описанный ниже, который необходим для развертывания инсталляции ADCM.

Например, для инициализации файла конфигурации ADCM с базой данных PostgreSQL выполните следующую команду с указанием флага --adpg:

$ adi init my-adcm --adpg

где my-adcm — имя инсталляции ADCM, которая включает в себя Docker-контейнеры my-adcm-adpg-1 и my-adcm-adcm-1.

Чтобы создать учетную запись для работы с базой данных и настроить параметры подключения к ней, воспользуйтесь интерактивным режимом, указав флаг -i или --interactive:

$ adi init my-adcm --adpg -i
ПРИМЕЧАНИЕ
Без указания флага --adpg будут запрошены настройки для подключения к внешней базе данных PostgreSQL.

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

Запрашиваемые параметры
Параметр Тип Описание Значение по умолчанию

ADCM database host

string

Адрес сервера базы данных ADCM. Этот параметр игнорируется при указании флага --adpg

 — 

ADCM database port

uint16

Номер порта для подключения к базе данных ADCM. Этот параметр игнорируется при указании флага --adpg

5432

ADCM database name

string

Имя базы данных ADCM

adcm

ADCM database user

string

Имя пользователя для подключения к базе данных ADCM

adcm

ADCM database password

string

Пароль пользователя для подключения к базе данных ADCM

 — 

Postgres SSL mode

string

Флаг, используемый для установления SSL-соединения к базе данных PostgreSQL. Этот параметр игнорируется при указании флага --adpg. Возможные значения:

  • disable

  • allow

  • prefer

  • require

  • verify ca

  • verify full

Описание каждого значения приведено в статье Настройка ADCM для использования внешней базы данных

 — 

ADCM database SSL CA file path

string

Расположение файла, содержащего SSL-сертификат, подписанный центром сертификации (Certificate Authority, CA). Этот параметр игнорируется, если SSL-соединение не установлено, то есть в качестве значения параметра Postgres SSL mode выбрано disable

 — 

ADCM database SSL certificate file path

string

Расположение файла SSL-сертификата клиента. Этот параметр игнорируется, если SSL-соединение не установлено, то есть в качестве значения параметра Postgres SSL mode выбрано disable

 — 

ADCM database SSL private key file path

string

Расположение секретного ключа, используемого для SSL-сертификата клиента. Этот параметр игнорируется, если SSL-соединение не установлено, то есть выбрано значение disable

 — 

ADCM volume name or path

string

Название тома (volume) контейнера ADCM (в приведенном выше примере — my-adcm-adcm-1) или полный путь к директории с данными SQLite. Параметр используется для миграции данных ADCM из SQLite в PostgreSQL

adcm

ADCM image

string

Репозиторий, в котором хранится Docker-образ контейнера ADCM (в приведенном выше примере — my-adcm-adcm-1)

hub.arenadata.io/adcm/adcm

ADCM image tag

string

Тег Docker-образа контейнера ADCM (в приведенном выше примере — my-adcm-adcm-1)

2.6.0

ADCM publish port

uint16

Номер порта локального хоста, на котором запускается контейнер ADCM (в приведенном выше примере — my-adcm-adcm-1)

8000

ADCM url

uint16

URL хоста, на котором разворачивается контейнер ADCM. Указывается в формате: http://<ip_address>:<port>/

IP-адрес хоста, на котором запущен контейнер ADCM, и номер порта ADCM, указанный в параметре ADCM publish port

ADPG superuser password

string

Пароль роли с правами superuser, который устанавливается при инициализации базы данных PostgreSQL

 — 

ADPG image

string

Репозиторий, в котором хранится Docker-образ контейнера ADPG (в приведенном выше примере — my-adcm-adpg-1)

hub.arenadata.io/adcm/postgres

ADPG image tag

string

Тег Docker-образа контейнера ADPG (в приведенном выше примере — my-adcm-adpg-1)

v16.3.1

ADPG publish port

uint16

Номер порта локального хоста, на котором запускается контейнер ADPG (в приведенном выше примере — my-adcm-adpg-1)

5432

Если значения параметров не указаны, то в качестве значений имен и параметров конфигурации Docker-контейнеров будут использованы значения по умолчанию, а пароли будут сгенерированы автоматически.

После выполнения команды, описанной выше, будут созданы два файла:

  • adcm.yaml (или adcm.yml) — файл конфигурации инсталляции ADCM в YAML-формате;

  • age.key — файл, содержащий приватный ключ в формате AGE-SECRET-KEY-1… для доступа к конфиденциальным данным (секретам), которые хранятся в файле adcm.yaml (или adcm.yml).

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

  • --force — позволяет перезаписать существующий файл конфигурации;

  • -o или --output — позволяет сохранить файл конфигурации с заданным именем, например: --output /<file_path>, где <file_path> — абсолютный путь к файлу конфигурации в YAML-формате, включая имя файла;

  • --from-config — позволяет указать файл, содержащий значения параметров, запрашиваемых при использовании интерактивного режима;

  • --age-key-file — определяет расположение файла с приватным ключом;

  • --age-key — определяет приватный ключ, например:

    $ adi init my-adcm --age-key AGE-SECRET-KEY-1...
    ПРИМЕЧАНИЕ
    Также приватный ключ можно передать через переменную окружения AGE_KEY, например: export AGE_KEY=AGE-SECRET-KEY-1…​.
Структура файла конфигурации
# Название проекта
name: my-adcm
# Конфигурации Docker-контейнеров my-adcm-adcm-1 и my-adcm-adpg-1
services:
  adcm:
    # Добавление поддержки определенных возможностей (capabilities) ядра Linux в Docker-контейнер. Список поддерживаемых возможностей приведен в документации Linux
    cap_add:
      - CAP_CHOWN
      - CAP_SETUID
      - CAP_SETGID
    # Отключение поддержки определенных возможностей ядра Linux
    cap_drop:
      - ALL
    # Последовательность запуска Docker-контейнеров. В данном случае контейнер my-adcm-adcm-1 будет запущен после запуска контейнера my-adcm-adpg-1
    depends_on:
      adpg:
        # Условие, при котором запустится контейнер my-adcm-adcm-1, в данном случае -- ожидание работоспособности контейнера my-adcm-adpg-1
        condition: service_healthy
        restart: true
        required: true
    # Пользовательское имя хоста для Docker-контейнера
    hostname: my-adcm-adcm
    # Имя образа для создания Docker-контейнера
    image: hub.arenadata.io/adcm/adcm:2.5.0
    # Метаданные для добавления в Docker-контейнер
    labels:
      app.arenadata.io/type: adcm
    # Создание выделенной сети для Docker-контейнера на хосте
    networks:
      default: null
    # Сопоставление портов между хостом и Docker-контейнером
    ports:
      - mode: ingress
        # Порт Docker-контейнера
        target: 8000
        # Публичный (опубликованный) порт хоста
        published: "8000"
        # Протокол порта
        protocol: tcp
    # Извлечение Docker-образа из реестра при каждом запуске контейнера
    pull_policy: always
    # Политика перезапуска Docker-контейнера. В данном случае будет выполняться перезапуск контейнера во всех случаях, кроме случая преднамеренной остановки контейнера
    restart: unless-stopped
    # Предоставление доступа Docker-контейнеру к конфиденциальным данным, определенным элементом верхнего уровня x-secrets
    secrets:
      - source: adcm-db-name
        target: /run/secrets/adcm-db-name
      - source: adcm-db-user
        target: /run/secrets/adcm-db-user
      - source: adcm-db-pass
        target: /run/secrets/adcm-db-pass
    # Именованные тома, которые доступны Docker-контейнеру
    volumes:
      - type: volume
        source: my-adcm-adcm
        target: /adcm/data
        volume: {}
  adpg:
    cap_drop:
      - ALL
    hostname: my-adcm-adpg
    # Проверка работоспособности Docker-контейнера с помощью утилиты pg_isready
    healthcheck:
      test:
        - CMD-SHELL
        - pg-entrypoint isready postgres
      timeout: 3s
      interval: 10s
      retries: 3
    image: mybackspace/adpg:16.4
    labels:
      app.arenadata.io/type: adpg
    networks:
      default: null
    pull_policy: always
    # Запуск Docker-контейнера без прав внесения изменений в файловую систему
    read_only: true
    restart: unless-stopped
    # Предотвращение повышения привилегий в Docker-контейнере
    security_opt:
      - no-new-privileges
    # Пользователь, от чьего имени будет запускаться Docker-контейнер
    user: 10001:10001
    volumes:
      - type: volume
        source: my-adcm-adpg
        target: /data
        volume: {}
# Именованная сеть, позволяющая Docker-контейнерам взаимодействовать друг с другом
networks:
  default:
    name: my-adcm_default
# Тома, которые будут созданы при первом запуске Docker-контейнеров
volumes:
  my-adcm-adcm:
    name: my-adcm-adcm
  my-adcm-adpg:
    name: my-adcm-adpg
# Конфиденциальные данные, которые используются Docker-контейнерами
x-secrets:
  age_recipient: age1htxwzyy75rlrhut6jry0uet3ks7cw44w80jl2gktukp9m800auyqspyfws
  data:
    adcm-db-name: YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBoMWh2d2E5TU8xR0RkQVdCalB6ZUEvZUh5d2ZqN3hpbEJBK2taMHZCM3hvCkNzbVNudHlSVUIxY0hCT3lDaHJNVld0VHlHK1hRU2RjMzRnUGxjaUdBUDAKLS0tIEFIcmVEVnpQVE5iVFdwQ0NRcVpNQ0w5TWRRQTB3ZmZBemZVbFcySk5ZOEEK3Y7P8Lgl0+Gx9+UwJQOzRheRbVxox/XaXEj6M1xMukn56AgJ
    adcm-db-pass: YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBWRXR6eEduL3piZk1oODd5QnNENUZPTHhzMXhxczRMNTVhd0VrUWJoYlNVCnV5OHBadTlpMlpTWnc4SXFoMThqbHE4UVBheVloNnk1U0o1N2E2dHZaZFEKLS0tIFViUm96eXJFWWJJY3o1WHlNYmdneVRQUTVRL3ZKbFlhVFF2Z2l4cDZ0QUUKr7EYAMlS/h6TeoZV4bgBKqlVDUysOKGgAU1qWjCOezUWA/2hARb1Kt928jB+Qn8i
    adcm-db-user: YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAzYm95bDZDV1NrbGpuYWdXN21IaUZwSFVaSHlVNVZXd2tGR1RhWE1XcTFjCnY0RUFJQnZwcUxWWk40bjUxWi9xdHM3TFpOUTZlYWk0elpSU21mUnlTbWcKLS0tIHJvYjZHNGk4UUNDMnFCd3NFVGsvV0tyYWprQUw2Wm1pMGNHMWRYYkIwTlEK4pYnqi8iDd2GefTUK2SLz8Q3BO5Re4DHmV33+TKiUQcjTXV6
    adpg-password: YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBObFI3MUptcW1ZdSs0ZGc2Tlp3SXprRGptdWhld01RekxjakZNQ1NIWFZNCnZDbzYzUXVzNUtvS3dYbkxhNnNNV2k2TXJCZWNQeVI2Y2c0aXlKdjk0bUUKLS0tIDZEUWFNRGRScFN0Y2s5WUQwMzUzQTJKNTAzRTBmVXhWNFQ0V2tXZUN6S00KTA1a/+YkjQ1bzr4/9I5GTHAnFHgCwblCW656C8O2qyw2NmbZtgeypIWf6n1yz2wg

Развертывание

Команда apply позволяет развернуть инсталляцию ADCM при наличии созданных файлов adcm.yaml (или adcm.yml) и age.key:

$ sudo adi apply

При выполнении команды формируется файл docker-compose.yaml, с помощью которого выполняются следующие действия:

  1. Создание и запуск контейнера my-adcm-adpg-1.

  2. Создание базы данных PostgreSQL.

  3. Создание и запуск контейнера my-adcm-adcm-1.

Чтобы убедиться в успешном развертывании инсталляции ADCM, выполните команды, описанные в статье Установка.

Для развертывания инсталляции ADCM в режиме отладки укажите флаг --dry-run. В результате сформируется файл docker-compose.yaml без создания и запуска контейнеров.

Чтобы получить информацию о других флагах, которые можно указать при выполнении команды apply, выполните следующую команду:

$ adi apply --help
ПРИМЕЧАНИЕ
С помощью флага --help также можно получить информационную справку о других командах, описанных ниже.

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

Команда completion позволяет сгенерировать скрипты автодополнения команд ADCM Installer по клавише Tab для следующих оболочек:

  • Bash

  • fish

  • PowerShell

  • Zsh

ПРИМЕЧАНИЕ
Для оболочки Bash предварительно установите пакет bash-completion, необходимый для работы скрипта.

Для получения инструкции по использованию сгенерированного скрипта воспользуйтесь командой:

$ adi completion <shell> --help

где <shell> — имя оболочки.

Просмотр развернутых инсталляций ADCM

Команда list позволяет получить следующую информацию об инсталляциях ADCM:

  • NAMES — имя инсталляции ADCM;

  • STATUS — статус и количество Docker-контейнеров;

  • CONFIG FILES — путь к файлу конфигурации.

Пример команды:

$ sudo adi list

Пример результата выполнения команды:

NAMES               STATUS              CONFIG FILES
my-adcm             running(3)          /home/adelya/adcm-installer/adcm.yaml

Для отображения информации об остановленных инсталляциях ADCM укажите флаг --all.

Просмотр доступных версий ADCM

Команда adcm-versions позволяет проверить версии Docker-образа ADCM, доступные для скачивания из Arenadata Docker Registry:

$ adi adcm-versions --all

Пример результата выполнения команды:

2.5.1
2.5.0
2.4.0
2.3.0
2.2.0
2.1.2
2.1.1
2.1.0
2.0.0

Для отображения пяти последних версий выполните команду adcm-versions без указания флага --all.

Управление секретами

Команда secrets позволяет управлять секретами, указанными в файле конфигурации, следующим образом:

  • secrets new-key — генерация нового приватного ключа, который по умолчанию будет сохранен в файле age.key;

  • secrets show — просмотр секретов, заданных при инициализации;

  • secrets set — определение новых значений секретов, например:

    $ adi secrets set adcm-db-pass 1234

Остановка и удаление развернутых инсталляций ADCM

Команда delete предназначена для остановки развернутых инсталляций ADCM с использованием заданного файла конфигурации или имени развернутой инсталляции.

Если в директории, в которой запускается команда, находятся файлы adcm.yaml (или adcm.yml) и age.key, то команда будет выполнена автоматически, то есть без необходимости указания файла конфигурации или имени инсталляции:

$ sudo adi delete

В результате будет остановлена инсталляция ADCM с сохранением данных, указанных ранее при инициализации файла конфигурации.

Для удаления развернутой инсталляции ADCM, включая удаление связанных с инсталляцией томов, укажите флаг --volumes. При выполнении команды подтвердите удаление томов.

Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней