When a remote environment is not directly accessible from the Portainer Server instance, we recommend deploying the Portainer Edge Agent to the remote environment. This allows you to manage the remote environment from your Portainer Server instance without having to open any ports on the environment. Rather than the traditional approach of the server connecting to Agents, the Edge Agent instead polls the Portainer Server periodically to see if there are any pending jobs to perform, and acts appropriately.
For a technical summary of how the Edge Agent works, refer to our advanced documentation.
The Edge Agent requires two ports be open on the Portainer Server instance: the UI port (usually 9443 or 30779 on Kubernetes with NodePort) and the tunnel port ( 8000 or 30776 when using Kubernetes with NodePort). The tunnel port is used to provide a secure TLS tunnel between the Portainer Edge Agent and the Portainer Server instance. Our installation instructions configure Portainer Server to listen on both ports by default, and you will need to ensure your firewalling provides external access to these ports in order to proceed.
If your Portainer Server 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, then the agent will not be able to communicate with the Portainer Server instance.
In addition, our instructions assume your environment meets our requirements. While Portainer may work with other configurations, it may require configuration changes or have limited functionality.
To add a standard Edge Agent to a Docker Swarm environment, from the menu expand Environment-related, click Environments, then click Add environment.
Select Docker Swarm then click Start Wizard. Then select the Edge Agent Standard option. Enter the environment details using the table below as a guide.
As an optional step you can expand the More settings section and adjust the Poll frequency for the environment - this defines how often this Edge Agent will check the Portainer Server for new jobs. The default is every 5 seconds. You can also categorize the environment by adding it to a group or tagging it for better searchability.
When you're ready, click Create. If you are pre-staging your Edge Agent deployment, you can now retrieve the join token for use in your deployment.
Otherwise, complete the new fields that have appeared using the table below as a guide.
Choose your platform (Linux or Windows), copy the generated command and run the command on your Edge environment to complete the installation.
If you have set a custom AGENT_SECRET on your Portainer Server instance (by specifying an AGENT_SECRET environment variable when starting the Portainer Server container) you must remember to explicitly provide the same secret to your Edge Agent in the same way (as an environment variable) when deploying your Edge Agent by adding it to the stack file:
environment:
- AGENT_SECRET: yoursecret
If Docker on the environment you're deploying the Edge Agent to has the Docker volume path at a non-standard location (instead of /var/lib/docker/volumes) you will need to adjust the volume mount in the deployment command to suit.
For example, if your volume path was /srv/data/docker, you would change the line in the command to:
The dst value of the mount should remain as /var/lib/docker/volumes, as that is what the Edge Agent expects.
If you have another Edge standard environment of the same type to deploy you can click Add another environment to do so. Otherwise if you have any other environments to configure click Next to proceed, or click Close to return to the list of environments.
| Field | Overview |
|---|---|
| Field/Option | Overview |
|---|---|
Name
Enter a name for your environment.
Portainer API server URL
Enter the URL and port of your Portainer Server instance as it will be seen from your Edge environment. If using a FQDN, ensure that DNS is properly configured to provide this.
Portainer tunnel server address
Enter the address and port of your Portainer Server instance's tunnel server as it will be seen from your Edge environment. If using a FQDN, ensure that DNS is properly configured to provide this.
In most cases, this will be the same address as the Portainer API server URL, but without the protocol and on port 8000.
This field is only available in Portainer Business Edition. For Community Edition users, refer to this GitHub issue.
Environment variables
Enter a comma separated list of environment variables that will be sourced from the host where the agent is deployed and provided to the agent.
Allow self-signed certs
Toggle this on to allow self-signed certificates when the agent is connecting to Portainer via HTTPS.
