Portainer Edge Agent stack deploy idempotency during network partition retries

Direct AnswerPortainer Edge Agent deployments are not idempotent by default. Retries after network partitions re-execute the full stack definition, risking duplicate named volumes, container name conflicts, and port binding collisions.

Confirmed Behavior

The Edge Agent uses exponential backoff (default 5s, configurable via EDGE_AGENT_RETRY_INTERVAL) to reconnect. When the Server sends a stack deployment and the acknowledgment is lost, the Server re-queues the deployment on reconnect. The Agent has no built-in idempotency key or pre-deploy hook mechanism.

Workarounds Without Stack Modification

1. External orchestration layer: Wrap deployments in a script that generates a unique stack name (e.g., stackname-$(uuidgen | cut -c1-8)) and checks for existing resources before applying.
2. Pre-deploy hook via init container: Add an initialization step in the compose file that runs a script to detect and remove stale resources with the same names before the main services start.
3. Post-deploy cleanup job: Use a separate Job or cron task that scans for duplicate resources created within a short time window (e.g., last 10 minutes) and removes them.

Server Retry Configuration

The Server does not currently expose per-error-class retry suppression. All non-200 responses trigger retries. As a workaround, you can:

• Set EDGE_AGENT_RETRY_INTERVAL to a higher value to reduce retry frequency.
• Use a proxy or network policy to fail fast on permanent errors (e.g., invalid image) while allowing transient connectivity issues to retry.

Recommended Pattern for Duplicate Cleanup

Implement an automated pipeline step that:

1. Queries the Agent’s local state or Docker API for resources with the expected names.
2. Filters by creation timestamp within a narrow window (e.g., now - 5m).
3. Removes duplicates while preserving the most recent instance.

Ensure the cleanup script itself is idempotent to avoid accidental deletion of valid resources.

Verification Steps

To confirm behavior in your environment:

• Check Edge Agent logs for repeated Retrying stack deployment entries with identical stack names after a network interruption.
• Compare Docker resource state before and after a simulated partition to verify no duplicate named volumes or containers were created.
• Confirm the Server snapshot interval is shorter than the maximum expected partition duration to avoid applying deployments on stale state.