x-info:
  github: https://github.com/portainer/agent
  docs: https://docs.portainer.io/admin/environments/add/swarm/agent
  homelab_status: stable
  last_updated: 2026-03-13

# portainer-agent Swarm stack
# Managed by Ansible — manual edits will be overwritten on next deploy.
# Deploy via:
#   ansible-playbook -i inventory/hosts.ini playbooks/docker/deploy_swarm_stack.yml \
#     -e "stack_name=portainer-agent" \
#     -e "stack_compose_src=/home/chester/homelab/ansible/templates/stacks/portainer-agent.stack.yml"
#
# WHAT THIS DOES:
#   Deploys the Portainer Agent as a global Swarm service — one instance on every
#   node in the cluster. Portainer on Watchtower connects to any manager IP on
#   port 9001 (AGENT_PORT) to discover and manage the full Swarm.
#
# HOW TO ADD TO PORTAINER UI:
#   Environments → Add Environment → Docker Swarm → Agent
#   Name:    homelab-swarm
#   Agent:   10.0.0.211:9001   (any Swarm manager IP)

version: "3.9"

services:
  portainer-agent:
    image: portainer/agent:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/lib/docker/volumes:/var/lib/docker/volumes
    environment:
      - AGENT_CLUSTER_ADDR=tasks.portainer-agent
      # WHY tasks.portainer-agent: Swarm DNS resolves the service task IPs,
      # allowing agents on each node to discover each other for cluster mode.
    networks:
      - portainer-agent-net
    ports:
      - target: 9001
        published: 9001
        protocol: tcp
        mode: host
        # WHY mode: host (not ingress): Portainer connects to a *specific* agent
        # instance on each node to gather that node's local container data.
        # Ingress mode would load-balance across all nodes, breaking per-node views.
    deploy:
      mode: global
      # WHY global: one agent per node. Portainer needs an agent on every node
      # to show per-node container stats, logs, and volume state.
      placement:
        constraints:
          - node.platform.os == linux
      resources:
        limits:
          memory: 128M
          cpus: "0.1"
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 30s
      update_config:
        parallelism: 1
        order: start-first
        failure_action: rollback
        delay: 10s
        monitor: 30s
      rollback_config:
        parallelism: 1
        order: stop-first

networks:
  portainer-agent-net:
    driver: overlay
    attachable: true
    # WHY attachable overlay: agents communicate with each other over this
    # dedicated network for cluster-aware discovery (AGENT_CLUSTER_ADDR).
    # Separate from proxy-net to isolate management traffic from app traffic.