Zum Inhalt

Portainer Agent role

Deploy Portainer Agent to enable remote Docker host management from a central Portainer instance.

Usage

Configure the agent hostname in your inventory:

1
2
# vars/main.yml
portainer_agent_hostname: portainer-agent

Include the role in your playbook:

1
2
3
4
# playbooks/proxmox/deploy_docker_services.yml
- hosts: docker_services
  roles:
    - role: portainer_agent

The role provides these tags: - portainer-agent-install - Deploy Portainer Agent - portainer-agent-uninstall - Remove Portainer Agent

Docs

Deploy Portainer Agent to your Docker host:

1
ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_services.yml --tags portainer-agent-install

Remove Portainer Agent:

1
ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_services.yml --tags portainer-agent-uninstall

Configuration Details

The role deploys Portainer Agent with: - Custom Image: gitea.rwcloud.ch/official-docker-images/portainer/agent:latest - Port: 9001 (exposed for Portainer server connection) - Docker Access: Full access to Docker daemon and volumes - Network: Internal portainer network - Host Access: Root filesystem mounted for container inspection

Architecture

Portainer Agent acts as a proxy between the Portainer server and the Docker daemon:

1
Portainer Server → (Port 9001) → Portainer Agent → Docker Daemon

Volume Mounts

The agent requires extensive Docker access: - /var/run/docker.sock:/var/run/docker.sock - Docker daemon socket - /var/lib/docker/volumes:/var/lib/docker/volumes - Volume inspection - /:/host - Host root filesystem (read-only access)

Connecting to Portainer

After deployment, add this agent to your Portainer server:

  1. Open Portainer UI
  2. Go to Environments → Add Environment
  3. Select Agent
  4. Enter environment details:
  5. Name: docker_services (or your host name)
  6. Endpoint URL: host-ip:9001 or hostname:9001
  7. Click Connect

Security Considerations

The agent has privileged access: - Docker Socket: Can create/manage any container - Volume Access: Can read all Docker volumes - Host Filesystem: Can inspect host files

Important: Only deploy on trusted networks. Do not expose port 9001 to the internet.

Network Configuration

The agent creates an internal portainer network. Only the agent port (9001) needs to be accessible from the Portainer server.

Use Cases

Deploy Portainer Agent when: - Managing multiple Docker hosts from one Portainer instance - Remote Docker host management required - Centralized container monitoring and deployment - Multi-host Docker Swarm or standalone setups

Difference from Portainer Server

  • Portainer Server: Web UI for management
  • Portainer Agent: Lightweight proxy for remote hosts

Typically: - Deploy Portainer Server on one host (management node) - Deploy Portainer Agent on each Docker host to be managed

Tailscale Integration

The original role description mentions "via Tailscale Funnel". This allows secure access to the agent over Tailscale VPN without exposing port 9001 publicly.

To use with Tailscale: 1. Ensure Tailscale is installed on the host (use tailscale role) 2. Configure Tailscale funnel if needed 3. Connect via Tailscale hostname: hostname.tailXXXXXX.ts.net:9001

Monitoring

Check agent status:

1
2
docker ps | grep portainer-agent
docker logs portainer-agent

Test connectivity from Portainer server:

1
curl http://agent-host:9001

Updates

Update to the latest agent version:

1
ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_services.yml --tags portainer-agent-install

The pull: always directive ensures the latest image is pulled on each deployment.