Help:XSvacer:Docker

From Svacer Wiki

Управление 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.

Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:Docker&oldid=1971"