Add Docker swarm documentation

Signed-off-by: Dan Webb <[email protected]>
sous-chefs · Dec 17, 2024 · d45d850 · d45d850
1 parent 2926f70
commit d45d850
Show file tree

Hide file tree

Showing 6 changed files with 251 additions and 9 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,26 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Add Docker Swarm support
+  New resources:
+  - docker_swarm_init
+  - docker_swarm_join
+  - docker_swarm_service
+  - docker_swarm_token
+
 ## 11.8.4 - *2024-12-11*
 
+- Update resources overview
 - Update documentation for `docker_container` resource
 - Update documentation for `docker_service` resource
 - Update documentation for `docker_exec` resource
-- Update resources overview
 - Update documentation for `docker_installation_package` resource
 - Update documentation for `docker_installation_script` resource
 - Update documentation for `docker_installation_tarball` resource
 - Update documentation for `docker_service_manager_execute` resource
 - Update documentation for `docker_service_manager_systemd` resource
 - Update documentation for `docker_volume_prune` resource
-<<<<<<< HEAD
-
-## 11.8.3 - *2024-12-11*
-
-- Cleanup changelog
-=======
-
->>>>>>> 5326caf (Update readme, and documentation folder)
 
 ## 11.8.2 - *2024-12-11*
 

diff --git a/README.md b/README.md
@@ -88,6 +88,10 @@ Those recipes are found at `test/cookbooks/docker_test`.
 - [docker_tag](documentation/docker_tag.md): image tagging operations
 - [docker_volume](documentation/docker_volume.md): volume operations
 - [docker_volume_prune](documentation/docker_volume_prune.md): remove unused docker volumes
+- [docker_swarm_init](documentation/docker_swarm_init.md): initialize a new Docker swarm cluster
+- [docker_swarm_join](documentation/docker_swarm_join.md): join a node to a Docker swarm cluster
+- [docker_swarm_service](documentation/docker_swarm_service.md): manage Docker swarm services
+- [docker_swarm_token](documentation/docker_swarm_token.md): manage Docker swarm tokens
 
 ## Getting Started
 

