Help:XSvacer:Docker

Управление docker-контейнерами

Примечание: данная функциональность входит в набор расширений XSvacer.

Данная функциональность предназначена для управления docker-контейнерами, содержащими компоненты XSvacer.

Управление docker-контейнерами осуществляется с помощью взаимодействия с docker-хостом с использованием REST API.

Возможны два сценария использования docker'а:

1. Подключение к существующему ("внешнему") docker-хосту;
2. Запуск управляемого svacer'ом rootless-хоста.

Активация функциональности

Для активации функциональности необходимо указать флаг --xsvacer.features docker при запуске svacer'а.

Примечание: на базе данной функциональности осуществляется запуск компонентов других расширений XSvacer. В таком случае её необязательно запускать явно: она будет запущена, если будет запущена зависимая функциональность.

Конфигурация

Управление настройками функциональности осуществляется с помощью конфигурационного yaml-файла svacer.cfg.

Раздел конфигурации для управления функциональностью - xsvacer/docker.

Раздел содержит перечисление настроек подключаемых хостов docker'а xsvacer/docker/hosts, на которые в дальнейшем будут ссылаться зависимые функциональности. Каждое поле в xsvacer/docker/hosts/... является идентификатором подключения и содержит его конфигурацию.

xsvacer:
  docker:
    hosts:
      dockerhost1:
        type: ...
        host: ...
        disabled: false
        ...
      dockerhost2:
        ...
  
  dependentFeature1:
    ...
    docker:
      hostid: dockerhost1
    ...
  dependentFeature2:
    ...
    docker:
      hostid: dockerhost2
    ...

Примечание: в случае отсутствия файла svacer.cfg или отсутствии раздела xsvacer/docker будет использоваться конфигурация по умолчанию (см. ниже)

Общие параметры docker-хостов

Название	Тип данных	Описание
type	enum: external, managed, remote	Тип подключаемого docker-хоста: external - "внешний" docker-хост managed - "управляемый" rootless-хост remote - аналогичен external, но host должен быть задан
hostd	url	Url docker-хоста
disabled	bool	Конфигурация хоста неактивна Неактивная конфигурация не может использоваться в других функциональностях

Использование существующего ("внешнего") docker-хоста

Данный способ взаимодействия предполагает подключение к существующему хосту docker'а.

Доступные варианты подключения:

1. К локальному хосту через unix-сокет;
2. К удалённому хосту по ssh;
3. К удалённому хосту по http;
4. К к удалённому хосту по https.

Для использования "внешнего" хоста docker'а в конфигурационном файле нужно указать type: external, а также задать адрес хоста, соответствующий типу подключения:

docker:
  hosts:
    default:
      type: external
      host: "unix:///path/to/docker.sock"
    remote1:
      type: external
      host: "ssh://docker-user@docker-host"
    remote2:
      type: external
      host: "http://docker-host-ip-address:2375"
    remote3:
      type: external
      host: "https://docker-host-ip-address:2376"
      clienttls: ...

Если параметр host не задан, то по умолчанию будет использоваться unix-сокет.

Подключение к локальному хосту через unix-сокет

При обычном запуске процесса dockerd взаимодействие с хостом осуществляется с помощью unix-сокета unix:///var/run/docker.sock.

Доступ к сокету может получить пользователь с правами root или обычный пользователь, входящий в группу docker (https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option).

Пользователь, под которым запускается svacer, должен иметь права доступа к указанному unix-сокету docker'а (https://docs.docker.com/engine/install/linux-postinstall/).

Внимание! При отсутствии прав доступа к unix-сокету использование данной функциональности будет приводить к ошибке.
В таком случае можно воспользоваться rootless-хостом (см. ниже).

Если для взаимодействия с хостом docker'а используется дефолтный unix-сокет unix:///var/run/docker.sock, то в конфигурации поле host можно не указывать:

docker:
  hosts:
    default:
      type: external

Подключение к удалённому хосту по ssh

Чтобы подключиться к удалённому хосту docker'а по ssh, необходимо в поле host указать схему ssh://, реквизиты пользователя и название/адрес docker-хоста:

docker:
  hosts:
    default:
      type: external
      host: "ssh://docker-user@docker-host"

