Portainer Documentation
Official WebsiteKnowledge BasePricingGet 3 Nodes of BE Free
2.21 LTS
2.21 LTS
  • Welcome
  • What's new in version 2.21
  • Release Notes
  • Getting Started
    • Introduction
    • Portainer architecture
    • Lifecycle policy
    • Requirements and prerequisites
    • Install Portainer BE
      • Set up a new Portainer BE Server installation
        • Docker Standalone
          • Install Portainer BE with Docker on Linux
          • Install Portainer BE with Docker on WSL / Docker Desktop
          • Install Portainer BE with Docker on Windows Container Service
        • Docker Swarm
          • Install Portainer BE with Docker Swarm on Linux
          • Install Portainer BE with Docker Swarm on WSL / Docker Desktop
          • Install Portainer BE with Docker Swarm on Windows Container Service
        • Kubernetes
          • Install Portainer BE on your Kubernetes environment
          • Install Portainer BE with Kubernetes on WSL / Docker Desktop
        • Initial setup
    • Install Portainer CE
      • Set up a new Portainer CE Server installation
        • Docker Standalone
          • Install Portainer CE with Docker on Linux
          • Install Portainer CE with Docker on WSL / Docker Desktop
          • Install Portainer CE with Docker on Windows Container Service
        • Docker Swarm
          • Install Portainer CE with Docker Swarm on Linux
          • Install Portainer CE with Docker Swarm on WSL / Docker Desktop
          • Install Portainer CE with Docker Swarm on Windows Container Service
        • Kubernetes
          • Install Portainer CE on your Kubernetes environment
          • Install Portainer CE with Kubernetes on WSL / Docker Desktop
        • Initial setup
    • Add an environment to an existing installation
    • Updating Portainer
      • Updating on Docker Standalone
      • Updating on Docker Swarm
      • Updating on Kubernetes
      • Updating on Nomad
      • Updating the Edge Agent
      • Updating from Portainer 1.x
      • Switching to Portainer Business Edition
        • Upgrade to Business Edition from within Portainer Community Edition
        • Docker Standalone
        • Docker Swarm
        • Kubernetes
        • Upgrading Agent-only deployments
  • Using Portainer
    • Home
      • Snapshot browsing
      • OpenAMT
    • Docker/Swarm
      • Dashboard
      • Templates
        • Application
        • Custom templates
        • Deploy a stack
        • Deploy a container
      • Stacks
        • Add a new stack
        • Inspect or edit a stack
        • Create a template from a deployed stack
        • Webhooks
        • Migrate or duplicate a stack
        • Remove a stack
      • Services
        • Add a new service
        • Configure service options
        • Scale a service
        • View the status of a service task
        • View service logs
        • Roll back a service
        • Webhooks
      • Containers
        • Add a new container
        • View a container's details
        • Inspect a container
        • Edit or duplicate a container
        • Advanced container settings
        • Webhooks
        • Attach a volume to a container
        • View container logs
        • View container statistics
        • Access a container's console
        • Change container ownership
        • Remove a container
      • Images
        • Pull an image
        • Build a new image
        • Import an image
        • Export an image
      • Networks
        • Add a new network
        • Remove a network
      • Volumes
        • Add a new volume
        • Browse a volume
        • Remove a volume
      • Configs
        • Add a new config
        • Remove a config
      • Secrets
        • Add a new secret
        • Remove a secret
      • Events
      • Host
        • Details
        • Setup
        • Registries
      • Swarm
        • Details
        • Cluster visualizer
        • Setup
        • Registries
    • Kubernetes
      • Dashboard
      • kubectl shell
      • Kubeconfig
      • Custom Templates
        • Add a new custom template
        • Edit a custom template
        • Remove a custom template
      • Namespaces
        • Add a new namespace
        • Manage a namespace
        • Manage access to a namespace
        • Remove a namespace
      • Helm
      • Applications
        • Add a new application using a form
        • Add a new application using a manifest
        • Inspect an application
        • Inspect a Helm application
        • Edit an application
        • Webhooks
        • Detach a volume from an application
        • Remove an application
      • Networking
        • Services
        • Ingresses
          • Add an Ingress manually
          • Add an Ingress using a manifest
          • Remove an Ingress
      • ConfigMaps & Secrets
        • Add a ConfigMap
        • Add a Secret
      • Volumes
        • Inspect a volume
        • Remove a volume
      • More Resources
        • Service Accounts
        • Cluster Roles
        • Roles
      • Cluster
        • Details
        • Inspect a node
        • Setup
        • Security constraints
        • Registries
    • Azure ACI
      • Dashboard
      • Container instances
        • Add a new container
        • Remove a container
    • Nomad
    • Edge Compute
      • Edge Groups
      • Edge Stacks
        • Add a new Edge Stack
      • Edge Jobs
      • Edge Configurations
      • Waiting Room
      • Edge Templates
        • Application
        • Custom
    • Account settings
  • Administering Portainer
    • User-related
      • Users
      • Add a new user
      • Turn a user into an administrator
      • Reset a user's password
      • Teams
        • Add a new team
        • Add a user to a team
      • Roles
    • Environment-related
      • Environments
      • Add a new environment
        • Add a local environment
        • Add a Docker Standalone environment
          • Install Portainer Agent on Docker Standalone
          • Connect to the Docker API
          • Connect to the Docker Socket
          • Install Edge Agent Standard on Docker Standalone
          • Install Edge Agent Async on Docker Standalone
        • Add a Docker Swarm environment
          • Install Portainer Agent on Docker Swarm
          • Connect to the Docker API
          • Connect to the Docker Socket
          • Install Edge Agent Standard on Docker Swarm
          • Install Edge Agent Async on Docker Swarm
        • Add a Kubernetes environment
          • Install Portainer Agent on your Kubernetes environment
          • Install Edge Agent Standard on Kubernetes
          • Install Edge Agent Async on Kubernetes
          • Import an existing Kubernetes environment
        • Add an ACI environment
        • Add a Nomad environment
        • Provision KaaS Cluster
          • Civo
          • Akamai Connected Cloud
          • DigitalOcean
          • Google Cloud
          • AWS
          • Azure
        • Create a Kubernetes cluster
          • MicroK8s
            • Offline installation
        • Add an environment via the Portainer API
      • Auto onboarding
      • Groups
      • Tags
      • Manage access to environments
      • Manage access to environment groups
      • Update & Rollback
    • Registries
      • Add a new registry
        • Add a DockerHub account
        • Add an AWS ECR registry
        • Add a Quay.io registry
        • Add a ProGet registry
        • Add an Azure registry
        • Add a Gitlab registry
        • Add a GitHub registry
        • Add a custom registry
      • Browse a registry
      • Manage a registry
    • Licenses
    • Logs
      • Authentication
      • Activity
    • Notifications
    • Settings
      • General
      • Authentication
        • Authenticate via LDAP
        • Authenticate via Active Directory
        • Authenticate via OAuth
      • Shared credentials
        • Add Civo credentials
        • Add Akamai Connected Cloud credentials
        • Add DigitalOcean credentials
        • Add Google Cloud credentials
        • Add AWS credentials
        • Add Azure credentials
        • Add SSH credentials
      • Edge Compute
  • Frequently Asked Questions
    • Portainer Concepts
    • Installing
    • Upgrading
    • Troubleshooting
    • Contributing
  • Advanced Topics
    • CLI configuration options
    • App templates
      • Build and host your own app templates
      • App template JSON format
    • The Portainer Edge Agent
    • Access control
    • Reset the admin user's password
    • Security and compliance
    • Encrypting the Portainer database
    • Using your own SSL certificate with Portainer
    • Using mTLS with Portainer
    • Stream auth and activity logs to an external provider
    • Using Portainer with reverse proxies
      • Deploying Portainer behind Traefik Proxy
      • Deploying Portainer behind nginx reverse proxy
    • How Relative Path Support works in Portainer
    • Helm chart configuration options
    • Docker roles and permissions
    • Kubernetes roles and bindings
    • Deprecated and removed features
  • API
    • Accessing the Portainer API
    • API documentation
    • API usage examples
  • Get More Help
    • Knowledge Base
    • Portainer Academy
    • YouTube
    • GitHub
    • Slack
    • Discord
    • Open a support request
  • Contribute to Portainer
    • Contribute
    • Build instructions
      • Set up a macOS build environment
      • Set up a Linux build environment
