From db892c0d9d2fba8227f066baca1eff920271791d Mon Sep 17 00:00:00 2001 From: Diekos <106403467+Diekos@users.noreply.github.com> Date: Mon, 28 Sep 2026 12:21:24 +0200 Subject: docs: Cleaned up container document (#2197) * Cleaned up container document Added more explicit explanation to some items Added note on Global State Policies and container networks about accept-invalid * Update docs/configuration/container/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update docs/configuration/container/index.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update docs/configuration/container/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update docs/configuration/container/index.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Added suggested fixes from coderabbit. * Fixed opmode for Adguard Home * Fix health-check retry command * Fixed the adguard example add container image fence and changed the wording around directories. * Fixed line exceeds 80 char at volume mount Fixed fences * Update docs/configuration/container/index.md No idea how that ended up in the file. Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Fix grammar for Zabbix example * Remove a third-party service example --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: Daniil Baturin --- docs/configuration/container/index.md | 95 ++++++++++++++++++----------------- 1 file changed, 49 insertions(+), 46 deletions(-) diff --git a/docs/configuration/container/index.md b/docs/configuration/container/index.md index e770c27f..86fcd714 100644 --- a/docs/configuration/container/index.md +++ b/docs/configuration/container/index.md @@ -27,31 +27,26 @@ set container name mysql-server image quay.io/mysql:8.0 ::: ``` - ```{cfgcmd} set container name \ entrypoint \ Override the default entrypoint from the image for a container. ``` - ```{cfgcmd} set container name \ command \ Override the default command from the image for a container. ``` - ```{cfgcmd} set container name \ arguments \ Set the command arguments for a container. ``` - ```{cfgcmd} set container name \ host-name \ Set the host name for a container. ``` - ```{cfgcmd} set container name \ allow-host-pid The container and the host share the same process namespace. @@ -61,7 +56,6 @@ container, and processes inside the container are visible on the host. The command translates to "--pid host" when the container is created. ``` - ```{cfgcmd} set container name \ allow-host-networks Allow host networking in a container. The network stack of the container is @@ -74,14 +68,12 @@ The command translates to "--net host" when the container is created. ::: ``` - ```{cfgcmd} set container name \ network \ -Attaches user-defined network to a container. +Attaches a user-defined network to a container. Only one network must be specified and must already exist. ``` - ```{cfgcmd} set container name \ network \ address \ Optionally set a specific static IPv4 or IPv6 address for the container. @@ -93,7 +85,6 @@ engine and cannot be used ::: ``` - ```{cfgcmd} set container name \ name-server \ Optionally set a custom name server. @@ -101,13 +92,11 @@ If a container network is used with DNS enabled, this setting will not have any effect. ``` - ```{cfgcmd} set container name \ description \ Set a container description ``` - ```{cfgcmd} set container name \ environment \ value \ Add custom environment variables. @@ -123,33 +112,36 @@ set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' ::: ``` - ```{cfgcmd} set container name \ port \ source \ - ``` ```{cfgcmd} set container name \ port \ destination \ ``` - ```{cfgcmd} set container name \ port \ protocol \ Publish a port for the container. +- **source**: Port on the host +- **destination**: Port on the container :::{code-block} 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 ::: -``` + :::{note} Port publishing cannot be used with **network**. For this purpose, a workaround using destination NAT and static IP assignment for the container is available. ::: -```{cfgcmd} set container name \ volume \ source \ ``` +```{cfgcmd} set container name \ volume \ source \ +``` ```{cfgcmd} set container name \ volume \ destination \ -Mount a volume into the container +Mount a volume into the container. +- **source**: Path on the host, place it inside `/config` to preserve during +upgrades +- **destination**: Path inside the container :::{code-block} none set container name coredns volume 'corefile' source /config/coredns/Corefile @@ -175,7 +167,6 @@ systems total available memory. ```{cfgcmd} set container name \ uid \ ``` - ```{cfgcmd} set container name \ gid \ Set the User ID or Group ID of the container @@ -184,7 +175,6 @@ Set the User ID or Group ID of the container ```{cfgcmd} 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) @@ -213,16 +203,16 @@ Default is 512 MB. Use 0 MB for unlimited memory. ```{cfgcmd} set container name \ device \ source \ ``` - ```{cfgcmd} set container name \ device \ destination \ Add a host device to the container. +- **source**: Device on the router itself +- **destination**: Device inside the container ``` ```{cfgcmd} 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) @@ -243,7 +233,6 @@ setdomainname) 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.* @@ -262,7 +251,6 @@ Disable a container. ### Container Health checks - By default, no health checks are run, even when defined by the image. ```{cfgcmd} set container name \ health-check @@ -285,13 +273,23 @@ Override the default health-check interval. For example: `60` Override the default health-check timeout. For example: `10` ``` -```{cfgcmd} set container name \ health-check retries \ +```{cfgcmd} set container name \ health-check retry \ Number of health check retries before container is considered unhealthy. For example: `1` ``` ### Container Networks +:::{note} +If you use **Global State Policies** in your +{ref}`quick-start:firewall` with container networks, you need +an exception for ARP traffic on bridge interfaces. +Otherwise, ARP will fail and the container will not be reachable. + +```{cfgcmd} set firewall global-options apply-to-bridged-traffic accept-invalid ethernet-type 'arp' +``` +::: + ```{cfgcmd} set container network \ Creates a named container network @@ -340,7 +338,6 @@ Disable a given container registry ```{cfgcmd} set container registry \ authentication username ``` - ```{cfgcmd} set container registry \ authentication password Some container registries require credentials to be used. @@ -357,15 +354,12 @@ untrusted certificates. ```{cfgcmd} set container registry \ mirror address \ ``` - ```{cfgcmd} set container registry \ mirror host-name \ ``` - ```{cfgcmd} set container registry \ mirror port \ ``` - ```{cfgcmd} set container registry \ mirror path \ - +``` Registry mirror, use ``(host-name|address)[:port][/path]``. If you have mirror http://192.168.1.1:8080 for docker.io, you can use ``docker.io/some/repo`` or run ``podman pull docker.io/some/repo`` @@ -380,7 +374,6 @@ If http://192.168.1.1:8080 is your own registry, you can use ``192.168.1.1:8080/ :::{code-block} none set container registry 192.168.1.1:8080 insecure ::: -``` ### Log Configuration @@ -389,11 +382,8 @@ set container registry 192.168.1.1:8080 insecure Set the default log driver for containers. - **k8s-file**: Log to a plain text file in Kubernetes-style format. -- **journald**: Log to the system journal +- **journald**: Log to the system journal (default) - **none**: Disable logging for the container - -Current default is journald. - ``` ## Operation Commands @@ -402,30 +392,37 @@ Current default is journald. Pull a new image for container ``` + ```{opcmd} show container Show the list of all active containers. ``` + ```{opcmd} show container image Show the local container images. ``` + ```{opcmd} show container log \ Show logs from a given container ``` + ```{opcmd} show container network -Show a list available container networks +Show a list of available container networks. ``` + ```{opcmd} restart container \ Restart a given container ``` + ```{opcmd} update container image \ Update container image ``` + ```{opcmd} delete container image \ [force] Delete a particular container image based on it's image ID. @@ -436,17 +433,19 @@ assigned, this is why there is a `force` option to pass down to the container image to also remove those images. ``` -## Example Configuration +## Example Configurations +% stop_vyoslinter 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. +is adapted to the declarative VyOS CLI syntax for Zabbix. +% start_vyoslinter ```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 network zabbix address 172.20.0.10 set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' set container name mysql-server environment 'MYSQL_USER' value 'zabbix' @@ -454,10 +453,10 @@ 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-java-gateway network zabbix address 172.20.0.11 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 network zabbix address 172.20.0.12 set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' @@ -466,11 +465,12 @@ set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbi 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 nat destination rule 100 destination port 10051 +set nat destination rule 100 protocol tcp +set nat destination rule 100 translation address 172.20.0.12 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 network zabbix address 172.20.0.13 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' @@ -479,6 +479,9 @@ 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 +set nat destination rule 101 destination port 80 +set nat destination rule 101 protocol tcp +set nat destination rule 101 translation address 172.20.0.13 +set nat destination rule 101 translation port 8080 ``` + -- cgit v1.2.3