Tuesday, December 3, 2024

How to Install Portainer Agent to Manage Multiple Docker Hosts

Portainer is an excellent tool for the home lab environment or production environments managing multiple Docker container hosts. We have discussed this before, but Portainer offers a Business Edition license with 3 free nodes for use as well. Using the Portainer agent, we can manage multiple Docker container hosts. Let’s see how this is done.

What is Portainer?

Arguably, it is one of the best Docker environment management utilities. It allows you to easily have a GUI to manage Docker instead of having to manage everything from the command line. It also has a lot of great tools that allows you to visibly see things that need to be addressed, such as old images, etc.

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 management gui for managing docker containers
portainer management gui for managing docker 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.

install the portainer agent installation on a docker host
install the portainer agent installation on a docker host

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.

adding a new environment in portainer using the portainer agent
adding a new environment in portainer using the portainer agent

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
select the environment to connect to in portainer
select the environment to connect to in portainer

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.

select how to connect to the remote docker standalone host
select how to connect to the remote docker standalone host

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

the new docker standalone environment has been added
the new docker standalone environment has been added

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.

the new docker standalone environment is added with the portainer agent

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.

Wrapping up

If you are looking for a container dashboard and management solution to manage your Docker standalone, Swarm hosts, Kubernetes, and other environments, Portainer provides a good solution that can be used for managing these modern environments. The Portainer agent is a great way to extend management beyond the initial Portainer server instance to manage other remote nodes and not have to install Portainer server on each instance.

Let me know in the comments if you are using Portainer for managing your containers. If not, what are you using?

Brandon Lee
Brandon Leehttps://tek2cloud.com
Brandon Lee is the Senior Writer, Engineer and owner at tek2Cloud.com and has over two decades of experience in Information Technology. Brandon holds multiple industry certifications and loves IT automation, modern applications, and cloud technologies along with traditional servers and infrastructure.

Leave a Reply

Read more

Other Posts