Powered by GitBook
On this page
  • The back story
  • Creating an Edge Agent in Portainer
  • How Portainer and the Edge Agent communicate
  • Polling
  • Connection process and checks
  • Opening a tunnel between the agent and Portainer
  • When Portainer forces the Edge Agent to establish a tunnel
  • Terminating the connection
  • Network performance
  • Adjusting the polling frequency to improve performance
  • Ongoing improvements

Was this helpful?

Edit on GitHub
  1. Advanced Topics

The Portainer Edge Agent

PreviousApp template JSON formatNextAccess control

Was this helpful?

The back story

For standard deployments, we used to assume that the Portainer instance and any environments shared the same network and could communicate seamlessly. If remote environments were on a different network (say, across the Internet) we could not manage them.

Then we changed the Edge agent architecture so only the environments need to access Portainer. There is now no need to expose the Portainer agents to the Internet.

Portainer now requires that only the 9443 and 8000 TCP ports are exposed. We used to serve the UI and the Portainer API from port 9000, but we extended the API to allow the remote agents to poll for instructions. Port 8000 is a TLS tunnel server used to create a secure tunnel between the agent and the Portainer instance. More about that soon.

If your Portainer instance is deployed with TLS, the agent will use HTTPS for the connection it makes back to Portainer. However, if your Portainer instance uses a self-signed certificate, the Edge Agent must be deployed with the -e EDGE_INSECURE_POLL=1 flag. If you do not deploy the Edge Agent with this flag, the agent won't be able to communicate with the Portainer instance.

