From 22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 14:41:08 +0300 Subject: Add incremental RST-to-MyST swap mechanism (sagitta) (#1868) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(swap-sagitta): add incremental RST-to-MyST swap mechanism Backport of the swap mechanism from feat/incremental-myst-swap onto the sagitta release branch. Built directly on top of origin/sagitta, so the underlying RST tree is sagitta's (not current's). Mechanism: - scripts/import_myst.py — import md from myst/* with md- prefix - scripts/swap_sources.py — rename md-{name}.md → {name}.md before Sphinx builds, restore after; writes _build/_swap_state.json and _build/_swap_exclude.txt - docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build → trap restore; explicit `swap` and `restore` targets too - docs/conf.py — MyST extensions enabled; swap exclude_patterns loader; _prefer_webp builder hook so html prefers webp over png Content: - 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md alongside each {name}.rst counterpart) - 1 plain MyST-only page from myst/sagitta where no .rst exists (already at canonical name on sagitta: docs/copyright.md) - 240 .webp images from myst/sagitta (added alongside the existing PNG/JPG so RST builds keep their assets) - docs/_swap.txt populated with all 202 stems → MyST is served by default, revert a page by removing its stem from _swap.txt 🤖 Generated by [robots](https://vyos.io) * feat(conf): copy .md sources into HTML output for plain-text serving Adds a build-finished hook that mirrors every .md file from the Sphinx source tree into the HTML output directory verbatim, making unrendered MyST sources accessible alongside HTML renders at the same URL path. 🤖 Generated by [robots](https://vyos.io) * docs: address review feedback (backport from PR #1857) Fix conversion artifacts, typos, and technical inaccuracies applicable to the sagitta branch: curly quotes, typos (deamonless, cammans, amdifferent, trough), incorrect firewall command paths, missing closing brace in zone-policy, peer name inconsistencies, hardcoded passwords replaced with vault references, and md-*.md exclusion in conf.py. 🤖 Generated by [robots](https://vyos.io) * docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857 Parity backport from PR #1857 (current) — three pieces were missing on sagitta. - .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run scripts/swap_sources.py --swap before the Sphinx build and --restore after. Without this, the swap mechanism ships but never runs on RTD builds for this branch — the swap is a silent no-op. - docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse() when self.state._renderer is not present. Required for cfgcmd / opcmd / cmdincludemd directives to render correctly when included from MyST pages (the swap mechanism's whole point). Sagitta-only delta on _ext/vyos.py (the path = str(path) line on 224) is intentionally untouched. - tests/test_import_myst.py, tests/test_swap_sources.py: tests for the swap scripts. The scripts on this branch are byte-identical to current's, so the same tests apply. Travels with the branch so CI catches per-branch regressions if the scripts ever drift. 🤖 Generated by [robots](https://vyos.io) * fix(conf): skip md-*.md staging files in _copy_md_sources Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com> --- docs/configuration/container/md-index.md | 512 +++++++++++++++++++++++++++++++ 1 file changed, 512 insertions(+) create mode 100644 docs/configuration/container/md-index.md (limited to 'docs/configuration/container') diff --git a/docs/configuration/container/md-index.md b/docs/configuration/container/md-index.md new file mode 100644 index 00000000..1cd322f9 --- /dev/null +++ b/docs/configuration/container/md-index.md @@ -0,0 +1,512 @@ +lastproofread +2022-06-10 + +# Container + +The VyOS container implementation is based on Podman\ as +a daemonless container engine. + +## Configuration + +
+ +set container name \ image + +Sets the image name in the hub registry + +``` none +set container name mysql-server image mysql:8.0 +``` + +If a registry is not specified, Docker.io will be used as the container +registry unless an alternative registry is specified using +**set container registry \** or the registry is included +in the image name + +``` none +set container name mysql-server image quay.io/mysql:8.0 +``` + +
+ +
+ +set container name \ entrypoint \ + +Override the default entrypoint from the image for a container. + +
+ +
+ +set container name \ command \ + +Override the default command from the image for a container. + +
+ +
+ +set container name \ arguments \ + +Set the command arguments for a container. + +
+ +
+ +set container name \ host-name \ + +Set the host name for a container. + +
+ +
+ +set container name \ allow-host-pid + +The container and the host share the same process namespace. +This means that processes running on the host are visible inside the +container, and processes inside the container are visible on the host. + +The command translates to "--pid host" when the container is created. + +
+ +
+ +set container name \ allow-host-networks + +Allow host networking in a container. The network stack of the container is +not isolated from the host and will use the host IP. + +The command translates to "--net host" when the container is created. + +
+ +
+ +Note + +
+ +**allow-host-networks** cannot be used with **network** + +
+ +
+ +
+ +set container name \ network \ + +Attaches user-defined network to a container. +Only one network must be specified and must already exist. + +
+ +
+ +set container name \ network \ address \ + +Optionally set a specific static IPv4 or IPv6 address for the container. +This address must be within the named network prefix. + +
+ +
+ +Note + +
+ +The first IP in the container network is reserved by the +engine and cannot be used + +
+ +
+ +
+ +set container name \ description \ + +Set a container description + +
+ +
+ +set container name \ environment \ value \ + +Add custom environment variables. +Multiple environment variables are allowed. +The following commands translate to "-e key=value" when the container +is created. + +``` none +set container name mysql-server environment MYSQL_DATABASE value 'zabbix' +set container name mysql-server environment MYSQL_USER value 'zabbix' +set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' +set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' +``` + +
+ +
+ +set container name \ port \ source \ + +
+ +
+ +set container name \ port \ destination \ + +
+ +
+ +set container name \ port \ protocol \ + +Publish a port for the container. + +``` none +set container name zabbix-web-nginx-mysql port http source 80 +set container name zabbix-web-nginx-mysql port http destination 8080 +set container name zabbix-web-nginx-mysql port http protocol tcp +``` + +
+ +
+ +set container name \ volume \ source \ + +
+ +
+ +set container name \ volume \ destination \ + +Mount a volume into the container + +``` none +set container name coredns volume 'corefile' source /config/coredns/Corefile +set container name coredns volume 'corefile' destination /etc/Corefile +``` + +
+ +
+ +set container name \ volume \ mode \ + +Volume is either mounted as rw (read-write - default) or ro (read-only) + +
+ +
+ +set container name \ uid \ + +
+ +
+ +set container name \ gid \ + +Set the User ID or Group ID of the container + +
+ +
+ +set container name \ restart \[no | on-failure | always\] + +Set the restart behavior of the container. + +- **no**: Do not restart containers on exit +- **on-failure**: Restart containers when they exit with a non-zero + exit code, retrying indefinitely (default) +- **always**: Restart containers when they exit, regardless of status, + retrying indefinitely + +
+ +
+ +set container name \ cpu-quota \ + +This specifies the number of CPU resources the container can use. + +Default is 0 for unlimited. +For example, 1.25 limits the container to use up to 1.25 cores +worth of CPU time. +This can be a decimal number with up to three decimal places. + +The command translates to "--cpus=\" when the container is created. + +
+ +
+ +set container name \ memory \ + +Constrain the memory available to the container. + +Default is 512 MB. Use 0 MB for unlimited memory. + +
+ +
+ +set container name \ device \ source \ + +
+ +
+ +set container name \ device \ destination \ + +Add a host device to the container. + +
+ +
+ +set container name \ capability \ + +Set container capabilities or permissions. + +- **net-admin**: Network operations (interface, firewall, routing tables) +- **net-bind-service**: Bind a socket to privileged ports + (port numbers less than 1024) +- **net-raw**: Permission to create raw network sockets +- **setpcap**: Capability sets (from bounded or inherited set) +- **sys-admin**: Administration operations (quotactl, mount, sethostname, + setdomainame) +- **sys-time**: Permission to set system clock + +
+ +
+ +set container name \ sysctl parameter \ value \ + +Set container sysctl values. + +The subset of possible parameters are: + +- Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, + kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced +- Parameters beginning with fs.mqueue.\* +- Parameters beginning with net.\* (only if user-defined network is used) + +
+ +
+ +set container name \ label \ value \ + +Add metadata label for this container. + +
+ +
+ +set container name \ disable + +Disable a container. + +
+ +### Container Networks + +
+ +set container network \ + +Creates a named container network + +
+ +
+ +set container network \ description + +A brief description what this network is all about. + +
+ +
+ +set container network \ prefix \ + +Define IPv4 and/or IPv6 prefix for a given network name. +Both IPv4 and IPv6 can be used in parallel. + +
+ +
+ +set container network \ vrf \ + +Bind container network to a given VRF instance. + +
+ +### Container Registry + +
+ +set container registry \ + +Adds registry to list of unqualified-search-registries. By default, for any +image that does not include the registry in the image name, VyOS will use +docker.io and quay.io as the container registry. + +
+ +
+ +set container registry \ disable + +Disable a given container registry + +
+ +
+ +set container registry \ authentication username + +
+ +
+ +set container registry \ authentication password + +Some container registries require credentials to be used. + +Credentials can be defined here and will only be used when adding a +container image to the system. + +
+ +## Operation Commands + +
+ +add container image \ + +Pull a new image for container + +
+ +
+ +show container + +Show the list of all active containers. + +
+ +
+ +show container image + +Show the local container images. + +
+ +
+ +show container log \ + +Show logs from a given container + +
+ +
+ +show container network + +Show a list available container networks + +
+ +
+ +restart container \ + +Restart a given container + +
+ +
+ +update container image \ + +Update container image + +
+ +
+ +delete container image \ \[force\] + +Delete a particular container image based on it's image ID. +You can also delete all container images at once. + +You can not delete a container image if it has more then one tag +assigned, this is why there is a force option to pass down to +the container image to also remove those images. + +
+ +## Example Configuration + +> For the sake of demonstration, [example \#1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers) +> to the declarative VyOS CLI syntax. +> +> ``` none +> set container network zabbix prefix 172.20.0.0/16 +> set container network zabbix description 'Network for Zabbix component containers' +> +> set container name mysql-server image mysql:8.0 +> set container name mysql-server network zabbix +> +> set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' +> set container name mysql-server environment 'MYSQL_USER' value 'zabbix' +> set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> +> set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest +> set container name zabbix-java-gateway network zabbix +> +> set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest +> set container name zabbix-server-mysql network zabbix +> +> set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +> set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' +> set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' +> set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' +> +> set container name zabbix-server-mysql port zabbix source 10051 +> set container name zabbix-server-mysql port zabbix destination 10051 +> +> set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest +> set container name zabbix-web-nginx-mysql network zabbix +> +> set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' +> set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' +> set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +> set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +> +> set container name zabbix-web-nginx-mysql port http source 80 +> set container name zabbix-web-nginx-mysql port http destination 8080 +> ``` -- cgit v1.2.3