diff --git a/documentation/docker_swarm_init.md b/documentation/docker_swarm_init.md
@@ -0,0 +1,59 @@
+# docker_swarm_init
+
+The `docker_swarm_init` resource initializes a new Docker swarm cluster.
+
+## Actions
+
+- `:init` - Initialize a new swarm
+- `:leave` - Leave the swarm (must be run on a manager node)
+
+## Properties
+
+| Property               | Type          | Default | Description                                   |
+|------------------------|---------------|---------|-----------------------------------------------|
+| `advertise_addr`       | String        | nil     | Advertised address for other nodes to connect |
+| `autolock`             | [true, false] | false   | Enable manager auto-locking                   |
+| `cert_expiry`          | String        | nil     | Validity period for node certificates         |
+| `data_path_addr`       | String        | nil     | Address for data path traffic                 |
+| `dispatcher_heartbeat` | String        | nil     | Dispatcher heartbeat period                   |
+| `force_new_cluster`    | [true, false] | false   | Force create a new cluster from current state |
+| `listen_addr`          | String        | nil     | Listen address                                |
+| `max_snapshots`        | Integer       | nil     | Number of snapshots to keep                   |
+| `snapshot_interval`    | Integer       | nil     | Number of log entries between snapshots       |
+| `task_history_limit`   | Integer       | nil     | Task history retention limit                  |
+
+## Examples
+
+### Initialize a basic swarm
+
+```ruby
+docker_swarm_init 'default' do
+  advertise_addr '192.168.1.2'
+  listen_addr '0.0.0.0:2377'
+end
+```
+
+### Initialize a swarm with auto-locking enabled
+
+```ruby
+docker_swarm_init 'secure' do
+  advertise_addr '192.168.1.2'
+  autolock true
+  cert_expiry '48h'
+end
+```
+
+### Leave a swarm
+
+```ruby
+docker_swarm_init 'default' do
+  action :leave
+end
+```
+
+## Notes
+
+- Only initialize a swarm on one node - other nodes should join using `docker_swarm_join`
+- The node that initializes the swarm becomes the first manager
+- Auto-locking requires additional security steps to unlock managers after a restart
+- The worker token is automatically stored in node attributes for use by worker nodes
diff --git a/documentation/docker_swarm_join.md b/documentation/docker_swarm_join.md
@@ -0,0 +1,58 @@
+# docker_swarm_join
+
+The `docker_swarm_join` resource allows a node to join an existing Docker swarm cluster.
+
+## Actions
+
+- `:join` - Join a swarm cluster
+- `:leave` - Leave the swarm cluster (--force is always used)
+
+## Properties
+
+| Property         | Type   | Default  | Description                          |
+|------------------|--------|----------|--------------------------------------|
+| `token`          | String | Required | Swarm join token (worker or manager) |
+| `manager_ip`     | String | Required | IP address of a manager node         |
+| `advertise_addr` | String | nil      | Advertised address for this node     |
+| `listen_addr`    | String | nil      | Listen address for the node          |
+| `data_path_addr` | String | nil      | Address for data path traffic        |
+
+## Examples
+
+### Join a node to the swarm
+
+```ruby
+docker_swarm_join 'worker' do
+  token 'SWMTKN-1-xxxx'
+  manager_ip '192.168.1.2'
+end
+```
+
+### Join with custom network configuration
+
+```ruby
+docker_swarm_join 'worker-custom' do
+  token 'SWMTKN-1-xxxx'
+  manager_ip '192.168.1.2'
+  advertise_addr '192.168.1.3'
+  listen_addr '0.0.0.0:2377'
+end
+```
+
+### Leave the swarm
+
+```ruby
+docker_swarm_join 'worker' do
+  token 'SWMTKN-1-xxxx'
+  manager_ip '192.168.1.2'
+  action :leave
+end
+```
+
+## Notes
+
+- The join token can be obtained from a manager node using `docker_swarm_token`
+- The default port for swarm communication is 2377
+- Use `advertise_addr` when the node has multiple network interfaces
+- The `:leave` action will always use the --force flag
+- The resource is idempotent and will not try to join if the node is already a swarm member
diff --git a/documentation/docker_swarm_service.md b/documentation/docker_swarm_service.md
@@ -0,0 +1,81 @@
+# docker_swarm_service
+
+The `docker_swarm_service` resource manages Docker services in a swarm cluster.
+
+## Actions
+
+- `:create` - Create a new service
+- `:update` - Update an existing service
+- `:delete` - Remove a service
+
+## Properties
+
+| Property          | Type          | Default       | Description                             |
+|-------------------|---------------|---------------|-----------------------------------------|
+| `service_name`    | String        | name_property | Name of the service                     |
+| `image`           | String        | nil           | Docker image to use for the service     |
+| `command`         | String, Array | nil           | Command to run in the container         |
+| `env`             | Array         | nil           | Environment variables                   |
+| `labels`          | Hash          | nil           | Service labels                          |
+| `mounts`          | Array         | nil           | Volume mounts                           |
+| `networks`        | Array         | nil           | Networks to attach the service to       |
+| `ports`           | Array         | nil           | Port mappings                           |
+| `replicas`        | Integer       | nil           | Number of replicas to run               |
+| `secrets`         | Array         | nil           | Docker secrets to expose to the service |
+| `configs`         | Array         | nil           | Docker configs to expose to the service |
+| `constraints`     | Array         | nil           | Placement constraints                   |
+| `preferences`     | Array         | nil           | Placement preferences                   |
+| `endpoint_mode`   | String        | nil           | Endpoint mode ('vip' or 'dnsrr')        |
+| `update_config`   | Hash          | nil           | Service update configuration            |
+| `rollback_config` | Hash          | nil           | Service rollback configuration          |
+| `restart_policy`  | Hash          | nil           | Service restart policy                  |
+
+## Examples
+
+### Create a simple web service
+
+```ruby
+docker_swarm_service 'web' do
+  image 'nginx:latest'
+  ports ['80:80']
+  replicas 2
+end
+```
+
+### Create a service with environment variables and constraints
+
+```ruby
+docker_swarm_service 'api' do
+  image 'api:v1'
+  env ['API_KEY=secret', 'DEBUG=1']
+  constraints ['node.role==worker']
+  replicas 3
+  ports ['8080:8080']
+  restart_policy({ 'condition' => 'on-failure', 'max_attempts' => 3 })
+end
+```
+
+### Update an existing service
+
+```ruby
+docker_swarm_service 'web' do
+  image 'nginx:1.19'
+  replicas 4
+  action :update
+end
+```
+
+### Delete a service
+
+```ruby
+docker_swarm_service 'old-service' do
+  action :delete
+end
+```
+
+## Notes
+
+- The node must be a swarm manager to manage services
+- Service updates are performed in a rolling fashion by default
+- Use `update_config` to fine-tune the update behavior
+- Network attachments must be to overlay networks or networks with swarm scope
diff --git a/documentation/docker_swarm_token.md b/documentation/docker_swarm_token.md
@@ -0,0 +1,41 @@
+# docker_swarm_token
+
+The `docker_swarm_token` resource manages Docker Swarm tokens for worker and manager nodes.
+
+## Actions
+
+- `:read` - Read the current token value
+- `:rotate` - Rotate the token to a new value
+- `:remove` - Remove the token (not typically used)
+
+## Properties
+
+| Property     | Type          | Default       | Description                                                   |
+|--------------|---------------|---------------|---------------------------------------------------------------|
+| `token_type` | String        | name_property | Type of token to manage. Must be either 'worker' or 'manager' |
+| `rotate`     | [true, false] | false         | Whether to rotate the token to a new value                    |
+
+## Examples
+
+### Read a worker token
+
+```ruby
+docker_swarm_token 'worker' do
+  action :read
+end
+```
+
+### Rotate a manager token
+
+```ruby
+docker_swarm_token 'manager' do
+  rotate true
+  action :read
+end
+```
+
+## Notes
+
+- The token values are stored in `node.run_state['docker_swarm']` with keys `worker_token` and `manager_token`
+- Token rotation is a security feature that invalidates old tokens
+- Only swarm managers can read or rotate tokens