Как на самом деле устроен кэш в controller-runtime, и почему ваш оператор не кладёт apiserver

• чтение дешёвое, но не мгновенно консистентное после записи;
  
• запись идёт напрямую в apiserver, а не через cache;
  
• размер локального cache и набор индексов напрямую влияют на потребление памяти;
  
• неправильный List() легко превращается в линейный скан по десяткам тысяч объектов;
  
• APIReader нужен редко, но в некоторых местах без него нельзя.

• пользователь или другой контроллер меняет объект;
  
• событие попадает в очередь;
  
• Reconcile читает текущее состояние;
  
• контроллер решает, что нужно создать, обновить или удалить;
  
• система получает новое событие и цикл повторяется.

kubectl get pod -w

func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var pod corev1.Pod
    if err := r.Get(ctx, req.NamespacedName, &pod); err != nil {
        return ctrl.Result{}, err
    }
    // дальше какая-то осмысленная логика
}

• GVK (GroupVersionKind) — тройка, однозначно идентифицирующая тип ресурса в Kubernetes: группа, версия и kind. Например, apps/v1/Deployment. Почти все API в controller-runtime оперируют именно GVK, а не «именем ресурса как в kubectl».
  
• resourceVersion — непрозрачная строка, которую apiserver прикрепляет к каждому объекту (внутри — монотонно растущая позиция в etcd). Нужна для двух вещей: для оптимистического контроля конкурентности (при Update apiserver проверит, что resourceVersion у вас тот же, что и в etcd, иначе вернёт 409 Conflict) и для возобновления watch (при WATCH?resourceVersion=X apiserver пришлёт все события, случившиеся после версии X).
  
• Manager — объект ctrl.Manager в controller-runtime. Это то, что ваш оператор создаёт в main.go и запускает через mgr.Start(ctx). Он оркеструет всё вокруг: держит shared cache, создаёт клиент, запускает контроллеры, вебхуки, healthz-эндпоинты и прочие runnable’ы. В рамках одного процесса обычно один менеджер, внутри которого может жить много контроллеров.
  
• Informer — сущность из client-go, которая держит watch на один GVK, поддерживает его локальный индексированный Store и раздаёт события подписчикам. В controller-runtime он создаётся автоматически, когда вы регистрируете Watches(...) или делаете первый Get/List нужного типа.
  
• Store — in-memory хранилище информера, где лежат сами объекты. В controller-runtime у каждого информера свой Store.
  
• ResourceEventHandler — интерфейс с тремя методами: OnAdd, OnUpdate, OnDelete. Именно их информер вызывает, когда в Store что-то меняется. Подписчики (ваши контроллеры) регистрируют такие обработчики и через них узнают об изменениях.
  
• workqueue — очередь ключей (namespace/name объектов) с дедупликацией и rate-limiting’ом. На каждое событие контроллер кладёт в неё ключ, а воркеры по одному вытаскивают и передают в Reconcile как ctrl.Request.
  
• Predicate — фильтр в контроллере. Предикат решает, нужно ли вообще класть событие в очередь (например, «реагировать только на изменение spec, status игнорировать»).

• Reflector — держит WATCH к apiserver и пишет приходящие изменения в очередь в виде дельт. Дельта — это запись вида «с объектом X произошло событие Added / Updated / Deleted, вот его новая версия». По сути, одна строчка журнала изменений.
  
• DeltaFIFO — очередь этих самых дельт. По каждому ключу namespace/name копится список того, что с этим объектом происходило, причём порядок сохраняется.
  
• Indexer (Store) — in-memory хранилище объектов и индексов к ним.
  
• SharedIndexInformer — дирижёр, который склеивает всё это воедино и раздаёт события подписчикам — вашим контроллерам и прочим наблюдателям.

• Сохраняет порядок. Что бы ни прилетело по объекту default/my-deploy, на выходе вы увидите ровно ту последовательность изменений, в которой apiserver их присылал.
  
