vagrant-docker-networks-manager

Vagrant plugin to manage Docker networks with labeled ownership, safe lifecycle hooks, JSON output, and conflict-aware validation.

• Creates a Docker network on vagrant up (with labels & marker)
• Cleans it on vagrant destroy only if owned by this machine (safe)
• vagrant network CLI: init | destroy | info | reload | list | prune | rename
• IPv4/CIDR validation, subnet conflict detection, optional macvlan
• i18n (English 🇬🇧 / Français 🇫🇷), emojis, and normalized JSON output

Requirements: Vagrant ≥ 2.2, Ruby ≥ 3.1, Docker (CLI + daemon) running

• Why this plugin?
• Installation
• Quick start
• Vagrantfile configuration
• CLI usage
• JSON output examples
• Ownership & safety
• Subnet validation & conflicts
• Internationalization
• Environment variables
• Permissions & OS notes
• Troubleshooting
• Contributing & Development
• License

🇫🇷 Français : voir README.fr.md

Managing Docker networks across Vagrant projects is tedious:

• naming consistency, subnet overlaps, and safe cleanup are error-prone
• destroying a VM shouldn’t delete someone else’s shared network
• operators need deterministic CLI and machine-readable output

This plugin solves these by labeling networks, keeping a marker per machine, validating CIDR + detecting overlaps, and offering a clean CLI with JSON output.

From RubyGems (once published):

vagrant plugin install vagrant-docker-networks-manager

From source (local path):

git clone https://github.com/julienpoirou/vagrant-docker-networks-manager
cd vagrant-docker-networks-manager
bundle install
rake
vagrant plugin install .    # install from the local gemspec

Check it’s available:

vagrant network version
vagrant network help

Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp/ubuntu-22.04"

  # Docker network plugin config
  config.docker_network.network_name       = "myproj_net"        # ⚠️ personalize to avoid collisions
  config.docker_network.network_subnet     = "172.28.50.0/24"
  config.docker_network.network_gateway    = "172.28.50.1"
  config.docker_network.network_type       = "bridge"            # or "macvlan"
  config.docker_network.network_parent     = nil                 # required if macvlan
  config.docker_network.network_attachable = true
  config.docker_network.enable_ipv6        = false
  config.docker_network.ip_range           = nil                 # optional
  config.docker_network.cleanup_on_destroy = true
  config.docker_network.locale             = "en"                # "en" or "fr"
end

vagrant up

If a network with the same name already exists:

• if it’s owned by this machine (labels match), it’s “adopted”
• otherwise you simply get an info message (no destructive action)

vagrant destroy

• The network is removed only if created/owned by this machine.
• To also remove attached containers during Vagrant destroy:

VDNM_DESTROY_WITH_CONTAINERS=1 vagrant destroy

All options (with defaults):

Validation performed:

• Docker name constraints, aligned IPv4/CIDR, gateway not network/broadcast
• ip_range must be included in network_subnet
• macvlan requires network_parent

vagrant network <command> [args] [options]

Commands:
  init    <name> <subnet>
  destroy <name> [--with-containers] [--yes]
  reload  <name> [--yes]
  info    <name>
  list    [--json]
  prune   [--yes]
  rename  <old> <new> [<subnet>] [--yes]
  version

Global options:
  --json            # machine-readable output
  --yes, -y         # auto-confirm prompts
  --quiet           # reduce output (hide info)
  --no-emoji        # disable emojis
  --lang en|fr      # force language

Examples:

vagrant network init mynet 172.28.100.0/26
vagrant network info mynet
vagrant network list
vagrant network destroy mynet --with-containers --yes
vagrant network reload mynet --yes
vagrant network rename oldnet newnet --yes
vagrant network rename oldnet same-name 10.10.0.0/24 --yes
vagrant network prune --yes

Enable with --json for any command.

init

{"action":"init","status":"success","data":{"name":"mynet","subnet":"172.28.100.0/26"}}

info

{
  "action":"info",
  "status":"success",
  "data":{
    "network":{
      "Name":"mynet",
      "Id":"...docker-id...",
      "Driver":"bridge",
      "Subnets":["172.28.100.0/26"],
      "Containers":[{"Name":"web","IPv4":"172.28.100.2/26"}]
    }
  }
}

prune (nothing to do)

{"action":"prune","status":"success","data":{"pruned":0,"items":[]}}

Errors are normalized:

{"action":"destroy","status":"error","error":"Network not found.","data":{"name":"ghost"}, "code":1}

• Networks are created with labels:
  • com.vagrant.plugin=docker_networks_manager
  • com.vagrant.machine_id=<VAGRANT_MACHINE_ID>
• A marker file is also written in:
  .vagrant/machines/<name>/<provider>/docker-networks/<network>.json

On vagrant destroy, the plugin only removes a network if:

• the marker indicates it was created by this machine, or
• labels match this machine’s id (ownership)

If a network exists but is not owned, the plugin leaves it untouched.

Before creating (or renaming to a new subnet), the plugin:

1. Validates network_subnet is an aligned IPv4/CIDR
   (e.g. 172.28.100.0/24, not 172.28.100.1/24)
2. Scans existing Docker networks and checks for overlaps
   (ignoring the target network when appropriate)

This prevents hard-to-debug IP conflicts.

• Locales: en, fr
• Choose via CLI --lang en|fr, or set locale in your Vagrantfile, or VDNM_LANG=en|fr.

Emojis can be disabled with --no-emoji.

The CLI vagrant network destroy <name> --with-containers achieves the same for the manual command.

This plugin only calls docker CLI commands — no elevated privileges are required by the plugin itself. However, the Docker daemon must be reachable by the current user (e.g. the user must be in the docker group on Linux, or Docker Desktop must be running on macOS/Windows).

• Docker is unavailable: ensure Docker Desktop/daemon is running and the CLI works (docker info).
• Invalid subnet: use aligned IPv4/CIDR (e.g. 10.0.0.0/24).
• Subnet already in use: another network overlaps. Pick a different range.
• Remove failed: some containers or other constraints may block docker network rm. Try --verbose (VDNM_VERBOSE=1) to see Docker’s output.
• macvlan: remember to set network_parent (host interface).

git clone https://github.com/julienpoirou/vagrant-docker-networks-manager
cd vagrant-docker-networks-manager
bundle install
rake          # runs RSpec

• Conventional Commits enforced in PRs.
• CI runs RuboCop, tests, and builds the gem.
• See docs/en/CONTRIBUTING.md and docs/en/DEVELOPMENT.md if present.

MIT © 2025 Julien Poirou

Tip: prefer setting a project-specific network_name (e.g. myapp_net) to avoid collisions if multiple Vagrant projects run on the same host.