Swarm Agents Cloud

A modern Jenkins plugin for dynamic agent provisioning on Docker Swarm clusters.

This plugin is a modern replacement for the abandoned docker-swarm-plugin (last updated February 2021, 54+ unresolved issues).

• Modern Stack — Java 21, WebSocket, current Jenkins API
• DevOps-Ready — JCasC, REST API, Prometheus, Pipeline DSL
• Security — TLS, Secrets, Input Validation
• Reliability — Rate Limiting, Retry with Backoff, Health Checks, Orphan Cleanup
• Active Support — Regular updates vs abandoned project

• Dynamic Agent Provisioning — Automatically creates Docker Swarm services on demand
• WebSocket Support — Modern agent connection (no inbound TCP ports required)
• TLS/SSL Authentication — Full Docker TLS certificate support
• Configuration as Code — Complete JCasC compatibility
• Resource Management — CPU/memory limits and reservations per template
• Health Checks — Configurable container health monitoring
• Secrets & Configs — Docker Swarm secrets and configs integration
• Rate Limiting — Built-in provisioning rate limits (thundering herd protection)
• Dashboard — Real-time cluster monitoring at /swarm-dashboard
• REST API — Programmatic management at /swarm-api
• Template Inheritance — Inherit settings from parent templates (inheritFrom)
• Prometheus Metrics — /swarm-api/prometheus endpoint
• Audit Logging — Track all provisioning events
• Pipeline DSL — Native swarmAgent step for Jenkinsfiles
• Retry with Backoff — Automatic exponential backoff on failures
• Orphan Cleanup — Automatic cleanup of stale services

• Jenkins 2.528.3 or newer (see Jenkins Java requirements for Java version)
• Docker Swarm cluster (docker swarm init)

1. Go to Manage Jenkins → Clouds
2. Click New cloud → Docker Swarm Agents Cloud
3. Configure:
   • Docker Host: tcp://your-swarm-manager:2376
   • Credentials: Docker Server Credentials (for TLS)
   • Max Concurrent Agents: Limit total agents

jenkins:
  clouds:
    - swarmAgentsCloud:
        name: "docker-swarm"
        dockerHost: "tcp://swarm-manager:2376"
        credentialsId: "docker-tls-creds"
        maxConcurrentAgents: 10
        jenkinsUrl: "http://jenkins:8080/"
        swarmNetwork: "jenkins-agents"
        templates:
          - name: "maven"
            image: "jenkins/inbound-agent:latest"
            labelString: "maven docker"
            remoteFs: "/home/jenkins/agent"
            numExecutors: 2
            maxInstances: 5
            cpuLimit: "2.0"
            memoryLimit: "4g"
            connectionTimeoutSeconds: 300
            idleTimeoutMinutes: 30

templates:
  - name: "base"
    image: "jenkins/inbound-agent:latest"
    cpuLimit: "2.0"
    memoryLimit: "4g"
    connectionTimeoutSeconds: 300

  - name: "maven"
    inheritFrom: "base"
    labelString: "maven docker"
    environmentVariables:
      - key: "MAVEN_OPTS"
        value: "-Xmx1g"

templates:
  - name: "with-secrets"
    secrets:
      - secretName: "my-secret"
        fileName: "secret.txt"
        targetPath: "/run/secrets"

pipeline {
    agent none
    stages {
        stage('Build') {
            steps {
                swarmAgent(cloud: 'docker-swarm', template: 'maven') {
                    sh 'mvn clean package'
                }
            }
        }
    }
}

Base URL: http://jenkins/swarm-api/

Access at http://jenkins/swarm-dashboard/

• Cluster health overview
• Node status and resources
• Active services list
• Dark theme support

http://jenkins/swarm-api/prometheus

Metrics: swarm_agents_total, swarm_agents_active, swarm_nodes_total, swarm_memory_total_bytes, etc.

Manage Jenkins → System Log → Add logger io.jenkins.plugins.swarmcloud with level FINE

git clone https://github.com/jenkinsci/swarm-agents-cloud-plugin.git
cd swarm-agents-cloud-plugin
mvn clean package -DskipTests
# Result: target/swarm-agents-cloud.hpi

See CONTRIBUTING.md

MIT License — see LICENSE