• Группирует по ключу. Все дельты по одному namespace/name копятся в одном слоте. Pop() возвращает не одну дельту, а слайс всех накопленных дельт по этому ключу — консьюмер одним разом видит всё, что произошло с объектом с прошлого вызова.
  
• Выборочно дедуплицирует. Встроенная функция dedupDeltas схлопывает подряд идущиеDeleted по одному ключу — чтобы два delete-события не превратились в две отдельные обработки.

• Added — создался Deployment (условно, с spec.replicas=1).
  
• Updated — кто-то поменял spec.replicas на 2.
  
• Updated — и сразу же на 3.

• DeltaFIFO — упорядоченная очередь дельт, группировка по ключу, дедуп только для подряд идущих Deleted. Её задача — доставить контроллерам факты изменений в правильном порядке.
  
• workqueue — очередь ключей с честным дедупом и rate-limit’ом. Именно она схлопывает «десять обновлений подряд → одна обработка».

• читать объекты напрямую из Indexer’а;
  
• подписываться на изменения через ResourceEventHandler (OnAdd, OnUpdate, OnDelete).

• При старте менеджера вызывается mgr.Start(ctx) — и он поднимает все зарегистрированные информеры.
  
• Для каждого GVK Reflector делает полный LIST — всех объектов, которые попадают под ваш scope.
  
• Ответ LIST раскладывается в Store информера, зарегистрированные индексы пересобираются, и у информера флаг HasSynced() переключается в true.
  
• После этого запускается WATCH с тем самым resourceVersion, полученным в LIST.
  
• И только теперь контроллер начинает дёргать Reconcile — конкретно, когда cache.WaitForCacheSync вернёт true для всех его источников. До этого момента воркеры не разбирают workqueue, даже если события в него уже капают.

var obj appsv1.Deployment
err := r.Get(ctx, req.NamespacedName, &obj)

item, exists, err := indexer.GetByKey("default/my-deploy")
if !exists {
    return apierrors.NewNotFound(...)
}
// DeepCopy в obj

• Чтение (Get, List) идёт через кэш.
  
• Запись (Create, Update, Patch, Delete, DeleteAllOf) идёт напрямую в apiserver.

• Чтение частое, должно быть дешёвым.
  
• Запись редкая, и должна быть точной.
  
• Если писать через кэш — получите split-brain: локальная версия считает, что всё ок, а apiserver запрос уже отклонил.

• resourceVersion в вашем PUT = resourceVersion в etcd? → ок, пишем.
  
• Нет, в etcd уже новее? → 409 Conflict, «кто-то тебя опередил».

obj.Spec.Replicas = ptr.To(int32(5))
if err := r.Update(ctx, &obj); err != nil {
    return ctrl.Result{}, err
}
// а давайте сразу перечитаем и убедимся, что там 5
var fresh appsv1.Deployment
_ = r.Get(ctx, key, &fresh)
fmt.Println(*fresh.Spec.Replicas) // внезапно 3

• Predicate — фильтр. Смотрит на событие (CreateEvent, UpdateEvent, DeleteEvent, GenericEvent) и решает, пускать его дальше или нет.
  
• EventHandler — преобразователь. Получает объект и превращает его в один или несколько ctrl.Request, которые уходят в workqueue (классический EnqueueRequestForObject просто кладёт namespace/name текущего объекта).

• То, что вы получили из r.Get / r.List — ваше, мутировать можно.
  
• То, что прилетело в Predicate или EventHandler — общее, чужое. Если зачем-то надо мутировать — руками obj.DeepCopy(), иначе получите скрытую коррапцию кэша в соседних контроллерах.

return ctrl.Result{RequeueAfter: 30 * time.Second}, nil

var pods corev1.PodList
_ = r.List(ctx, &pods)
for _, p := range pods.Items {
    if p.Spec.NodeName == "node-1" {
        // делаем что-то
    }
}

