Использование ADCM Installer
ADCM Installer представляет собой написанный на языке Go инструмент для облегчения процессов установки, обновления и настройки инсталляций ADCM. Он позволяет расширить функциональность Docker Compose за счет хранения секретов (secrets).
ADCM Installer включает следующие пакеты:
-
Docker Compose — управляет жизненным циклом Docker-контейнеров.
-
age-encryption — кодирует и декодирует конфиденциальные данные (например, имя пользователя и пароль для подключения к базе данных).
Подробности возможных сценариев использования ADCM Installer приведены в разделе Сценарии использования.
Начало работы с ADCM Installer
ПРИМЕЧАНИЕ
В случае использования CentOS версия операционной системы должна быть не ниже версии 8.
|
Следуйте инструкциям ниже для установки ADCM Installer:
-
Установите Docker. Для получения подробной информации обратитесь к документации Docker.
-
Загрузите файл 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. Этот параметр игнорируется при указании флага |
— |
ADCM database port |
uint16 |
Номер порта для подключения к базе данных ADCM. Этот параметр игнорируется при указании флага |
5432 |
ADCM database name |
string |
Имя базы данных ADCM |
adcm |
ADCM database user |
string |
Имя пользователя для подключения к базе данных ADCM |
adcm |
ADCM database password |
string |
Пароль пользователя для подключения к базе данных ADCM |
— |
Postgres SSL mode |
string |
Флаг, используемый для установления SSL-соединения к базе данных PostgreSQL. Этот параметр игнорируется при указании флага
Описание каждого значения приведено в статье Настройка ADCM для использования внешней базы данных |
— |
ADCM database SSL CA file path |
string |
Расположение файла, содержащего SSL-сертификат, подписанный центром сертификации (Certificate Authority, CA). Этот параметр игнорируется, если SSL-соединение не установлено, то есть в качестве значения параметра |
— |
ADCM database SSL certificate file path |
string |
Расположение файла SSL-сертификата клиента. Этот параметр игнорируется, если SSL-соединение не установлено, то есть в качестве значения параметра |
— |
ADCM database SSL private key file path |
string |
Расположение секретного ключа, используемого для SSL-сертификата клиента. Этот параметр игнорируется, если SSL-соединение не установлено, то есть выбрано значение |
— |
ADCM volume name or path |
string |
Название тома (volume) контейнера ADCM (в приведенном выше примере — |
adcm |
ADCM image |
string |
Репозиторий, в котором хранится Docker-образ контейнера ADCM (в приведенном выше примере — |
hub.arenadata.io/adcm/adcm |
ADCM image tag |
string |
Тег Docker-образа контейнера ADCM (в приведенном выше примере — |
2.6.0 |
ADCM publish port |
uint16 |
Номер порта локального хоста, на котором запускается контейнер ADCM (в приведенном выше примере — |
8000 |
ADCM url |
uint16 |
URL хоста, на котором разворачивается контейнер ADCM. Указывается в формате: |
IP-адрес хоста, на котором запущен контейнер ADCM, и номер порта ADCM, указанный в параметре |
ADPG superuser password |
string |
Пароль роли с правами superuser, который устанавливается при инициализации базы данных PostgreSQL |
— |
ADPG image |
string |
Репозиторий, в котором хранится Docker-образ контейнера ADPG (в приведенном выше примере — |
hub.arenadata.io/adcm/postgres |
ADPG image tag |
string |
Тег Docker-образа контейнера ADPG (в приведенном выше примере — |
v16.3.1 |
ADPG publish port |
uint16 |
Номер порта локального хоста, на котором запускается контейнер ADPG (в приведенном выше примере — |
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, с помощью которого выполняются следующие действия:
-
Создание и запуск контейнера
my-adcm-adpg-1
. -
Создание базы данных PostgreSQL.
-
Создание и запуск контейнера
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
. При выполнении команды подтвердите удаление томов.