Help:XSvacer:Docker - Revision history

Akuzmin: change to info/warn boxes

2024-06-19T12:47:10Z

change to info/warn boxes

← Older revision		Revision as of 15:47, 19 June 2024
Line 1:		Line 1:
			{{Note\|text=Данная функциональность входит в набор расширений XSvacer}}

	= Управление docker-контейнерами =		= Управление docker-контейнерами =
	~~Данная функциональность входит в набор расширений XSvacer~~

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

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

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

	== Конфигурация ==		== Конфигурация ==
Line 110:		Line 110:
	Пользователь, под которым запускается Svacer, должен иметь права доступа к указанному unix-сокету docker (https://docs.docker.com/engine/install/linux-postinstall/).		Пользователь, под которым запускается Svacer, должен иметь права доступа к указанному unix-сокету docker (https://docs.docker.com/engine/install/linux-postinstall/).

	~~'''Внимание!'''~~ При отсутствии прав доступа к unix-сокету использование данной функциональности будет приводить к ошибке.		{{Note\|type=reminder\|text=При отсутствии прав доступа к unix-сокету использование данной функциональности будет приводить к ошибке. В таком случае можно воспользоваться rootless-хостом (см. ниже)}}
	В таком случае можно воспользоваться rootless-хостом (см. ниже).

	Если для взаимодействия с хостом docker используется дефолтный unix-сокет <code>unix:///var/run/docker.sock</code>, то в конфигурации поле <code>host</code> можно не указывать:		Если для взаимодействия с хостом docker используется дефолтный unix-сокет <code>unix:///var/run/docker.sock</code>, то в конфигурации поле <code>host</code> можно не указывать:
Line 140:		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 ====
Line 322:		Line 321:
	retries: 10		retries: 10

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

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

Akuzmin: review and some fixes

2024-06-14T11:35:38Z

review and some fixes

Show changes

M.vinogradov at 11:59, 7 June 2024

2024-06-07T11:59:35Z

Show changes

M.vinogradov at 13:24, 6 June 2024

2024-06-06T13:24:53Z

← Older revision		Revision as of 16:24, 6 June 2024
Line 346:		Line 346:
	При остановке svacer не будет останавливать "неконтролируемый" rootless-хост.		При остановке svacer не будет останавливать "неконтролируемый" rootless-хост.

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

M.vinogradov at 07:06, 5 June 2024

2024-06-05T07:06:44Z

← Older revision		Revision as of 10:06, 5 June 2024
Line 169:		Line 169:
	\|clienttls/ca		\|clienttls/ca
	\|url		\|url
	\|Путь к файлу ~~сетрификата~~ удостоверяющего центра		\|Путь к файлу сертификата удостоверяющего центра
	\|-		\|-
	\|clienttls/cert		\|clienttls/cert
Line 177:		Line 177:
	\|clienttls/key		\|clienttls/key
	\|url		\|url
	\|Путь к ~~клиенскому~~ ключу		\|Путь к клиентскому ключу
	\|}		\|}

M.vinogradov at 20:52, 4 June 2024

2024-06-04T20:52:36Z

← Older revision		Revision as of 23:52, 4 June 2024
Line 13:		Line 13:
	Для активации функциональности необходимо указать флаг <code>--xsvacer.features docker</code> при запуске svacer'а.		Для активации функциональности необходимо указать флаг <code>--xsvacer.features docker</code> при запуске svacer'а.

	'''Примечание:''' На базе данной функциональности осуществляется запуск компонентов других расширений 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 136:		Line 136:
	host: "<nowiki>http://docker-host-ip-address:port</nowiki>"		host: "<nowiki>http://docker-host-ip-address:port</nowiki>"

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

	==== Подключение к удалённому хосту по https (tls) ====		==== Подключение к удалённому хосту по https (tls) ====
Line 190:		Line 190:
	Управление (запуск и остановка) rootless-хостом будет осуществлять svacer.		Управление (запуск и остановка) rootless-хостом будет осуществлять svacer.

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

	Для использования данного rootless-хоста в конфигурационном файле для хоста нужно указать <code>type: managed</code>.		Для использования данного rootless-хоста в конфигурационном файле для хоста нужно указать <code>type: managed</code>.