// Индекс по spec.nodeName для Pod'ов
if err := mgr.GetFieldIndexer().IndexField(
    ctx,
    &corev1.Pod{},
    "spec.nodeName",
    func(obj client.Object) []string {
        pod := obj.(*corev1.Pod)
        if pod.Spec.NodeName == "" {
            return nil
        }
        return []string{pod.Spec.NodeName}
    },
); err != nil {
    return err
}

map["node-1"] = {"default/pod-a", "kube-system/pod-b", ...}
map["node-2"] = {"default/pod-c", ...}

• На каждое входящее событие (ADDED, MODIFIED, DELETED) Indexer прогоняет объект через вашу индексирующую функцию, получает набор ключей индекса и обновляет inverted-словарь. Если Pod переехал с node-1 на node-2, ключ node-1 теряет ссылку на него, а ключ node-2 её получает.
  
• Таким образом, к моменту, когда вы делаете List, индекс уже актуален. Вы не платите за его перестройку в момент запроса — ни за какие проходы по всем объектам, ни за пересборку словаря. Вся работа сделана заранее, в момент изменения объекта.

var pods corev1.PodList
_ = r.List(ctx, &pods,
    client.MatchingFields{"spec.nodeName": "node-1"},
)

• Только equality. Range-запросов, LIKE, сортировок, агрегаций — нет. Если нужно «всё старше пяти минут» — либо делайте обычный List и фильтруйте в коде, либо используйте трюк с бакетом времени: вместо точного time.Time индексируете округлённое значение (например, now.Truncate(5*time.Minute).Format(...)). Тогда можно выбирать объекты по конкретному окну.
  
• MatchingLabels— это не индекс. Многие думают, что раз по лейблам так часто ищут, для них точно есть оптимизация. Её нет: отдельного словаря по лейблам в ThreadSafeStore не существует.
  Когда вы пишете List(..., MatchingLabels{...}), под капотом контроллер честно проходит по всем закэшированным объектам нужного типа и для каждого проверяет, подходит ли он под селектор. То есть O(n) — ровно то, от чего мы защищаемся через IndexField.
  Сам apiserver позволяет настроить поток событий по конкретному label-селектору. Но чтобы это эффективно работало в вашем контроллере, оптимизировать надо на этапе формирования кэша — через cache.ByObject{Label: ...}, — а не чтения из него. Об этом подробно — в следующем разделе про селективный кэш.
  А если нужен быстрый поиск по конкретному лейблу среди уже закэшированных — заводите IndexField по этому лейблу руками, это работает.
  
• Индекс — это память. Каждый индекс — это дополнительный словарь с ключами по каждому объекту. Не надо индексировать «на всякий случай» всё подряд.
  
• Индексировать можно только то, что есть в самом объекте. Нельзя проиндексировать Pod по «наличию связанного PVC с таким-то флагом». Пишите это поле в сам объект либо индексируйте PVC, а не Pod.

• секретами, потому что Helm хранит в них состояние релизов (helm.sh/release.v1.*), и эти секреты легко по сотне килобайт каждый;
  
• v1.Node, у которых в status.images лежит список всех образов, когда-либо оседавших на узле — в нагруженных кластерах это десятки килобайт на узел;
  
• Event’ами, которых может быть очень много и которые вам, скорее всего, кэшировать не надо вообще никогда.

mgr, err := ctrl.NewManager(cfg, ctrl.Options{
    Cache: cache.Options{
        ByObject: map[client.Object]cache.ByObject{
            // Кэшируем только Secret'ы из своего namespace, да и то по label'у
            &corev1.Secret{}: {
                Namespaces: map[string]cache.Config{
                    "my-operator": {},
                },
                Label: labels.SelectorFromSet(labels.Set{
                    "app.kubernetes.io/managed-by": "my-operator",
                }),
            },
            // Pod'ы кэшируем все, но режем лишнее при попадании в Store
            &corev1.Pod{}: {
                Transform: func(obj any) (any, error) {
                    pod := obj.(*corev1.Pod)
                    pod.ManagedFields = nil
                    return pod, nil
                },
            },
        },
    },
})

