Update the docs with a section regarding the cache usage

Signed-off-by: Soule BA <soule@weave.works>

Author: souleb

docs/spec/v1beta2/helmcharts.md

@@ -390,6 +390,54 @@ Besides being reported in Events, the reconciliation errors are also logged by
 the controller. The Flux CLI offer commands for filtering the logs for a
 specific HelmChart, e.g. `flux logs --level=error --kind=HelmChart --name=<chart-name>`.
 
+### Improving Resource Consumption Using The Cache
+
+When using a Helm Repository as source for a Helm chart and dependencies, the
+controller loads the Helm Repository index in-memory to find the latest version
+of the chart.
+
+The controller can be configured to cache a Helm Repository indexes in-memory.
+The cache is used to avoid loading Helm Repository indexes for every Helm chart
+reconciliation.
+
+Three fields are provided to enable and configure the cache:
+- `helm-cache-max-size`: The maximum size of the cache in number of indexes.
+  If `0`, then the cache is disabled.
+- `helm-cache-ttl`: The TTL of an index in the cache.
+- `helm-cache-purge-interval`: The interval at which the cache is purged of
+  expired items. 
+
+The caching strategy is to pull a Helm Repository index from the cache if it is 
+available, otherwise to load the index, to retrieve and build the chart,
+then cache the index. The cached index ttl is refreshed every time the
+Helm Repository index is loaded with the `helm-cache-ttl` value.
+
+The cache is purged of expired items every `helm-cache-purge-interval`.
+
+When the cache is full, no more items can be added to the cache, the
+source-controller will report a warning event instead.
+
+In order to use the cache, set the related flags in the source-controller
+deployment config:
+
+```yaml
+    spec:
+      containers:
+      - args:
+        - --watch-all-namespaces
+        - --log-level=info
+        - --log-encoding=json
+        - --enable-leader-election
+        - --storage-path=/data
+        - --storage-adv-addr=source-controller.$(RUNTIME_NAMESPACE).svc.cluster.local.
+        ## Helm Cache with up to 10 items, i.e. 10 indexes.
+        - --helm-cache-max-size=10
+        ## TTL of an index is 1 hour.
+        - --helm-cache-ttl=1h
+        ## Purge expired index every 10 minutes.
+        - --helm-cache-purge-interval=10m
+```
+
 ## HelmChart Status
 
 ### Artifact

main.go

@@ -115,9 +115,9 @@ func main() {
 	flag.DurationVar(&requeueDependency, "requeue-dependency", 30*time.Second,
 		"The interval at which failing dependencies are reevaluated.")
 	flag.IntVar(&helmCacheMaxSize, "helm-cache-max-size", 0,
-		"The maximum size of the cache in number of items.")
+		"The maximum size of the cache in number of indexes.")
 	flag.StringVar(&helmCacheTTL, "helm-cache-ttl", "15m",
-		"The TTL of an item in the cache. Valid time units are ns, us (or µs), ms, s, m, h.")
+		"The TTL of an index in the cache. Valid time units are ns, us (or µs), ms, s, m, h.")
 	flag.StringVar(&helmCachePurgeInterval, "helm-cache-purge-interval", "1m",
 		"The interval at which the cache is purged. Valid time units are ns, us (or µs), ms, s, m, h.")