UnderstandingGracefulDeletion.md

Understanding Graceful Deletion

When a Docker container managed by DockFlare stops or is removed, DockFlare doesn't immediately delete the associated Cloudflare DNS records and tunnel ingress rules. Instead, it uses a configurable grace period.

Purpose of the Grace Period

The grace period is a crucial feature for stability and resilience:

1. Prevent "Flapping": If a container is rapidly restarted (e.g., due to updates or health check failures), the grace period prevents DockFlare from constantly deleting and recreating the Cloudflare rules, which is inefficient and could lead to API rate-limiting.
2. Allow for Debugging: If a container stops unexpectedly, the associated hostname remains active for the duration of the grace period, giving you time to investigate the issue without the service immediately becoming inaccessible.
3. Smooth Updates: During rolling updates where an old container is replaced by a new one, the grace period ensures the public-facing rule persists, helping to minimize downtime.

How it Works

1. Container Stop Event: DockFlare detects that a labeled container has stopped.
2. Mark for Deletion: DockFlare finds the corresponding rule(s) in its internal state, marks their status as "Pending Deletion," and records a "Scheduled Deletion Time" (current time + grace period). This status is visible in the Web UI.
3. Grace Period Countdown: The rule remains active in Cloudflare (DNS, tunnel ingress, and access policy) during the grace period.
4. Rule Reactivation: If a container starts up before the grace period expires and its labels define the exact same rule (same hostname and path), DockFlare detects this, cancels the pending deletion, and marks the rule as "Active" again.
5. Cleanup Check: A background task in DockFlare periodically checks for rules whose grace period has expired.
6. Actual Deletion: Once the grace period for a rule has passed, the cleanup task permanently removes all associated Cloudflare resources:
   • The CNAME DNS record.
   • The ingress rule from the Cloudflare Tunnel.
   • The associated Cloudflare Access Application (if one was managed by DockFlare for that rule).
   • Finally, the rule is removed from the local state.json file.

Configuration

• GRACE_PERIOD_SECONDS: The environment variable that defines the length of the grace period in seconds.
  • Default: 3600 (1 hour)
  • Set to 0 to disable the grace period entirely, causing rules to be deleted almost immediately upon container stop (not recommended for most environments).
• CLEANUP_INTERVAL_SECONDS: The environment variable defining how often DockFlare runs its cleanup task to check for expired grace periods.
  • Default: 300 (5 minutes)

Forcing Deletion

If you need to remove a rule immediately and bypass the grace period, you can use the "Force Delete" button next to the rule in the Web UI. This triggers the full deletion process instantly.