Line 321:		Line 321:
	retries: 10		retries: 10

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

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

M.vinogradov: Created page with "= Управление docker-контейнерами = '''Примечание:''' данная функциональность входит в набор расширений XSvacer. Данная функциональность предназначена для управления docker-контейнерами содержащими компоненты XSvacer. Управление docker-контейнерами осуществляется с помощь..."

2024-06-04T20:38:37Z

Created page with "= Управление docker-контейнерами = '''Примечание:''' данная функциональность входит в набор расширений XSvacer. Данная функциональность предназначена для управления docker-контейнерами содержащими компоненты XSvacer. Управление docker-контейнерами осуществляется с помощь..."

New page

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

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

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

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

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

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

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

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

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

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

xsvacer:
docker:
hosts:
dockerhost1:
type: ...
host: ...
disabled: false
...
dockerhost2:
...

dependentFeature1:
...
docker:
hostid: dockerhost1
...
dependentFeature2:
...
docker:
hostid: dockerhost2
...

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

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

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

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

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

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

Для использования "внешнего" хоста docker'а в конфигурационном файле нужно указать <code>type: external</code>, а также задать адрес хоста, соответствующий типу подключения:
docker:
hosts:
default:
type: external
host: "unix:///path/to/docker.sock"
remote1:
type: external
host: "<nowiki>ssh://docker-user@docker-host</nowiki>"
remote2:
type: external
host: "<nowiki>http://docker-host-ip-address:2375</nowiki>"
remote3:
type: external
host: "<nowiki>https://docker-host-ip-address:2376</nowiki>"
clienttls: ...
Если параметр <code>host</code> не задан, то по умолчанию будет использоваться unix-сокет.

==== Подключение к локальному хосту через unix-сокет ====
При обычном запуске демона <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).

Пользователь, под которым запускается 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> можно не указывать:
docker:
hosts:
default:
type: external

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

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

docker:
hosts:
default:
type: external
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)

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

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

'''Внимание!''' данный тип подключения является *небезопасным*, т.к. при использовании 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 необходимо иметь сертификат удостоверяющего центра, клиентский ключ и сертификат.

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

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

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
|-
|clienttls/
|map
|Настройки TLS
|-
|clienttls/ca
|url
|Путь к файлу сетрификата удостоверяющего центра
|-
|clienttls/cert
|url
|Путь к клиентскому сертификату
|-
|clienttls/key
|url
|Путь к клиенскому ключу
|}

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

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

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

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

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

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

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

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

{| class="wikitable"
|+
!Название
!Тип данных
!Описание
|-
|managed/
|map
|параметры запуска rootless-хоста
|-
|managed/executable
|string
|исполняемый файл. Должен быть доступен в $PATH или содержать абсолютный путь
''формат'': имя исполняемого фала, доступного через переменную <code>$PATH</code>

''или'': абсолютный путь до исполняемого файла
|-
|managed/env
|[]string
|список переменных окружения для процесса rootless-хоста
формат: <code>"НАЗВАНИЕ_ПЕРЕМЕННОЙ=значение переменной"</code>
|-
|managed/args
|[]string
|список аргументов запуска rootless-хоста
''формат'': <code>"--название-аргумента=значение-аргумента"</code>

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

''или'': <code>"--название-флага"</code>
|-
|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
|количество попыток проверки до ошибки доступности
|}

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

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

При запуске <code>dockerd-rootless.sh</code> без параметров папки с артефактами docker'а создаются во вложенных папках внутри <code>/run/user/$UID/</code>.
Для лучшей локализации артефактов 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

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

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

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

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

В таком случае подключиться к данному хосту можно как к "внешнему" (<code>type: external</code>) с указанием адреса unix-сокета. Например:
docker:
hosts:
unmanaged:
type: external
host: "unix:///home/${USER}/.cache/svacer-docker-host/svacer-docker.sock"

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

Данная конфигурация применяется по умолчанию, если в конфигурационном файле svacer.cfg отсутствует раздел <code>xsvacer/docker</code>:
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

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

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

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

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

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

Список известных проблем и их решение

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

При некорректном завершении работы svacer'а (например, при получении сигнала <code>SIGKILL</code>), процесс 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>

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

При остановке svacer не будет останавливать "неконтролируемый" rootless-хост.

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