• Namespaces ограничивает область видимости. Если оператор управляет только своим namespace — нечего держать в памяти чужие.
  
• Label/Field превращаются в параметры самого WATCH. То есть apiserver шлёт вам только подходящие объекты — экономия и в сети, и в памяти.
  
• Transform вызывается до того, как объект попадёт в Store. Идеальное место срезать managedFields, гигантские annotations, бинарные data у ConfigMap, всё, что вам не нужно.
  
• DefaultLabelSelector/DefaultNamespaces — то же самое, но глобально, если все типы нужно ограничить одинаково.

var list metav1.PartialObjectMetadataList
// Обратите внимание: Kind указывается singular ("Secret"), а не "SecretList".
// То, что это list, controller-runtime понимает по типу переменной.
list.SetGroupVersionKind(schema.GroupVersionKind{
    Group:   "",
    Version: "v1",
    Kind:    "Secret",
})
if err := r.List(ctx, &list, client.InNamespace("my-ns")); err != nil {
    return err
}

• Validating webhook, где вам критична свежая версия объекта. Кэш в другом процессе в этот момент может отставать, и вы заблокируете корректный Update.
  
• Разовое чтение ресурса, для которого у вас не поднят информер. Поднимать watch ради одной операции — дорого.
  
• Чтение доmgr.Start(), например в инициализации. Обычный mgr.GetClient() в этот момент вернёт пустоту.

• Ограничьте scope кэша (Namespaces, Label, Field селекторы), особенно для «тяжёлых» типов: Secret, ConfigMap, Event, Pod, Node.
  
• ДобавьтеTransform для объектов, у которых вам не нужны «толстые» поля — ManagedFields сами по себе съедают заметную долю памяти.
  
• ДобавьтеIndexField под каждый List с MatchingFields. Нет индекса — у вас O(n) скрытого скана на каждый реконсайл.
  
• Не мутируйте объекты, полученные в EventHandler и Predicate, без предварительного DeepCopy. Мутации в Store ломают соседние контроллеры тихо и надолго.
  
• ДелайтеReconcileидемпотентным. Он должен корректно отработать, даже если его дёрнули пять раз подряд без реальных изменений.
  
• Не ждите read-after-write из кэша сразу после Update. В этом окне кэш ещё отстаёт.
  
• Если нужна свежесть (вебхуки, инициализация, разовые чтения) — используйте APIReader, а не обычный Client.
  
• ИспользуйтеPartialObjectMetadata для типов, где нужна только метадата. Это может сэкономить гигабайты.
  
• Не дёргайтеmgr.GetClient()доmgr.Start(). Информер ещё не прогрет, Store пустой, и вы получите либо NotFound, либо пустой List, а потом полдня будете выяснять, почему объект «пропал».
  
• Для отложенных действий используйтеRequeueAfter, а не time.Sleep и не свои горутины.

• Кэш в controller-runtime — не оптимизация, а модель работы. Под капотом — Reflector + DeltaFIFO + Indexer, те же самые, что и в ядре Kubernetes.
  
• r.Get / r.List идут в память, Create / Update / Patch / Delete — напрямую в apiserver. Обратная связь — через watch.
  
• IndexField + MatchingFields превращают кэш в почти полноценный query engine с inverted-индексами.
  
• Namespaces, селекторы, PartialObjectMetadata, Transform — инструменты, чтобы контролировать, сколько памяти и трафика вы реально потребляете.
  
• APIReader — аварийный выход, когда нужна строго свежая версия объекта.

• зачем нужны managedFields;
  
• как работает Server-Side Apply;
  
• как работает Patch без указания resourceVersion.