Указанный пользователь должен иметь возможность подключения по ssh к указанному хосту, а также иметь права доступа к unix-сокету docker'а на удалённом хосте (https://docs.docker.com/engine/security/protect-access/#use-ssh-to-protect-the-docker-daemon-socket)

Подключение к удалённому хосту по http

Чтобы подключиться к удалённому хосту docker'а по http, необходимо в поле host указать схему http:// и адрес docker-хоста:

docker:
  hosts:
    default:
      type: external
      host: "http://docker-host-ip-address:port"

Внимание! Данный тип подключения является *небезопасным*, т.к. при использовании API docker'а не производится шифрование сетевого трафика и аутентификация клиента при доступе к docker'у. Чтобы создать безопасное сетевое соединение необходимо использовать подключение по https (tls) (см. ниже)

Подключение к удалённому хосту по https (tls)

Docker-хост может предоставлять доступ по https (https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket).

В таком случае для доступа к API необходимо иметь сертификат удостоверяющего центра, клиентский ключ и сертификат.

В конфигурационном файле пути к ключам указываются в поле xsvacer/docker/{docker-host-id}/clienttls:

docker:
  hosts:
    default:
      type: external
      host: "https://docker-host-ip-address:2376"
      clienttls:
        ca:   "/path/to/ca.pem"
        cert: "/path/to/cert.pem"
        key:  "/path/to/key.pem"

Специфичные настройки для подключения к https хосту

Название	Тип данных	Описание
clienttls/	map	Настройки TLS
clienttls/ca	url	Путь к файлу сертификата удостоверяющего центра
clienttls/cert	url	Путь к клиентскому сертификату
clienttls/key	url	Путь к клиентскому ключу

Памятка при использовании подключения к удалённым хостам

Примечание: если используется подключения к удалённому хосту docker'а, в настройке биндингов контейнеров необходимо указывать ip-адрес доступного сетевого интерфейса хоста, т.к. при привязке контейнера к 0.0.0.0 на машине хоста контейнеры будут недоступны снаружи.

Запуск "управляемого" rootless-хоста

В случае отсутствия доступного docker-хоста, либо если не хочется его загромождать контейнерами svacer'а, предусмотрена возможность запуска "управляемого" rootless-хоста, не требующего настройки дополнительных прав для пользователя, под которым запускается svacer (https://docs.docker.com/engine/security/rootless/).

Управление (запуск и остановка) rootless-хостом будет осуществлять svacer.

Внимание! Доступно только для linux'а.

Для использования данного rootless-хоста в конфигурационном файле для хоста нужно указать type: managed.

docker:
  hosts:
    local:
      type: managed
      ...

Специфичные настройки для rootless-хоста

Название	Тип данных	Описание
managed/	map	параметры запуска rootless-хоста
managed/executable	string	исполняемый файл. Должен быть доступен в $PATH или содержать абсолютный путь формат: имя исполняемого фала, доступного через переменную $PATH или: абсолютный путь до исполняемого файла
managed/env	[]string	список переменных окружения для процесса rootless-хоста формат: "НАЗВАНИЕ_ПЕРЕМЕННОЙ=значение переменной"
managed/args	[]string	список аргументов запуска rootless-хоста формат: "--название-аргумента=значение-аргумента" или: "--название-аргумента", "значение-аргумента" или: "--название-флага"
managed/loglevel	string	уровень логирования, на котором будут записываться stdout и stderr процесса rootless-хоста
managed/logprefix	string	префикс в логе, которым будут помечаться записи из stdout и stderr процесса rootless-хоста
managed/healthcheck	map	параметры проверки доступности rootless-хоста
managed/healthcheck/interval	golang duration string	интервал проверки
managed/healthcheck/retries	int	количество попыток проверки до ошибки доступности

В значениях managed/env и managed/args можно использовать имена переменных окружения в формате ${НАЗВАНИЕ_ПЕРЕМЕННОЙ}.

Рекомендуемая конфигурация rootless-хоста

При запуске dockerd-rootless.sh без параметров папки с артефактами docker'а создаются во вложенных папках внутри /run/user/$UID/. Для лучшей локализации артефактов svacer'а рекомендуется использовать следующие настройки для rootless-хоста:

