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 serves several important functions:

1. Prevent Flapping: If a container is rapidly restarted (e.g., due to errors, updates, or orchestration adjustments), the grace period prevents DockFlare from constantly deleting and recreating the Cloudflare rules, which can be inefficient and potentially hit API rate limits.
2. Allow for Debugging: If a container stops unexpectedly, the associated hostname remains active for the duration of the grace period, allowing time to investigate the issue without the service immediately becoming inaccessible.
3. Smooth Updates: During rolling updates or blue-green deployments managed by orchestration tools, the old container's rule can persist briefly while the new one comes online, potentially minimizing downtime (though precise zero-downtime depends on your deployment strategy).

How it Works

1. Container Stop Event: DockFlare detects that a labeled container has stopped (e.g., docker stop my-container, or the container exits).
2. Mark for Deletion: DockFlare finds the corresponding rule(s) in its internal state. It marks these rules as "Pending Deletion" and records the current time plus the configured grace period duration as the "Scheduled Deletion Time". This status is visible in the Web UI.
3. Grace Period Countdown: The rule remains active in Cloudflare (DNS and tunnel ingress) during the grace period.
4. Container Restart: If the same container (identified by its ID or potentially by labels/name depending on DockFlare's logic) restarts before the grace period expires, DockFlare typically detects this and cancels the pending deletion, marking the rule as "Active" again.
5. Cleanup Check: DockFlare periodically runs a cleanup task (controlled by CLEANUP_INTERVAL_SECONDS). This task checks for any rules marked as "Pending Deletion" whose "Scheduled Deletion Time" has passed.
6. Actual Deletion: If the grace period has expired for a rule, the cleanup task instructs DockFlare to:
   • Remove the corresponding CNAME DNS record via the Cloudflare API.
   • Remove the ingress rule from the Cloudflare Tunnel configuration via the Cloudflare API.
   • Remove the rule entry from its internal state.json file.

Configuration

• GRACE_PERIOD_SECONDS: Environment variable defining the length of the grace period in seconds.
  • Default: 28800 (8 hours)
  • Set to 0 to disable the grace period (rules deleted almost immediately upon container stop - not generally recommended).
• CLEANUP_INTERVAL_SECONDS: Environment variable defining how often DockFlare checks for expired grace periods.
  • Default: 300 (5 minutes)

Forcing Deletion

If you need to remove a rule immediately, bypassing the grace period (e.g., you've decommissioned a service and want the hostname freed up), you can use the "Force Delete" button next to the rule in the Web UI. This triggers the deletion process immediately.