portainer

The portainer role runs either the Portainer server or an agent, chosen by portainer_mode. The compose project lives in portainer_dir (/opt/portainer).

What it does

• Server mode (default): runs the Portainer server. With portainer_host set it adds Traefik labels so the UI is reachable on that host name through the shared Traefik network. With portainer_bind set it also publishes the UI port 9443 on those addresses.
• Agent mode: runs the agent and publishes port 9001 on the addresses in portainer_agent_bind. A server connects to it.
• Writes the shared secret (AGENT_SECRET) to a file with mode 0600 and starts the project.

Key variables

Variable	Default	Meaning
portainer_mode	server	server or agent.
portainer_version	pinned release	Version of both images. Server and agents must match.
portainer_agent_secret	empty	Shared secret of the server and every agent. Keep it in a vault.
portainer_host	empty	Server only. Host name Traefik routes to the UI. Empty adds no route.
portainer_traefik_network	proxy	Server only. Network Traefik routes on.
portainer_traefik_entrypoint	empty	Server only. Entrypoint of the route; empty uses Traefik’s default.
portainer_bind	[]	Server only. Addresses that publish the UI port 9443.
portainer_agent_bind	[]	Agent only. Addresses that publish the agent port 9001. Required.

All variables: portainer in the reference.

Example

A server behind Traefik, and an agent on another host:

- hosts: control
  become: true
  roles:
    - noixdev.infra.docker
    - noixdev.infra.traefik
    - role: noixdev.infra.portainer
      vars:
        portainer_host: portainer.example.com
        portainer_agent_secret: "{{ vault_portainer_agent_secret }}"

- hosts: workers
  become: true
  roles:
    - noixdev.infra.docker
    - role: noixdev.infra.portainer
      vars:
        portainer_mode: agent
        portainer_agent_bind: [198.51.100.20]
        portainer_agent_secret: "{{ vault_portainer_agent_secret }}"

Gotchas

• An agent needs both portainer_agent_bind and portainer_agent_secret. The role stops without them. There is no default bind address; use a private address.
• Set the secret on the server too. Without it an agent accepts the first server that connects to it.
• Keep server and agents on the same portainer_version.
• Do not publish the UI port on a public address unless you mean to. Prefer portainer_host behind Traefik, or bind portainer_bind to a private network address.