Help:XSvacer:Docker: Difference between revisions

From Svacer Wiki
mNo edit summary
(change to info/warn boxes)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Note|text=Данная функциональность входит в набор расширений XSvacer}}
= Управление docker-контейнерами =
= Управление docker-контейнерами =
'''Примечание:''' данная функциональность входит в набор расширений XSvacer.
Данная функциональность предназначена для управления docker-контейнерами, содержащими компоненты XSvacer.
 
Данная функциональность предназначена для управления docker-контейнерами содержащими компоненты XSvacer.


Управление docker-контейнерами осуществляется с помощью взаимодействия с docker-хостом с использованием [https://docs.docker.com/engine/api/latest/ REST API].
Управление docker-контейнерами осуществляется с помощью взаимодействия с docker-хостом с использованием [https://docs.docker.com/engine/api/latest/ REST API]


Возможны два сценария использования docker:
Возможны два сценария использования docker:
# Подключение к существующему ("внешнему") docker-хосту;
# Подключение к существующему ("внешнему") docker-хосту
# Запуск управляемого svacer'ом [https://docs.docker.com/go/rootless/ rootless-хоста].
# Запуск управляемого Svacer [https://docs.docker.com/go/rootless/ rootless-хоста]


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


'''Примечание:''' на базе данной функциональности осуществляется запуск компонентов других расширений XSvacer. В таком случае её не обязательно запускать явно: она будет запущена, если будет запущена зависимая функциональность.
{{Note|type=reminder|text=На базе данной функциональности осуществляется запуск компонентов других расширений XSvacer. В таком случае её необязательно запускать явно: она будет запущена, если будет запущена зависимая функциональность}}


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


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


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


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


  xsvacer:
  xsvacer:
Line 45: Line 45:
     ...
     ...


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


=== Общие параметры docker-хостов ===
=== Общие параметры docker-хостов ===
Line 54: Line 54:
!Описание
!Описание
|-
|-
|<code>type</code>
|type
|enum: <code>external</code>, <code>managed</code>, <code>remote</code>
|enum: <code>external</code>, <code>managed</code>, <code>remote</code>
|Тип подключаемого docker-хоста:
|Тип подключаемого docker-хоста:


* <code>external</code> - "внешний" docker-хост
* <code>external</code> "внешний" docker-хост
* <code>managed</code> - "управляемый" rootless-хост
* <code>managed</code> "управляемый" rootless-хост
* <code>remote</code> - аналогичен <code>external</code>, но <code>host</code> должен быть задан
* <code>remote</code> аналогичен <code>external</code>, но <code>host</code> должен быть задан
|-
|-
|<code>hostd</code>
|host
|url
|url
|Строка содержащая url docker-хоста
|URL docker-хоста
|-
|-
|<code>disabled</code>
|disabled
|bool
|bool
|Конфигурация хоста неактивна
|Конфигурация хоста неактивна
Line 73: Line 73:


=== Использование существующего ("внешнего") docker-хоста ===
=== Использование существующего ("внешнего") docker-хоста ===
Данный способ взаимодействия предполагает подключение к существующему хосту docker.
Данный способ взаимодействия предполагает подключение к существующему хосту docker.


Доступные варианты подключения:
Доступные варианты подключения:
# К локальному хосту через unix-сокет
# К удалённому хосту по SSH
# К удалённому хосту по HTTP
# К удалённому хосту по HTTPS


# К локальному хосту через unix-сокет;
Для использования "внешнего" хоста docker в конфигурационном файле нужно указать <code>type: external</code>, а также задать адрес хоста, соответствующий типу подключения:
# К удалённому хосту по ssh;
# К удалённому хосту по http;
# К к удалённому хосту по https.


Для использования "внешнего" хоста docker'а в конфигурационном файле нужно указать <code>type: external</code>, а также задать адрес хоста, соответствующий типу подключения:
  docker:
  docker:
   hosts:
   hosts:
Line 98: Line 98:
       host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"
       host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"
       clienttls: ...
       clienttls: ...
Если параметр <code>host</code> не задан, то по умолчанию будет использоваться unix-сокет.
Если параметр <code>host</code> не задан, то по умолчанию будет использоваться unix-сокет.
Если используется подключение к удалённому хосту docker, в настройке биндингов контейнеров необходимо указывать ip-адрес доступного сетевого интерфейса хоста, т. к. при привязке контейнера к 0.0.0.0 на машине хоста контейнеры будут недоступны снаружи.


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


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


Пользователь, под которым запускается svacer, должен иметь права доступа к указанному unix-сокету docker(https://docs.docker.com/engine/install/linux-postinstall/).
Пользователь, под которым запускается Svacer, должен иметь права доступа к указанному unix-сокету docker (https://docs.docker.com/engine/install/linux-postinstall/).
'''Внимание!''' При отсутствии прав доступа к unix-сокету у пользователя, под которым запускается svacer, использование данной функциональности зависимыми функциональностями будет приводить к ошибке.
В таком случае можно воспользоваться rootless-хостом (см. ниже).


Если для взаимодействия с хостом dockerиспользуется дефолтный unix-сокет <code>unix:///var/run/docker.sock</code>, то в конфигурации поле <code>host</code> можно не указывать:
{{Note|type=reminder|text=При отсутствии прав доступа к unix-сокету использование данной функциональности будет приводить к ошибке. В таком случае можно воспользоваться rootless-хостом (см. ниже)}}
 
Если для взаимодействия с хостом docker используется дефолтный unix-сокет <code>unix:///var/run/docker.sock</code>, то в конфигурации поле <code>host</code> можно не указывать:
  docker:
  docker:
   hosts:
   hosts:
Line 115: Line 118:
       type: external
       type: external


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


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


  docker:
  docker:
Line 125: Line 128:
       host: "<nowiki>ssh://docker-user@docker-host</nowiki>"
       host: "<nowiki>ssh://docker-user@docker-host</nowiki>"


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


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


Чтобы подключиться к удалённому хосту dockerпо http, необходимо в поле <code>host</code> указать схему <code>http://</code> и адрес docker-хоста:
Чтобы подключиться к удалённому хосту docker по HTTP, необходимо в поле <code>host</code> указать схему <code>http://</code> и адрес docker-хоста:
  docker:
  docker:
   hosts:
   hosts:
Line 136: Line 139:
       host: "<nowiki>http://docker-host-ip-address:port</nowiki>"
       host: "<nowiki>http://docker-host-ip-address:port</nowiki>"


'''Внимание!''' Данный тип подключения является *небезопасным*, т.к. при использовании API dockerне производится шифрование сетевого трафика и аутентификация клиента при доступе к docker. Чтобы создать безопасное сетевое соединение необходимо использовать подключение по https (tls) (см. ниже)
{{Note|type=error|text=Данный тип подключения является небезопасным, т. к. при использовании API docker не производится шифрование сетевого трафика и аутентификация клиента при доступе к docker. Чтобы создать безопасное сетевое соединение необходимо использовать подключение по HTTPS/TLS}}


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


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


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


В конфигурационном файле пути к ключам указываются в поле <code>xsvacer/docker/{docker-host-id}/clienttls</code>:
В конфигурационном файле пути к ключам указываются в поле <code>xsvacer/docker/{docker-host-id}/clienttls</code>
 
  docker:
  docker:
   hosts:
   hosts:
Line 151: Line 155:
       host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"
       host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"
       clienttls:
       clienttls:
         ca: "/path/to/ca.pem"
         ca:   "/path/to/ca.pem"
         cert: "/path/to/cert.pem"
         cert: "/path/to/cert.pem"
         key: "/path/to/key.pem"
         key: "/path/to/key.pem"


===== Специфичные настройки для подключения к https хосту =====
===== Специфичные настройки для подключения к https хосту =====
Line 179: Line 183:
|Путь к клиентскому ключу                         
|Путь к клиентскому ключу                         
|}
|}
==== Памятка при использовании подключения к удалённым хостам ====
NOTE: при использовании подключения к удалённому хосту docker'а, при настройке биндингов создаваемых контейнеров необходимо указывать ip-адрес сетевого интерфейса хоста, т.к. при привязке контейнера к 0.0.0.0 на машине хоста, контейнеры будут недоступны снаружи.


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


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


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


Для использования данного rootless-хоста в конфигурационном файле для хоста нужно указать <code>type: managed</code>.
Для использования данного rootless-хоста в конфигурационном файле для хоста нужно указать <code>type: managed</code>.
Line 214: Line 212:
|string
|string
|исполняемый файл. Должен быть доступен в $PATH или содержать абсолютный путь  
|исполняемый файл. Должен быть доступен в $PATH или содержать абсолютный путь  
''формат'': имя исполняемого фала, доступного через переменную <code>$PATH</code>


''или'': абсолютный путь до исполняемого файла
формат: имя исполняемого файла, доступного через переменную <code>$PATH</code>
 
или: абсолютный путь до исполняемого файла
|-
|-
|managed/env
|managed/env
Line 226: Line 225:
|[]string
|[]string
|список аргументов запуска rootless-хоста                                     
|список аргументов запуска rootless-хоста                                     
''формат'': <code>"--название-аргумента=значение-аргумента"</code>
формат: <code>"--название-аргумента=значение-аргумента"</code>


''или'': <code>"--название-аргумента", "значение-аргумента"</code>  
или: <code>"--название-аргумента", "значение-аргумента"</code>  


''или'': <code>"--название-флага"</code>
или: <code>"--название-флага"</code>
|-
|-
|managed/loglevel
|managed/loglevel
Line 257: Line 256:
==== Рекомендуемая конфигурация rootless-хоста ====
==== Рекомендуемая конфигурация rootless-хоста ====


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


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


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


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


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


В таком случае подключиться к данному хосту можно как к "внешнему" (<code>type: external</code>) с указанием адреса unix-сокета. Например:
В таком случае подключиться к данному хосту можно как к "внешнему" (<code>type: external</code>), указав адрес unix-сокета. Например:
  docker:
  docker:
   hosts:
   hosts:
Line 297: Line 297:
=== Конфигурация по умолчанию ===
=== Конфигурация по умолчанию ===


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


'''Внимание!''' При наличии раздела <code>xsvacer/docker</code> в конфигурационном файле <code>svacer.cfg</code>, будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы.
{{Note|type=info|text=При наличии раздела <code>xsvacer/docker</code> в конфигурационном файле svacer.cfg будут применены только настройки из этого раздела. Настройки по умолчанию будут полностью проигнорированы}}


=== Изменение конфигурационных параметров с помощью переменных окружения ===
=== Изменение конфигурационных параметров с помощью переменных окружения ===
Line 327: Line 327:
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения <code>XSVACER_DOCKER_HOSTS_{id хоста}[_параметр]={значение параметра}</code>
Значения атрибутов конфигурации могут быть изменены с помощью переменных окружения <code>XSVACER_DOCKER_HOSTS_{id хоста}[_параметр]={значение параметра}</code>


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


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


Список известных проблем и их решение
=== rootless-хост продолжает работать при некорректной остановке Svacer ===
 
=== rootless-хост продолжает работать при некорректной остановке svacer'а ===
 
При некорректном завершении работы svacer'а (например, при получении сигнала <code>SIGKILL</code>), процесс rootless-хоста останется в запущенным в системе.


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


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


При этом, если настройки не менялись, зависимые функциональности смогут получить доступ к "неконтролируемому" rootless-хосту, т.к. адрес unix-сокета хоста известен.
[rootlesskit:parent] error: failed to lock /path/to/svacer-docker-host/state-dir/lock, another RootlessKit is running with the same state directory?


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


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

Latest revision as of 15:47, 19 June 2024

Данная функциональность входит в набор расширений 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.