portainer / agent

Portainer agent Purpose The Portainer Agent is a workaround for a Docker API limitation when using the Docker API to manage a Docker environment. The user interactions with specific resources (containers, networks, volumes and images) are limited to those available on the node targeted by the Docker API request. Docker Swarm mode introduces a concept which is the clustering of Docker nodes. It also adds services, tasks, configs and secrets which are cluster-aware resources. Cluster-aware means that you can query for a list of services or inspect a task inside any node on the cluster, as long as you’re executing the Docker API request on a manager node. Containers, networks, volumes, and images are node-specific resources; they are not cluster-aware. When you, for example, want to list all the volumes available on a node inside your cluster, you will need to send a query to that specific node. The purpose of the agent is to allow previously node-specific resources to be cluster-aware, all while keeping the Docker API request format. As aforementioned, this means that you only need to execute one Docker API request to retrieve all these resources from every node inside the cluster. In all bringing a better Docker user experience when managing Swarm clusters. Security For information about reporting security vulnerabilities, please see our Security Policy. Technical details The Portainer agent is basically a cluster of Docker API proxies. Deployed inside a Swarm cluster on each node, it allows the redirection (proxy) of a Docker API request on any specific node as well as the aggregation of the response of multiple nodes. At startup, the agent will communicate with the Docker node it is deployed on via the Unix socket/Windows named pipe to retrieve information about the node (name, IP address, role in the Swarm cluster). This data will be shared when the agent registers into the agent cluster. Agent cluster This implementation uses *serf* to form a cluster over a network, each agent requires an address where it will advertise its ability to be part of a cluster and a join address where it will be able to reach other agents. The agent retrieves the IP address it can use to create a cluster by inspecting the Docker networks associated with the agent container. If multiple networks are available, it will pick up the first network available and retrieve the IP address inside this network. Note: Be careful when deploying the agent to not deploy it inside the Swarm ingress network (by not using when exposing ports). This could lead to the agent being unable to create a cluster correctly, if picking the IP address inside the ingress network. Proxy The agent works as a proxy to the Docker API on which it is deployed as well as a proxy to the other agents inside the cluster. In order to proxy the request to the other agents inside the cluster, it introduces a header called which can have the name of any node in the cluster as a value. When this header is specified, the Portainer agent receiving the request will extract its value, retrieve the address of the agent located on the node specified using this header value and proxy the request to it. If no header is present, we assume that the agent receiving the request is the target of the request and it will be proxied to the local Docker API. Some requests are specifically marked to be executed against a manager node inside the cluster ( , , , etc... e.g. all the Docker API operations that can only be executed on a Swarm manager node). This means that you can execute these requests against any agent in the cluster and they will be proxied to an agent (and to the associated Docker API) located on a Swarm manager node. Proxy & aggregation By default, the agent will inspect any requests and search for the header. If it is found (the value of the header does not matter), then the agent will proxy that request to an agent located on any manager node. If this header is not found, then an operation will be executed based on the endpoint prefix ( for a cluster operation, for a manager operation, etc...). The header was introduced to work-around the fact that a Portainer instance uses the Docker CLI binary to manage stacks and the binary **MUST** always target a manager node when executing any command. Some requests are specifically marked to be executed against the whole cluster: • • • • The agent handles these requests using the same header mechanism. If no is found, it will automatically execute the request against each node in the cluster in a concurrent way. Behind the scene, it retrieves the IP address of each node, creates a copy of the request, decorates each request with the header and aggregates the response of each request into a single one (reproducing the Docker API response format). Docker API compliance When communicating with a Portainer agent instead of using the Docker API directly, the only difference is the possibility to add the header to each request to be able to execute some actions against a specific node in the cluster. The fact that the agent's final proxy target is always the Docker API means that we keep the Docker original response format. The only difference in the response is that the agent will automatically add the header to each response using the version of the Portainer agent as value. Agent specific API The agent also exposes the following endpoints: • (*GET*): List all the available agents in the cluster • (*GET*): List the files available under a specific path on the filesystem • (*GET*): Retrieve a file available under a specific path on the filesystem • (*DELETE*): Delete an existing file under a specific path on the filesystem • (*PUT*): Rename an existing file under a specific path on the filesystem • (*POST*): Upload a file under a specific path on the filesystem • (*GET*): Get information about the underlying host system • (*GET*): Returns a 204. Public endpoint that does not require any…