vagrant-docker-networks-manager 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a02b353f50a855257d0e7e7f72279b47666e4f6131c2b621a3d58d3b6a4780ed
+  data.tar.gz: 3a2ac68c851a9b6c54ed3aec26c7394086013ac902dcafa19fcc245d6a5da23d
+SHA512:
+  metadata.gz: 9d61692ed4dcfd31642630109b346c3c13d7d3adc13473a2a777c5add55f5cdb4b56e29992f72a49d1af59e4915c06c039a4cc0d186bcc6a7867c3eb0f1b50d6
+  data.tar.gz: 30c99e6849d84e5ba1d2fe5d378bd195be123e7fad9c55addc3369ddc612d7ff98a73ce7e45a239aebe5f4853576892d330eaacb0082d7cf361edd24b0675f73

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.1.1](https://github.com/julienpoirou/vagrant-docker-networks-manager/compare/v0.1.0...v0.1.1) (2025-08-17)
+
+
+### CI 🧑‍💻
+
+* **release-please:** Add issues:write permission ([1c959e0](https://github.com/julienpoirou/vagrant-docker-networks-manager/commit/1c959e04ac86bc7a81363cf4029e0dc52acfc5f7))
+* **release-please:** Point to dotfiles config ([d123be2](https://github.com/julienpoirou/vagrant-docker-networks-manager/commit/d123be274d8aac8d4f2de2de40df976b58f29a2e))
+* **release-please:** Use generic updater for VERSION file ([#3](https://github.com/julienpoirou/vagrant-docker-networks-manager/issues/3)) ([1cc3003](https://github.com/julienpoirou/vagrant-docker-networks-manager/commit/1cc30033cef9b8be87255c45dd82a1ebe1877e7f))
+
+
+### Maintenance 🧹
+
+* **ci:** Unblock CI => RSpec shim & RuboCop config baseline ([#1](https://github.com/julienpoirou/vagrant-docker-networks-manager/issues/1)) ([2e4a1df](https://github.com/julienpoirou/vagrant-docker-networks-manager/commit/2e4a1df9d0d46063c908765d7fbfd17a55fe3f9a))
+* **init:** Bootstrap plugin, CI, CodeQL, Release, Docs ([2b71a69](https://github.com/julienpoirou/vagrant-docker-networks-manager/commit/2b71a69e2b1eb1dd87cdf75b6e9ed1c350afd366))

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+===========
+
+Copyright (c) 2025 Julien Poirou <julienpoirou@protonmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights  
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+copies of the Software, and to permit persons to whom the Software is  
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in  
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,320 @@
+# vagrant-docker-networks-manager
+
+[![CI](https://github.com/julienpoirou/vagrant-docker-networks-manager/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/julienpoirou/vagrant-docker-networks-manager/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/julienpoirou/vagrant-docker-networks-manager/actions/workflows/codeql.yml/badge.svg)](https://github.com/julienpoirou/vagrant-docker-networks-manager/actions/workflows/codeql.yml)
+[![Release](https://img.shields.io/github/v/release/julienpoirou/vagrant-docker-networks-manager?include_prereleases&sort=semver)](https://github.com/julienpoirou/vagrant-docker-networks-manager/releases)
+[![RubyGems](https://img.shields.io/gem/v/vagrant-docker-networks-manager.svg)](https://rubygems.org/gems/vagrant-docker-networks-manager)
+[![License](https://img.shields.io/github/license/julienpoirou/vagrant-docker-networks-manager.svg)](LICENSE.md)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196.svg)](https://www.conventionalcommits.org)
+[![Renovate](https://img.shields.io/badge/Renovate-enabled-brightgreen.svg)](https://renovatebot.com)
+
+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**
+
+---
+
+## Table of contents
+
+- [Why this plugin?](#why-this-plugin)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Vagrantfile configuration](#vagrantfile-configuration)
+- [CLI usage](#cli-usage)
+- [JSON output examples](#json-output-examples)
+- [Ownership & safety](#ownership--safety)
+- [Subnet validation & conflicts](#subnet-validation--conflicts)
+- [Internationalization](#internationalization)
+- [Environment variables](#environment-variables)
+- [Permissions & OS notes](#permissions--os-notes)
+- [Troubleshooting](#troubleshooting)
+- [Contributing & Development](#contributing--development)
+- [License](#license)
+
+> 🇫🇷 **Français :** voir [README.fr.md](README.fr.md)
+
+---
+
+## Why this plugin?
+
+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.
+
+---
+
+## Installation
+
+From RubyGems (once published):
+
+```bash
+vagrant plugin install vagrant-docker-networks-manager
+```
+
+From source (local path):
+
+```bash
+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:
+
+```bash
+vagrant network version
+vagrant network help
+```
+
+---
+
+## Quick start
+
+### Minimal Vagrantfile
+
+```ruby
+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
+```
+
+### Create the network on `up`
+
+```bash
+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)
+
+### Destroy VM and clean the network
+
+```bash
+vagrant destroy
+```
+
+- The network is removed **only** if created/owned by this machine.
+- To also remove attached containers during Vagrant destroy:
+
+```bash
+VDNM_DESTROY_WITH_CONTAINERS=1 vagrant destroy
+```
+
+---
+
+## Vagrantfile configuration
+
+All options (with defaults):
+
+| Key                         | Type    | Default            | Notes |
+|----------------------------|---------|--------------------|-------|
+| `network_name`             | String  | `"network_lo1"`    | ⚠️ Personalize to avoid collisions across projects. |
+| `network_subnet`           | String  | `"172.28.100.0/26"`| Must be **aligned** IPv4/CIDR (e.g. `x.y.z.0/nn`). |
+| `network_type`             | String  | `"bridge"`         | `"bridge"` or `"macvlan"`. |
+| `network_gateway`          | String  | `"172.28.100.1"`   | Must be a **host** address inside `network_subnet`. |
+| `network_parent`           | String  | `nil`              | **Required** if `network_type == "macvlan"`. |
+| `network_attachable`       | Bool    | `false`            | Adds `--attachable`. |
+| `enable_ipv6`              | Bool    | `false`            | Adds `--ipv6`. |
+| `ip_range`                 | String  | `nil`              | IPv4/CIDR **inside** `network_subnet`. |
+| `cleanup_on_destroy`       | Bool    | `true`             | Remove network on `vagrant destroy` if owned/created. |
+| `locale`                   | String  | `"en"`             | `"en"` or `"fr"`. |
+
+Validation performed:
+- Docker name constraints, aligned IPv4/CIDR, `gateway` not network/broadcast
+- `ip_range` must be included in `network_subnet`
+- `macvlan` requires `network_parent`
+
+---
+
+## CLI usage
+
+```
+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]
+
+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:
+
+```bash
+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
+```
+
+---
+
+## JSON output examples
+
+Enable with `--json` for any command.
+
+**init**
+```json
+{"action":"init","status":"success","data":{"name":"mynet","subnet":"172.28.100.0/26"}}
+```
+
+**info**
+```json
+{
+  "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)**
+```json
+{"action":"prune","status":"success","data":{"pruned":0,"items":[]}}
+```
+
+Errors are normalized:
+```json
+{"action":"destroy","status":"error","error":"Network not found.","data":{"name":"ghost"}, "code":1}
+```
+
+---
+
+## Ownership & safety
+
+- 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.
+
+---
+
+## Subnet validation & conflicts
+
+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.
+
+---
+
+## Internationalization
+
+- 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`.
+
+---
+
+## Environment variables
+
+| Variable                         | Purpose |
+|----------------------------------|---------|
+| `VDNM_LANG`                      | Force locale (`en`/`fr`) in hooks. |
+| `VDNM_VERBOSE` | When `1`, prints the full `docker` command on STDERR and shows the native Docker output. |
+| `VDNM_SKIP_CONFLICTS` | When `1`, the reload ignores subnet conflict detection (dangerous, for experts only). |
+| `VDNM_DESTROY_WITH_CONTAINERS`   | When `1`, on Vagrant destroy the plugin also runs `docker rm -f` for attached containers (in addition to disconnect). |
+
+> The CLI `vagrant network destroy <name> --with-containers` achieves the same for the **manual command**.
+
+---
+
+## Permissions & OS notes
+
+- **Linux / macOS**: modifying `/etc/hosts` requires privileges. The plugin pipes through `sudo tee -a` when appending, and writes the file when removing. You may be prompted for your password.
+- **Windows**: the plugin uses **PowerShell elevation** (`Start-Process -Verb RunAs`) when needed to append or rewrite the hosts file.
+
+> If your shell is already elevated (root/Admin), no prompts appear.
+
+---
+
+## Troubleshooting
+
+- **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).
+
+---
+
+## Contributing & Development
+
+```bash
+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.
+
+---
+
+## License
+
+MIT © 2025 [Julien Poirou](mailto:julienpoirou@protonmail.com)
+
+--- 
+
+> Tip: prefer setting a **project-specific** `network_name` (e.g. `myapp_net`) to avoid collisions if multiple Vagrant projects run on the same host.

data/lib/vagrant-docker-networks-manager/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/vagrant-docker-networks-manager/action.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+require "shellwords"
+require "open3"
+require_relative "helpers"
+require_relative "util"
+require_relative "network_builder"
+require_relative "version"
+
+module VagrantDockerNetworksManager
+  class ActionUp
+    def initialize(app, _env); @app = app; end
+
+    def call(env)
+      UiHelpers.setup_i18n!
+      cfg  = env[:machine].config.docker_network
+      set_locale!(cfg)
+
+      unless Util.docker_available?
+        env[:ui].error("#{UiHelpers.e(:error)} #{I18n.t('errors.docker_unavailable')}")
+        return @app.call(env)
+      end
+
+      name = cfg.network_name
+      mid  = env[:machine].id
+
+      if Util.docker_network_exists?(name)
+        if owned_by_this_machine?(name, mid)
+          write_marker(env, name, cfg)
+          env[:ui].info("#{UiHelpers.e(:success)} #{I18n.t('messages.network_exists_adopted', name: name)}")
+        else
+          env[:ui].info("#{UiHelpers.e(:info)} #{I18n.t('messages.network_exists', name: name)}")
+        end
+      else
+        subnet_label = cfg.network_subnet || "-"
+
+        if cfg.network_subnet && !VagrantDockerNetworksManager::Util.valid_subnet?(cfg.network_subnet)
+          env[:ui].error("#{UiHelpers.e(:error)} #{I18n.t('errors.invalid_subnet')}")
+          return @app.call(env)
+        end
+
+        if cfg.network_subnet &&
+           VagrantDockerNetworksManager::Util.docker_subnet_conflicts?(
+             cfg.network_subnet,
+             ignore_network: name
+           )
+          env[:ui].error("#{UiHelpers.e(:error)} #{I18n.t('errors.subnet_in_use')}")
+          return @app.call(env)
+        end
+
+        env[:ui].info("#{UiHelpers.e(:ongoing)} #{I18n.t('log.create_network', name: name, subnet: subnet_label)}")
+        builder = NetworkBuilder.new(cfg, machine_id: mid)
+        args = builder.build_create_command_args
+        if Util.sh!(*args)
+          write_marker(env, name, cfg)
+          env[:ui].info("#{UiHelpers.e(:success)} #{I18n.t('log.ok')}")
+        else
+          rendered = args.shelljoin
+          env[:ui].error("#{UiHelpers.e(:error)} #{I18n.t('messages.create_failed', cmd: rendered)}")
+        end
+      end
+
+      @app.call(env)
+    end
+
+    private
+
+    def set_locale!(cfg)
+      lang = cfg.locale || ENV["VDNM_LANG"]
+      return unless lang
+      UiHelpers.set_locale!(lang)
+    rescue UiHelpers::UnsupportedLocaleError
+      UiHelpers.set_locale!("en")
+    end
+
+    def write_marker(env, name, cfg)
+      m_id  = env[:machine].id
+      dir   = env[:machine].data_dir.join("docker-networks")
+      FileUtils.mkdir_p(dir)
+      marker = dir.join("#{name}.json")
+      payload = {
+        "name"         => name,
+        "machine_id"   => m_id,
+        "plugin"       => "vagrant-docker-networks-manager",
+        "version"      => VagrantDockerNetworksManager::VERSION,
+        "created_at"   => Time.now.utc.iso8601,
+        "config"       => {
+          "type"        => cfg.network_type,
+          "subnet"      => cfg.network_subnet,
+          "gateway"     => cfg.network_gateway,
+          "ip_range"    => cfg.ip_range,
+          "ipv6"        => !!cfg.enable_ipv6,
+          "attachable"  => !!cfg.network_attachable,
+          "parent"      => cfg.network_parent
+        }
+      }
+      File.write(marker, JSON.pretty_generate(payload))
+    rescue => e
+      env[:ui].warn("marker write failed for '#{name}': #{e.message}")
+    end
+
+    def owned_by_this_machine?(name, machine_id)
+      labels = Util.read_network_labels(name)
+      labels["com.vagrant.plugin"] == "docker_networks_manager" &&
+        labels["com.vagrant.machine_id"] == machine_id
+    end
+  end
+
+  class ActionDestroy
+    def initialize(app, _env); @app = app; end
+
+    def call(env)
+      UiHelpers.setup_i18n!
+      cfg  = env[:machine].config.docker_network
+      set_locale!(cfg)
+
+      unless Util.docker_available?
+        env[:ui].error("#{UiHelpers.e(:error)} #{I18n.t('errors.docker_unavailable')}")
+        return @app.call(env)
+      end
+
+      name = cfg.network_name
+      mid  = env[:machine].id
+
+      unless cfg.cleanup_on_destroy
+        @app.call(env)
+        return
+      end
+
+      if created_by_this_machine?(env, name) || owned_by_this_machine?(name, mid)
+        env[:ui].info("#{UiHelpers.e(:broom)} #{I18n.t('messages.remove_network', name: name)}")
+
+        if Util.docker_network_exists?(name)
+          out, _e, st = Open3.capture3("docker", "network", "inspect", name)
+          if st.success?
+            begin
+              info = JSON.parse(out).first
+              (info["Containers"] || {}).values.each do |c|
+                cn = c["Name"]
+                env[:ui].info("#{UiHelpers.e(:ongoing)} #{I18n.t('log.disconnect_container', name: cn)}")
+                Util.sh!("network", "disconnect", "--force", name, cn)
+                if ENV["VDNM_DESTROY_WITH_CONTAINERS"] == "1"
+                  env[:ui].info("#{UiHelpers.e(:ongoing)} #{I18n.t('log.remove_container', name: cn)}")
+                  Util.sh!("rm", "-f", cn)
+                end
+              end
+            rescue => e
+              env[:ui].warn("failed to parse containers for '#{name}': #{e.message}")
+            end
+          end
+
+          if Util.sh!("network", "rm", name)
+            delete_marker(env, name)
+            env[:ui].info("#{UiHelpers.e(:success)} #{I18n.t('log.ok')}")
+          else
+            env[:ui].warn("#{UiHelpers.e(:warning)} #{I18n.t('errors.remove_failed')}")
+          end
+        else
+          delete_marker(env, name)
+          env[:ui].info("#{UiHelpers.e(:info)} #{I18n.t('messages.nothing_to_do')}")
+        end
+      else
+        env[:ui].info("#{UiHelpers.e(:broom)} #{I18n.t('messages.nothing_to_do')}")
+      end
+
+      @app.call(env)
+    end
+
+    private
+
+    def set_locale!(cfg)
+      lang = cfg.locale || ENV["VDNM_LANG"]
+      return unless lang
+      UiHelpers.set_locale!(lang)
+    rescue UiHelpers::UnsupportedLocaleError
+      UiHelpers.set_locale!("en")
+    end
+
+    def marker_path(env, name)
+      env[:machine].data_dir.join("docker-networks", "#{name}.json")
+    end
+
+    def created_by_this_machine?(env, name)
+      marker = marker_path(env, name)
+      return false unless File.exist?(marker)
+      j = JSON.parse(File.read(marker)) rescue {}
+      j["name"] == name && j["machine_id"] == env[:machine].id
+    end
+
+    def owned_by_this_machine?(name, machine_id)
+      labels = Util.read_network_labels(name)
+      labels["com.vagrant.plugin"] == "docker_networks_manager" &&
+        labels["com.vagrant.machine_id"] == machine_id
+    end
+
+    def delete_marker(env, name)
+      m = marker_path(env, name)
+      File.delete(m) if File.exist?(m)
+    end
+  end
+end