Document the experimental garbage collection feature

cmd/fluxd/main.go

@@ -99,7 +99,7 @@ func main() {
 
 		// syncing
 		syncInterval = fs.Duration("sync-interval", 5*time.Minute, "apply config in git to cluster at least this often, even if there are no new commits")
-		syncGC       = fs.Bool("sync-garbage-collection", false, "experimental; delete resources that are no longer in the git repo")
+		syncGC       = fs.Bool("sync-garbage-collection", false, "experimental; delete resources that were created by fluxd, but are no longer in the git repo")
 
 		// registry
 		memcachedHostname = fs.String("memcached-hostname", "memcached", "hostname for memcached service.")

site/daemon.md

@@ -62,8 +62,9 @@ fluxd requires setup and offers customization though a multitude of flags.
 |--git-notes-ref         | `flux`            | ref to use for keeping commit annotations in git notes|
 |--git-poll-interval     | `5m`                 | period at which to fetch any new commits from the git repo |
 |--git-timeout           | `20s`                | duration after which git operations time out |
-|**syncing**             |                             | control over how config is applied to the cluster |
+|**syncing**             |                      | control over how config is applied to the cluster |
 |--sync-interval         | `5m`                 | apply the git config to the cluster at least this often. New commits may provoke more frequent syncs |
+|--sync-garbage-collection | `false`            | experimental: when set, fluxd will delete resources that it created, but are no longer present in git (see [garbage collection](./garbagecollection.md)) |
 |**registry cache**      |                               | (none of these need overriding, usually) |
 |--memcached-hostname    | `memcached` | hostname for memcached service to use for caching image metadata|
 |--memcached-timeout     | `1s`                   | maximum time to wait before giving up on memcached requests|

site/faq.md

@@ -16,6 +16,7 @@ menu_order: 60
   * [Is there any special directory layout I need in my git repo?](#is-there-any-special-directory-layout-i-need-in-my-git-repo)
   * [Why does Flux need a git ssh key with write access?](#why-does-flux-need-a-git-ssh-key-with-write-access)
   * [Does Flux automatically sync changes back to git?](#does-flux-automatically-sync-changes-back-to-git)
+  * [Will Flux delete resources when I remove them from git?](#will-flux-delete-resources-when-i-remove-them-from-git)
   * [How do I give Flux access to an image registry?](#how-do-i-give-flux-access-to-an-image-registry)
   * [How often does Flux check for new images?](#how-often-does-flux-check-for-new-images)
   * [How often does Flux check for new git commits (and can I make it sync faster)?](#how-often-does-flux-check-for-new-git-commits-and-can-i-make-it-sync-faster)
@@ -145,6 +146,18 @@ For more information about Flux commands see [the fluxctl docs](./fluxctl.md).
 
 No. It applies changes to git only when a Flux command or API call makes them.
 
+### Will Flux delete resources when I remove them from git?
+
+Flux has an experimental (for now) garbage collectiion feature,
+enabled by passing the command-line flag `--sync-garbage-collection`
+to fluxd.
+
+The garbage collection is conservative: it is designed to not delete
+resources that were not created by fluxd. This means it will sometimes
+_not_ delete resources that _were_ created by fluxd, when
+reconfigured. Read more about garbage collection
+[here](./garbagecollection.md).
+
 ### How do I give Flux access to an image registry?
 
 Flux transparently looks at the image pull secrets that you attach to

site/garbagecollection.md

@@ -0,0 +1,45 @@
+## Garbage collection
+
+Part of syncing a cluster with a git repository is getting rid of
+resources in the cluster that have been removed in the repository. You
+can tell fluxd to do this "garbage collection" using the command-line
+flag `--sync-garbage-collection`. It's important to know how it
+operates, and appreciate its limitations, before enabling it.
+
+### How garbage collection works
+
+When garbage collection is enabled, syncing is done in two phases:
+
+ 1. Apply all the manifests in the git repo (as delimited by the
+    branch and path arguments), and give each resource a label marking
+    it as having been synced from this source.
+
+ 2. Ask the cluster for all the resources marked as being from this
+    source, and delete those that were not applied in step 1.
+
+In the above, "source" refers to the particular combination of git
+repo URL, branch, and paths that this fluxd has been configured to
+use, which is taken as identifying the resources under _this_ fluxd's
+control.
+
+We need to be careful about identifying these accurately, since
+getting it wrong could mean _not_ deleting resources that should be
+deleted; or (much worse), deleting resources that are under another
+fluxd's control.
+
+The definition of "source" affects how garbage collection behaves when
+you reconfigure fluxd. It is intended to be conservative: it ensures
+that fluxd will not delete resources that it did not create.
+
+### Limitations of this approach
+
+In general, if you change an element of the source (the git repo URL,
+branch, and paths), there is a possiblility that resources no longer
+present in the new source will be missed (i.e., not deleted) by
+garbage collection, and you will need to delete them by hand.
+
+| Config change     | What happens |
+|-------------------|--------------|
+| git URL or branch | If the manifests at the new git repo are the same, they will all be relabelled, and things will proceed as usual. If they are different, the resources from the old repo will be missed by garbage collection and will need to be deleted by hand |
+| path added        | Existing resources will be relabelled, and new resources (from manifests in the new path) will be created. Then things will proceed as usual. |
+| path removed | The resources from manifests in the removed path will be missed by garbage collection, and will need to be deleted by hand. Other resources will be treated as usual. |