Update the docs with a section regarding the cache usage

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

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.")