Creating an Edge Agent in Portainer

When you create an Edge Agent, you are first asked for a human-friendly endpoint name. You are then asked to confirm the FQDN:PORT of your Portainer instance. This is what agents will use to connect, so make sure it’s correct and that the DNS resolves.

During the creation process, an Edge ID is dynamically generated. This is a random UUID which is assigned to each environment. You can see it in the command syntax which is provided during the setup process.

The Edge ID and the join token are unique per environment. The join token (EDGE_KEY) is made up of the following base64 encoded data separated by the pipe (|) character:

  • The Portainer instance API URL. This is how the Edge Agent knows how to ‘call home’ to your Portainer instance.

  • The Portainer instance reverse-tunnel server fingerprint (prevents MITM when creating a tunnel).

  • The environment identifier key (endpoint / environment ID).

Use the command syntax to deploy an Edge Agent across your remote node or remote swarm cluster.

How Portainer and the Edge Agent communicate

Polling

Agents poll the Portainer instance every 5 seconds by default (this is defined in Portainer settings).

Connection process and checks

The agent says to Portainer, “Hi, I'm an agent. My join token is abc123. Do you need me right now?”. Portainer checks its database to ensure the Edge UUID and the join token match. If no UUID can be associated with the join token provided, Portainer will associate the UUID provided by the agent to the environment’s join token.

If the UUID/join token do not match, the connection is rejected. If the UUID/join token match, the Portainer instance responds with either: "No, I don’t need you. Please check in again in X seconds." (where X is the agent polling frequency), or "Yes, I do need you. Please connect using these tunnel credentials.”.

Portainer encrypts the tunnel credentials using the Edge UUID as the encryption key (intended as one-time-use credentials).

Opening a tunnel between the agent and Portainer

Once confirmation is received, the Edge Agent decrypts the credentials and opens a tunnel on port 8000 to the Portainer instance. If a remote environment is a swarm cluster, every node will run an instance of the agent (and every instance will poll Portainer). The 'you are required' flag causes the first agent in the cluster to establish the tunnel. Once in place, Portainer can then query the agent where the tunnel is open. If the tunnel closes for any reason, the agent will immediately re-establish it.

When Portainer forces the Edge Agent to establish a tunnel

Sometimes Portainer will ask the agent to establish a tunnel. This happens when an admin selects an Edge environment for interactive management via the Portainer UI or the API. Once selected, the 'you are required' flag triggers the connection process. If default settings are in use, it takes about 10 seconds for the agent to poll and establish a tunnel. That’s about 5 seconds wait time until polling then a few seconds for the tunnel to open. The admin is shown this message while this happens:

Terminating the connection

The agent keeps a record of when Portainer last communicated with it. After 5 minutes of inactivity, it sends a snapshot of the current config to Portainer for its records, closes the tunnel and revokes the credentials. When admins have an active session with an Edge environment, ‘keep alives’ are sent every minute (even if the admin is not performing a task) so they are not kicked out by mistake.

Network performance

Adjusting the polling frequency to improve performance

Thousands of endpoints polling Portainer every 5 seconds is a lot. That’s about 324b/second per agent, not per environment. If you don’t do a lot of environment admin, we suggest you go into Portainer settings and increase the polling frequency. Simply change it back when you need to do some admin so you are not kept waiting.

Ongoing improvements

We load-tested Portainer with 15,000 actively connected environments with a polling frequency of 5 seconds. This generated 7Mbps of network traffic to the Portainer instance, and Portainer needed 4 CPUs to handle the encryption/tunnel load. This Edge Agent release is our first attempt at massive-scale centralized management. Our end goal is to reduce the network overhead associated with polling.

The Portainer instance reverse tunnel server address. This is identical to the API URL (unless or in ) but with the tunnel server port (8000 is the default).

changed during deployment
Edge Compute settings