# Swarm provider
## About
The Swarm provider allows you to analyze the services of your Swarm cluster to extract images found and check for
updates on the registry.
## Quick start
In this section we quickly go over a basic stack using your local swarm cluster.
Here we use our local Swarm provider with a minimum configuration to analyze labeled containers (watch by default
disabled).
Now let's create a simple stack for Diun:
```yaml
name: diun
services:
diun:
image: crazymax/diun:latest
command: serve
volumes:
- "./data:/data"
- "/var/run/docker.sock:/var/run/docker.sock"
environment:
- "TZ=Europe/Paris"
- "LOG_LEVEL=info"
- "LOG_JSON=false"
- "DIUN_WATCH_WORKERS=20"
- "DIUN_WATCH_SCHEDULE=0 */6 * * *"
- "DIUN_WATCH_JITTER=30s"
- "DIUN_PROVIDERS_SWARM=true"
deploy:
mode: replicated
replicas: 1
placement:
constraints:
- node.role == manager
```
And another one with a simple service:
```yaml
name: diun
services:
nginx:
image: nginx
ports:
- target: 80
published: 80
protocol: udp
deploy:
mode: replicated
replicas: 2
labels:
- "diun.enable=true"
```
As an example we use [nginx](https://hub.docker.com/_/nginx/) Docker image. A
few [labels](#docker-labels) are added to configure the image analysis of this
service for Diun. We can now start these 2 stacks:
```shell
docker stack deploy -c diun.yml diun
docker stack deploy -c nginx.yml nginx
```
Now take a look at the logs:
```
$ docker service logs -f diun_diun
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:19:57 CET INF Starting Diun dev
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:19:57 CET INF Starting Diun...
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:19:57 CET INF Found 1 image(s) to analyze provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:19:59 CET INF New image found id=myswarm image=docker.io/library/nginx:latest provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:01 CET INF New image found id=myswarm image=docker.io/library/nginx:1.9 provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:01 CET INF New image found id=myswarm image=docker.io/library/nginx:1.9.4 provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:01 CET INF New image found id=myswarm image=docker.io/library/nginx:1.9.8 provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:01 CET INF New image found id=myswarm image=docker.io/library/nginx:1.9.7 provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:01 CET INF New image found id=myswarm image=docker.io/library/nginx:1.9.9 provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:01 CET INF New image found id=myswarm image=docker.io/library/nginx:1.9.6 provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:01 CET INF New image found id=myswarm image=docker.io/library/nginx:1.9.5 provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:mainline-alpine provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:alpine-perl provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:stable-perl provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:stable-alpine-perl provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:1 provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:perl provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:mainline-alpine-perl provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:stable provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:mainline-perl provider=swarm
diun_diun.1.i1l4yuiafq6y@docker-desktop | Sat, 14 Dec 2019 16:20:02 CET INF New image found id=myswarm image=docker.io/library/nginx:mainline provider=swarm
...
```
## Configuration
!!! hint
Environment variable `DIUN_PROVIDERS_SWARM=true` can be used to enable this provider with default values.
### `endpoint`
Server address to connect to. Local if empty.
!!! example "File"
```yaml
providers:
swarm:
endpoint: "unix:///var/run/docker.sock"
```
!!! abstract "Environment variables"
* `DIUN_PROVIDERS_SWARM_ENDPOINT`
#### `apiVersion`
Overrides the client version with the specified one.
!!! example "File"
```yaml
providers:
swarm:
apiVersion: "1.39"
```
!!! abstract "Environment variables"
* `DIUN_PROVIDERS_SWARM_APIVERSION`
#### `tlsCertsPath`
Path to load the TLS certificates from.
!!! example "File"
```yaml
providers:
swarm:
tlsCertsPath: "/certs/"
```
!!! abstract "Environment variables"
* `DIUN_PROVIDERS_SWARM_TLSCERTSPATH`
#### `tlsVerify`
Controls whether client verifies the server's certificate chain and hostname (default `true`).
!!! example "File"
```yaml
providers:
swarm:
tlsVerify: true
```
!!! abstract "Environment variables"
* `DIUN_PROVIDERS_SWARM_TLSVERIFY`
#### `watchByDefault`
Enable watch by default. If false, services that don't have `diun.enable=true` label will be ignored (default `false`).
!!! example "File"
```yaml
providers:
swarm:
watchByDefault: false
```
!!! abstract "Environment variables"
* `DIUN_PROVIDERS_SWARM_WATCHBYDEFAULT`
## Docker labels
You can configure more finely the way to analyze the image of your service through Docker labels:
| Name | Default | Description |
|---------------------|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| `diun.enable` | | Set to true to enable image analysis of this service |
| `diun.regopt` | | [Registry options](../config/regopts.md) name to use |
| `diun.watch_repo` | `false` | Watch all tags of this service image ([be careful](../faq.md#docker-hub-rate-limits) with this setting) |
| `diun.notify_on` | `new;update` | Semicolon separated list of status to be notified: `new`, `update`. |
| `diun.sort_tags` | `reverse` | [Sort tags method](../faq.md#tags-sorting-when-using-watch_repo) if `diun.watch_repo` enabled. One of `default`, `reverse`, `semver`, `lexicographical` |
| `diun.max_tags` | `0` | Maximum number of tags to watch if `diun.watch_repo` enabled. `0` means all of them |
| `diun.include_tags` | | Semicolon separated list of regular expressions to include tags. Can be useful if you enable `diun.watch_repo` |
| `diun.exclude_tags` | | Semicolon separated list of regular expressions to exclude tags. Can be useful if you enable `diun.watch_repo` |
| `diun.hub_link` | _automatic_ | Set registry hub link for this image |
| `diun.platform` | _automatic_ | Platform to use (e.g. `linux/amd64`) |
| `diun.metadata.*` | See [below](#default-metadata) | Additional metadata that can be used in [notification template](../faq.md#notification-template) (e.g. `diun.metadata.foo=bar`) |
## Default metadata
| Key | Description |
|-------------------------------|-----------------------|
| `diun.metadata.svc_id` | Service ID |
| `diun.metadata.svc_createdat` | Service creation date |
| `diun.metadata.svc_updatedat` | Service update date |
| `diun.metadata.ctn_name` | Container name |