diff --git a/designs/cache_options.md b/designs/cache_options.md new file mode 100644 index 0000000000..ce4d4a2e52 --- /dev/null +++ b/designs/cache_options.md @@ -0,0 +1,104 @@ +Cache Options +=================== + +This document describes how we imagine the cache options to look like in +the future. + +## Goals + +* Align everyone on what settings on the cache we want to support and + their configuration surface +* Ensure that we support both complicated cache setups and provide an + intuitive configuration UX + +## Non-Goals + +* Line out how the actual implementation of the cache itself will look like. + The assumption is that the most granular level we will end up with is + "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. + Implementation will happen gradually over time whenever someone steps up + to do the actual work + +## Proposal + + +``` +type CacheSetting struct { + // LabelSelector specifies a label selector. A nil value allows to + // default this. + LabelSelector labels.Selector + + // FieldSelector specifics a field selector. A nil value allows to + // default this. + FieldSelector fields.Selector + + // Transform specifies a transform func. A nil value allows to default + // this. + Transform toolscache.TransformFunc + + // UnsafeDisableDeepCopy specifies if List and Get requests against the + // cache should not DeepCopy. A nil value allows to default this. + UnsafeDisableDeepCopy *bool +} + + +type ByObject struct { + // Namespaces maps a namespace name to cache setting. If set, only the + // namespaces in this map will be cached. + // + // A nil value in this map means "fall through to the ByObject CacheSetting" + // + // 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. + // + // A nil map allows to default this to the caches DefaultNamespaces setting. + // An empty map prevents this. + Namespaces map[string]*CacheSetting + + // CacheSettings will be used if Namespaces is empty or for entries in + // Namespaces that have a nil value. + // + // If nil, this will be defaulted to the caches DefaultLabelSelector, + // DefaultFieldSelector and DefaultTransform. + CacheSettings *CacheSetting +} + +type Options struct { + // ByObject specifies per-object cache settings. If unset for a given + // object, this will fall through to Default* settings. + ByObject map[client.Object]*ByObject + + // DefaultNamespaces maps namespace names to cache settings. If set, it + // 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 + // "all namespaces". This wil then include all namespaces that do not have + // a more specific setting. + // + // If CacheSetting is nil, DefaultLabelSelector, DefaultFieldSelector + // and DefaultTransform will be used if set. + DefaultNamespaces map[string]*CacheSetting + + // DefaultLabelSelector is the label selector that will be used as + // the default field label selector for everything that doesn't + // have one configured. + DefaultLabelSelector labels.Selector + + // DefaultFieldSelector is the field selector that will be used as + // the default field selector for everything that doesn't have + // one configured. + DefaultFieldSelector fields.Selector + + // DefaultUnsafeDisableDeepCopy is the default for UnsafeDisableDeepCopy + // for everything that doesn't specify this. + DefaultUnsafeDisableDeepCopy *bool +} +```