Install Portainer Agent with Docker Swarm on Linux

Introduction
Portainer uses the Portainer Agent container to communicate with the Portainer Server instance and provide access to the node's resources. This document will outline how to install the Portainer Agent on your node and how to connect to it from your Portainer Server instance. If you do not have a working Portainer Server instance yet, please refer to the Portainer Server installation guide first.
To get started, you will need:
The latest version of Docker installed and working.
Swarm mode enabled and working, including the overlay network for the swarm service communication.
sudo access on the manager node of your swarm cluster.
The manager and worker nodes must be able to communicate with each other over port 9001. In addition, the Portainer Server installation must be able to reach the nodes on port 9001. If this is not possible, we advise looking at the Edge Agent instead.
The installation instructions also make the following assumptions about your environment:
Your environment meets our requirements. While Portainer may work with other configurations, it may require configuration changes or have limited functionality.
You are accessing Docker via Unix sockets. Connecting via TCP is not supported in Docker Swarm.
SELinux is disabled on the machine running Docker. If you require SELinux, you will need to pass the --privileged flag to Docker when deploying Portainer.
Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration.
If your nodes are using DNS records to communicate, that all records are resolvable across the cluster.
You have not set a custom AGENT_SECRET on your Portainer Server instance. If you have, you will need to provide that secret to your agent by adding it to the stack file:
environment:
  - AGENT_SECRET: yoursecret
Deploying the Agent
From the menu select Environments then click Add environment. Ensure Agent is selected in Environment type.
In the Information tab click the Linux button and select the Docker Swarm tab. Copy the command, then run the command on the manager node of your Docker Swarm cluster.
You must run the command on the Docker Swarm cluster before you proceed to entering the environment details.
The deployment command will return something similar to:
Creating network portainer-agent_portainer_agent
Creating service portainer-agent_agent
To validate the Agent is running, you can run the following command:
 docker service ls
the result of which should look something like this:
ID                  NAME                    MODE                REPLICAS            IMAGE                    PORTS
tshb6ee2710s        portainer-agent_agent   global              1/1                 portainer/agent:2.11.1
Finishing the configuration
Once the Agent is running on the Docker Swarm cluster, enter the environment details using the table below as a guide.
Only do this once for your environment, regardless of how many nodes are in the cluster. You do not need to add each node as an individual environment in Portainer. Adding just one node (we recommend the manager node) will allow Portainer to manage the entire cluster.
Field
Overview
Name
Give the environment a descriptive name. This is a required field.
Endpoint URL
Enter the IP or DNS name at which the Portainer Server instance can reach the environment along with the port (9001). This is a required field.
Public IP
URL or IP address where exposed containers will be reachable. This is an optional field and will default to the environment URL. This can be changed at a later date.
In the Metadata section, as an optional step you can categorize the environment by adding it to a group or tagging it for better searchability.
When everything is set, you can click Add environment.
For security, if an agent does not have a custom AGENT_SECRET defined and has been running for longer than 72 hours without being associated with a Portainer Server installation, the agent will stop accepting connections until it is restarted.

Docker Swarm

Install Portainer Agent with Docker Swarm on WSL / Docker Desktop

Last modified 5mo ago

Copy link

Edit on GitHub

Outline

Introduction

Deploying the Agent

Finishing the configuration