Update designs/cache_options.md

Co-authored-by: Steven E. Harris <seh@panix.com>

designs/cache_options.md

@@ -1,7 +1,7 @@
 Cache Options
 ===================
 
-This document describes how we imagine the cache options to look like in
+This document describes how we imagine the cache options to look in
 the future.
 
 ## Goals
@@ -13,9 +13,9 @@ the future.
 
 ## Non-Goals
 
-* Line out how the actual implementation of the cache itself will look like.
+* Describe the design and implementation of the cache itself.
   The assumption is that the most granular level we will end up with is
-  "per object multiple namespaces with distinct selectors" and that this
+  "per-object multiple namespaces with distinct selectors" and that this
   can be implemented using a "meta cache" that delegates per object and by
   extending the current multi-namespace cache
 * Outline any kind of timeline for when these settings will be implemented.
@@ -26,6 +26,11 @@ the future.
 
 
 ```
+
+const (
+   AllNamespaces = corev1.NamespaceAll
+)
+
 type CacheSetting struct {
   // LabelSelector specifies a label selector. A nil value allows to
   // default this.
@@ -54,21 +59,21 @@ type ByObject struct {
   // An empty value in this map means "No Selectors".
   //
   // It is possible to have specific CacheSettings for just some namespaces
-  // but cache all namespaces by using the empty string as map key for
-  // "all namespaces". This wil then include all namespaces that do not have
-  // a more specific setting.
+  // but cache all namespaces by using the AllNamespaces const as the map key.
+  // This wil then include all namespaces that do not have a more specific
+  // setting.
   //
-  // A nil map allows to default this to the caches DefaultNamespaces setting.
+  // A nil map allows to default this to the cache's DefaultNamespaces setting.
   // An empty map prevents this.
   //
   // This must be unset for cluster-scoped objects.
   Namespaces map[string]*CacheSetting
 
-  // CacheSettings will be used if Namespaces is empty or for entries in
-  // Namespaces that have a nil value.
+  // CacheSettings will be used for cluster-scoped objects and to default
+  // CacheSettings in the Namespaces field.
   //
-  // If nil, this will be defaulted to the caches DefaultLabelSelector,
-  // DefaultFieldSelector and DefaultTransform.
+  // It gets defaulted from DefaultLabelSelector, DefaultFieldSelector,
+  // DefaultUnsafeDisableDeepCopy and DefaultTransform.
   CacheSettings *CacheSetting
 }
 
@@ -81,11 +86,11 @@ type Options struct {
   // will be usd for all objects that have a nil Namespaces setting.
   //
   // It is possible to have specific CacheSettings for just some namespaces
-  // but cache all namespaces by using the empty string as map key for
+  // but cache all namespaces by using the empty string as the map key for
   // "all namespaces". This wil then include all namespaces that do not have
   // a more specific setting.
   //
-  // If CacheSetting is nil, DefaultLabelSelector, DefaultFieldSelector
+  // If CacheSetting is nil, DefaultLabelSelector, DefaultFieldSelector,
   // and DefaultTransform will be used if set.
   DefaultNamespaces map[string]*CacheSetting
 
@@ -102,6 +107,47 @@ type Options struct {
   // DefaultUnsafeDisableDeepCopy is the default for UnsafeDisableDeepCopy
   // for everything that doesn't specify this.
   DefaultUnsafeDisableDeepCopy *bool
+
+  // DefaultTransform will be used as transform for all object types
+  // unless they have a more specific transform set in ByObject.
+  DefaultTransform toolscache.TransformFunc
+
+  // HTTPClient is the http client to use for the REST client
+  HTTPClient *http.Client
+
+  // Scheme is the scheme to use for mapping objects to GroupVersionKinds
+  Scheme *runtime.Scheme
+
+  // Mapper is the RESTMapper to use for mapping GroupVersionKinds to Resources
+  Mapper meta.RESTMapper
+
+  // SyncPeriod determines the minimum frequency at which watched resources are
+  // reconciled. A lower period will correct entropy more quickly, but reduce
+  // responsiveness to change if there are many watched resources. Change this
+  // value only if you know what you are doing. Defaults to 10 hours if unset.
+  // there will a 10 percent jitter between the SyncPeriod of all controllers
+  // so that all controllers will not send list requests simultaneously.
+  //
+  // This applies to all controllers.
+  //
+  // A period sync happens for two reasons:
+  // 1. To insure against a bug in the controller that causes an object to not
+  // be requeued, when it otherwise should be requeued.
+  // 2. To insure against an unknown bug in controller-runtime, or its dependencies,
+  // that causes an object to not be requeued, when it otherwise should be
+  // requeued, or to be removed from the queue, when it otherwise should not
+  // be removed.
+  //
+  // If you want
+  // 1. to insure against missed watch events, or
+  // 2. to poll services that cannot be watched,
+  // then we recommend that, instead of changing the default period, the
+  // controller requeue, with a constant duration `t`, whenever the controller
+  // is "done" with an object, and would otherwise not requeue it, i.e., we
+  // recommend the `Reconcile` function return `reconcile.Result{RequeueAfter: t}`,
+  // instead of `reconcile.Result{}`.
+  SyncPeriod *time.Duration
+
 }
 ```
 
@@ -132,10 +178,10 @@ Options{
 ```
 Options{
   ByObject: map[client.Object]*cache.ByObject{
-    &corev1.ConfgMap{}: {
+    &corev1.ConfigMap{}: {
       Namespaces: map[string]*cache.CacheSetting{
         "": {},                                    // No selector for all namespaces...
-        "operator" {LabelSelector: labelSelector}, // except for the operator namespace
+        "operator": {LabelSelector: labelSelector}, // except for the operator namespace
       },
     },
   },
@@ -149,7 +195,7 @@ Options{
 Options{
   ByObject: map[client.Object]*cache.ByObject{
     &appsv1.Deployment: {Namespaces: map[string]*cacheSetting:
-       "": {},
+       cache.AllNamespaces: {},
     },
   },
   DefaultNamespaces: map[string]*cache.CacheSetting{
@@ -163,7 +209,7 @@ Options{
 ```
 Options{
   ByObject: map[client.Object]*cache.ByObject{
-    &corev1.Node: {},
+    &corev1.Node: {LabelSelector: labels.Everything()},
   },
   DefaultLabelSelector: myLabelSelector,
 }