Skip to content
A dead simple REST API for Docker Swarm
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.editorconfig
.gitattributes
.gitignore
.goreleaser.yml
.pre-commit-config.yaml
LICENSE
README.md
go.mod
go.sum
main.go
main_test.go

README.md

Docker Swarm REST API

CircleCI GitHub release

A dead simple REST API built to solve provisoner configuration issues when creating a Docker Swarm with Terraform.

See https://github.com/hashicorp/terraform/issues/19509

Installation

Snapcraft

snap install swarm-api

Homebrew on macOS

If you are using Homebrew on macOS, you can install the swarm-api with the following command:

brew install syntaqx/tap/swarm-api

Download the binary

Quickly download install the latest release:

curl -sfL https://install.goreleaser.com/github.com/syntaqx/swarm-api.sh | sh

Or manually download the latest release binary for your system/architecture and install it into your $PATH

Usage

By default the swarm-api server will only respond to requests on localhost. It is designed to be used on private/protected network interfaces so that newly created docker hosts can easily connect to a swarm without the need to persist join tokens while provisioning hosts.

In practice, a DigitalOcean Droplet might start the swarm-api server like:

nohup swarm-api serve --host $(curl -sfL http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address) &

This leverages DigitalOcean's Droplet Metadata API and should work on a Droplet that supports it.

⚠ Important: You should only change the listening host to a private/protected network interface configured for your netwwork. This API is not protected for use on a public network and doing so would be a massive security hole in your swarm. Be careful.

The swarm-api is intended to be a running alongside a docker swarm leader or connection configuration, configured through the environment:

docker swarm init --advertise-addr $(curl -sfL http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address)

Once both the swarm is initialzied and the swarm-api server started, you're then able to join new nodes by simply leveraging curl or equivelant tool, specifying worker or manager as the last parameter in the example below:

docker swarm join --token $(curl -sfL http://$api_ipv4:8080/swarm/token/worker) $leader_ipv4

You are responsible for knowing the values for $api_ipv4 and $leader_ipv4, which are generally available during provisioning.

Security vulnerabilities

If you discover a security vulnerability within the project, please send an email to Chase Pierce at syntaqx@gmail.com. All security vulnerabilities will be promptly addressed.

License

swarm-api is open source software released under the MIT license.

You can’t perform that action at this time.