Help:XSvacer:Docker

From Svacer Wiki
Revision as of 15:47, 19 June 2024 by Akuzmin (talk | contribs) (change to info/warn boxes)

(diff) ← Older revision | Approved revision (diff) | Latest revision (diff) | Newer revision → (diff)
Данная функциональность входит в набор расширений 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.

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