Vagrant Docker Swarm Environment

Warning: For development only, do not use for production

This repository contains a Vagrantfile and the necessary configuration files for automating the setup of a Docker Swarm cluster using Vagrant’s shell provisioning. You can easily override the default settings for the Vagrant environment and the Swarm cluster to suit your needs. Customize global settings via the .settings.yml file, and specify per-node overrides using the NODES Ruby hash in nodes.rb.

By default, make will create three Debian Stable x86_64 Docker Swarm nodes. Each node will consume:

• 2 threads/cores (depending on architecture)
• 2 GB of RAM
• ~1 GB of storage (base install only)

Warning: Make sure your machine has enough resources or adjust override settings.

Quick Start

Get your Vagrant Docker Swarm cluster up and running with these simple steps:

• Setup the Cluster

  Run the following command to clean any previous setup and start fresh:

  make clean && make
  

• SSH into a Node

  Access the first node (node1) in your cluster:

  vagrant ssh node1
  

• Verify Cluster Setup

  List all the nodes to ensure they've joined the cluster successfully:

  docker node ls
  

Global Overrides

If you wish to override the default settings on a global level, you can do so by creating a .settings.yml file based on the provided example-.settings.yml file:

cp example-.settings.yml .settings.yml

Once you have copied the example-.settings.yml to .settings.yml, you can edit it to override the default settings. Below are the available settings:

Vagrant Settings Overrides

• VAGRANT_BOX
  • Default: debian/bookworm64
  • Tested most around Debian Stable x86_64 (currently Bookworm)
• VAGRANT_CPU
  • Default: 2
  • Two threads or cores per node, depending on CPU architecture
• VAGRANT_MEM
  • Default: 2048
  • Two GB of RAM per node
• SSH_FORWARD
  • Default: false
  • Enable this if you need to forward SSH agents to the Vagrant machine(s)

Docker Swarm Settings Overrides

• SWARM_NODES
  • Default: 3
  • The total number of nodes in your Docker Swarm cluster
• JOIN_TIMEOUT
  • Default: 60
  • Timeout in seconds for nodes to obtain a swarm join token

Per-Node Overrides

The naming convention for nodes follows a specific pattern: nodeX, where X is a number corresponding to the node's position within the cluster. This convention is strictly adhered to due to the iteration logic within the Vagrantfile, which utilizes a loop iterating over an array range defined by the number of swarm nodes (Array(1..SWARM_NODES)). Each iteration of the loop corresponds to a node, and the loop counter is in the node name (nodeX).

The overrides, if specified in nodes.rb, take the highest precedence, followed by the overrides in .settings.yml, and lastly, the defaults hard coded in the Vagrantfile itself. This hierarchy allows for a flexible configuration where global overrides can be specified in .settings.yml, and more granular, per-node overrides can be defined in nodes.rb. If a particular setting is not overridden in either .settings.yml or nodes.rb, the default value from the Vagrantfile is used.

If you wish to override the default settings on a per-node level, you can do so by creating a nodes.rb file based on the provided example-nodes.rb file:

cp example-nodes.rb nodes.rb

Once you have copied the example-nodes.rb to nodes.rb, you can edit it to override the default settings. Below are the available settings available per-node:

• BOX
  • Default: debian/bookworm64 (or as overridden in .settings.yml)
  • Vagrant box or image to be used for the node.
• CPU
  • Default: 2 (or as overridden in .settings.yml)
  • Defines the number of CPU cores or threads (depending on architecture).
• MEM
  • Default: 2048 (2 GB) (or as overridden in .settings.yml)
  • Specifies the amount of memory (in MB) allocated to the node.
• SSH
  • Default: false (or as overridden in .settings.yml)
  • Enable this if you need to forward SSH agents to the Vagrant machine

All settings are optional, and as many or as few options can be overridden on any arbitrary node.