Deploy The Portainer Agent

There are multiple ways to deploy the Portainer Agent. Deploying the Agent as a stack is the simplest method, however you can also install the Agent manually if desired. Connecting your Portainer instance to the Agent is required in order to make use of the Agent's features.

Deploy as a Stack

The simplest way to deploy the Agent is to use the Stacks feature of the the Portainer UI.

Within the web editor of Portainer's Stacks feature you can copy in the contents of the below stack file:

version: '3.2'

services:
  agent:
    image: portainer/agent
    environment:
      AGENT_CLUSTER_ADDR: tasks.agent
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
    ports:
      - target: 9001
        published: 9001
        protocol: tcp
        mode: host
    networks:
      - portainer_agent
    deploy:
      mode: global
      placement:
        constraints: [node.platform.os == linux]

networks:
  portainer_agent:
    driver: overlay
    attachable: true

Alternatively, you can download this same stack file to your computer and upload it to Portainer when creating the Agent.

540B

agent-stack.yml

Agent Stack File

The file can be named whatever you wish as long as it has the .yml file extension.

Note: Portainer needs to be connected to the Agent before you can make use of the Agents features.

Deploy Manually

Note: This tutorial requires that you execute all commands on a manager node in your swarm.

Step 1: Create a new overlay network in your swarm cluster for the Agent by entering the following command:

docker network create --driver overlay --attachable portainer_agent_network 

Step 2: Instructions for step 2 are specific to your operating system. Users running Windows Server follow the special instructions for Windows Server

Deploy Steps

Enter the following command in your terminal to deploy the Agent as a global service in your cluster (connected to the overlay network you just created).

docker service create \
    --name portainer_agent \
    --network portainer_agent_network \
    -e AGENT_CLUSTER_ADDR=tasks.portainer_agent \
    --mode global \
    --constraint 'node.platform.os == linux' \
    --publish published=9001,target=9001,mode=host \
    --mount type=bind,src=//var/run/docker.sock,dst=/var/run/docker.sock \
    --mount type=bind,src=//var/lib/docker/volumes,dst=/var/lib/docker/volumes \
    portainer/agent

Special Instructions for Windows Server

Because of a Docker limitation you need to deploy the Agent to all Windows Server nodes by running following command on each of the nodes in your cluster.

docker run -d --name portainer_agent --restart always \
    --network portainer_agent_network -e AGENT_CLUSTER_ADDR=tasks.portainer_agent \
    --mount type=npipe,source=\.\pipe\docker_engine,target=\.\pipe\docker_engine \
    portainer/agent:windows1803-amd64

Note: If you’re using Windows server 1803, you might need to open up DNS ports to support the DNS resolution of tasks.portainer_agent. See: https://success.docker.com/article/swarm-internal-dns-is-inaccessible-on-windows-server-1803

Note: Portainer needs to be connected to the Agent before you can make use of the Agents features.

Connecting Your Portainer Instance to The Agent

You need to add the Agent as an endpoint inside of Portainer before you can use the Agent's features.

Step 1: Navigate to the Endpoints view of the Portainer UI and click the Add Endpoint button.

Step 2: Click on the Agent Tab at the top of the page, fill in a name for your endpoint and the endpoint URL and click the Add Endpoint button.

Note: You will need to replace 10.0.7.10 with the IP of the node you have the Agent running on.

You should now see a green message such as the one below appear in the top right of the screen. This indicates the Agent has been successfully added as an endpoint.

You should also now have your Agent endpoint available to select & manage in the Home view of Portainer such as below.