Using agents, you can manage multiple hosts from a single interface without having to install the server installation on each host you need to manage. It also allows you to manage app stacks using a stack file to easily deploy your applications and software as a bundle instead of piecing together individual containers.

Portainer has come a long way as well and has evolved from simply a “Docker management tool” to a tool that can manage Docker Swarm, Kubernetes, Nomad, KaaS, and even orchestrate deploying your own Kubernetes cluster using Microk8s on your own infrastructure.

What is the Portainer Agent?

The portainer agent or portainer edge agent are lightweight software installations that allow you to connect multiple managed nodes to a Portainer server instance. The Portainer server instance is the instance that runs the full Portainer server installation running as a container.

The Portainer instance will run on your Docker host with Docker installed and has access to the Docker service locally and via the agent to the service running remotely. You can think of the server instance as the manager node for your Portainer environment.

The agent allows you to manage your Docker hosts all from a single pane of glass and eliminates the need to install the Portainer server on each Docker standalone host. This makes managing things much simpler and you don’t have to manage users and such on each Portainer server installation. You have one server and all the agent installations will exist on the one Portainer server installation.

Install the Portainer Agent

Let’s look at how to install the portainer agent on a standalone Docker host as an example. You need to have command line access to your Docker container host for deploying portainer agent installations.

On your Docker container host that will be managed by your Portainer manager node, this is a simple one-liner Docker run command:

To install the agent, you use the following command and add any other environment variables needed to your Docker run command:

docker run -d -p 9001:9001 --name portainer_agent --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/docker/volumes:/var/lib/docker/volumes portainer/agent:latest

As you can see the default port for the agent is port 9001.

Add the remote Portainer agent environment to Portainer manager node

Now that we have the Portainer agent installed, we can add the remote Docker host installation to our Portainer manager node. We can do this by logging into the Portainer manager GUI.

Navigate to Settings > Environments > Add environment.

You will see the following screen where you can select the environment you want to add. Choices include:

• Docker standalone
• Docker Swarm cluster
• Kubernetes
• ACI
• Nomad
• Provision KaaS Cluster
• Create a Kubernetes cluster

Next, we select how we connect to our Docker standalone environment. Choices here include:

• Agent
• Docker API
• Docker socket
• Edge Agent Standard
• Edge Agent Async

Below we are selecting the Agent which means we will be communicating via the Portainer API with the remote agent. Note how we have named the new environment and entered the connection information.

Hit the Connect button and you should have the agent successfully connected to your Portainer server.

As we can see over in the right-hand column, it has added our remote Docker host.

Now, if we go back to our Home menu, we will see both container hosts listed, the local host itself, and then the remote host we just added to our Portainer instance.

Troubleshooting

If you run into issues getting the Portainer agent deployed, check the following:

• The agent container is running on the remote host
• If the agent container is not running, use the docker logs command and check the logs for the Portainer agent container to help diagnose the underlying issue
• If you have a firewall in between your Docker container hosts and filtering/scoping traffic between them, you will need to allow port 9001 by default for agent communication