Network utils 🕸️

Reusable task files for creating Docker networks in a uniform way. Both helpers derive the docker-side network name from role_id | entity_name and the subnet from meta/server.yml.networks.local.subnet, so the name and the subnet pinning live in exactly one place.

Ad-hoc community.docker.docker_network calls or docker network create / container network create shell-outs in role tasks are forbidden by test_network_create_via_util.py.

When to use which 🧭

create.yml: network only, no compose-up

Use when the role still has work to do between the network creation and the compose-up. Examples: copy entrypoint.sh / healthcheck.sh into the instance directory before the container starts, render additional configs, pre-attach other resources. Also the right choice when pre-creating several foreign networks in a loop (e.g. prometheus’s native_metrics_apps pre-create), where firing the compose handler per iteration would be wrong.

Required var:

• network_role_id: the role whose network to create. Name and subnet are derived from it.

- include_tasks: "{{ [playbook_dir, 'roles/sys-svc-compose/tasks/utils/network/create.yml'] | path_join }}"
  vars:
    network_role_id: "{{ application_id }}"

routine.yml: wrapper with immediate compose-up

Use when the role is a self-contained single-container service whose only pre-condition for compose-up is its own network (e.g. svc-db-mariadb, svc-db-postgres, svc-ai-ollama). The wrapper loads the docker-python deps, calls create.yml for the role’s own network (via application_id), and then re-includes sys-svc-compose with compose_handlers_flush: true so the compose-up fires right after.

- include_tasks: "{{ [playbook_dir, 'roles/sys-svc-compose/tasks/utils/network/routine.yml'] | path_join }}"
  vars:
    compose_handlers_flush: true

Decision rule 📌

Pick routine.yml when “create network → compose-up immediately” is the entire pre-condition chain. Pick create.yml in every other case.