Cache TTL Reduction vs API Request Surge: Which Trade‑off Fits Portainer in Resource‑Limited Setups?

Recommended Trade-off

For a small Docker Swarm, a cache TTL of 30 seconds typically provides the best balance. This interval ensures the UI reflects container state changes reasonably quickly while keeping the volume of /containers/json requests well below the default rate limits of most Docker daemons. Portainer does not currently support event-driven cache invalidation, and caching cannot be disabled for specific connectors; the TTL setting is global.

Likely Behavior and Constraints

In a resource-constrained environment, the primary risk of reducing TTL is increasing the CPU and I/O load on the Docker daemon. Because Portainer polls the API rather than receiving push notifications from Docker, the request volume scales linearly with the number of nodes and the frequency of the TTL refresh.

• Request Volume: In a 10-node swarm with a 30s TTL, Portainer generates approximately 20 metadata requests per minute. Most Docker hosts handle hundreds of requests per minute before hitting performance bottlenecks.
• State Latency: Since there is no automatic invalidation on state change, the UI will always lag by up to the duration of the TTL.
• Global Scope: Because the cache is global, lowering the TTL for one problematic environment increases the load across all connected environments.

Implementation Steps

1. Modify Configuration: Locate your Portainer configuration (typically within the /data volume or portainer.yml) and update the cacheTTL value:

   cacheTTL: 30

2. Apply Changes: Restart the Portainer container to initialize the new TTL:

   docker restart portainer

3. Verify Freshness: Stop a non-critical container and measure the time until the Portainer UI reflects the exited status.

Verifying API Load

To ensure the daemon is not overwhelmed, monitor the Docker socket traffic. If you have a Prometheus exporter installed, track the request rate for the /containers/json endpoint. Alternatively, check the host's system logs for API timeout errors or "too many open files" warnings.

Required Diagnostic Detail

To determine if a 30s TTL is too aggressive for your specific hardware, please provide the total number of containers across all nodes and the available RAM on the manager node.