Help:XSvacer:Docker

Данная функциональность входит в набор расширений XSvacer

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

Данная функциональность предназначена для управления 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 должен быть задан
host	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-сокет.

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

Подключение к локальному хосту через 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	Путь к клиентскому ключу

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

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

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

Для использования данного 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

При таких настройках все артефакты хоста 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

При некорректном завершении работы Svac4r (например, при получении сигнала 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.