docker:
  hosts:
    local:
      type: managed
      host: "unix://${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.sock"

      managed:
        executable: "dockerd-rootless.sh"
        env:
          - "DOCKERD_ROOTLESS_ROOTLESSKIT_STATE_DIR=${USER_CACHE_DIR}/svacer-docker-host/state-dir/"
        args:
          - "--data-root=${USER_CACHE_DIR}/svacer-docker-host/data-root/"
          - "--exec-root=${USER_CACHE_DIR}/svacer-docker-host/exec-root/"
          - "--pidfile=${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.pid"
        logLevel: info
        logPrefix: "DOCKER HOST: "
        healthCheck:
          interval: 1s
          retries: 10

Здесь вместо ${USER_CACHE_DIR} будет подставлен путь $HOME/.cache на unix-подобных системах или %LocalAppData% на windows.

При таких настройках все артефакты хоста docker'а будут храниться внутри папки ${USER_CACHE_DIR}/svacer-docker-host.

Использование "неуправляемого" rootless-хоста

В случае необходимости управления rootless-хостом без участия svacer'а, его можно запустить отдельно. Например, командой:

DOCKERD_ROOTLESS_ROOTLESSKIT_STATE_DIR=/home/$USER/.cache/svacer-docker-host/state-dir/ dockerd-rootless.sh --host unix:///home/$USER/.cache/svacer-docker-host/svacer-docker.sock --data-root=/home/$USER/.cache/svacer-docker-host/data-root/ --exec-root=/home/$USER/.cache/svacer-docker-host/exec-root/ --pidfile=/home/$USER/.cache/svacer-docker-host/svacer-docker.pid

В таком случае подключиться к данному хосту можно как к "внешнему" (type: external), указав адрес unix-сокета. Например:

docker:
  hosts:
    unmanaged:
      type: external
      host: "unix:///home/${USER}/.cache/svacer-docker-host/svacer-docker.sock"

Конфигурация по умолчанию

Данная конфигурация применяется по умолчанию, если в конфигурационном файле svacer.cfg отсутствует раздел xsvacer/docker:

docker:
  hosts:
    default:
      type: external
    local:
      type: managed
      host: "unix://${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.sock"
      disabled: true

      managed:
        executable: "dockerd-rootless.sh"
        env:
          - "DOCKERD_ROOTLESS_ROOTLESSKIT_STATE_DIR=${USER_CACHE_DIR}/svacer-docker-host/state-dir/"
        args:
          - "--data-root=${USER_CACHE_DIR}/svacer-docker-host/data-root/"
          - "--exec-root=${USER_CACHE_DIR}/svacer-docker-host/exec-root/"
          - "--pidfile=${USER_CACHE_DIR}/svacer-docker-host/svacer-docker.pid"
        logLevel: info
        logPrefix: "DOCKER HOST: "
        healthCheck:
          interval: 1s
          retries: 10

Внимание! При наличии раздела xsvacer/docker в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.

Изменение конфигурационных параметров с помощью переменных окружения

Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения XSVACER_DOCKER_HOSTS_{id хоста}[_параметр]={значение параметра}.

Например, для активации rootless-хоста xsvacer/hosts/local можно указать такие значения переменных окружения при запуске svacer'а:

XSVACER_DOCKER_HOSTS_LOCAL_DISABLED=false

Известные проблемы

rootless-хост продолжает работать при некорректной остановке svacer'а

При некорректном завершении работы svacer'а (например, при получении сигнала SIGKILL) процесс rootless-хоста останется запущенным в системе.

При этом svacer потеряет возможность управления (запуска/остановки) этого процесса.

При последующем запуске svacer попробует повторно запустить rootless-хост и получит сообщение типа [rootlesskit:parent] error: failed to lock /path/to/svacer-docker-host/state-dir/lock, another RootlessKit is running with the same state directory?

При этом, если настройки не менялись, зависимые функциональности смогут получить доступ к "неконтролируемому" rootless-хосту, т.к. адрес unix-сокета хоста известен.

Процесс "неконтролируемого" rootless-хоста при необходимости может быть остановлен вручную. Например с помощью отправки сигнала SIGTERM.