Files
cozystack/packages/system/lineage-controller-webhook/README.md
T
Nikita Aboltin 8732dc96cf feat(api): add configurable resources and replicas for cozystack-engine components
- cozystack-api, cozystack-controller, lineage-controller-webhook: conditional
  resources block via `{{- with .Values.*.resources }}`, defaulting to `{}` so the
  default render stays unchanged
- cozystack-controller: replicas comes from values (was hardcoded 1); the chart
  now passes --leader-elect unconditionally and grants the Lease verbs through a
  namespaced Role and RoleBinding in cozy-system (the Lease lives in the manager's
  own namespace), so raising replicas adds a standby instead of a second active
  writer over the reconcilers that patch HelmReleases, Gateways, Certificates,
  ResourceQuotas and Secrets

Signed-off-by: Nikita Aboltin <aboltin.nikita@rwb.ru>
2026-09-28 15:19:45 +03:00

69 lines
4.4 KiB
Markdown

# lineage-controller-webhook
Cozystack system package for the **lineage controller webhook** — a mutating
admission webhook that stamps "lineage" labels onto tenant workloads, linking
each resource back to the Cozystack `Application` that ultimately owns it.
The webhook intercepts CREATE and UPDATE on `pods`, `secrets`, `services`,
`persistentvolumeclaims`, `ingresses.networking.k8s.io`, and
`workloadmonitors.cozystack.io` outside system namespaces. For each request it
walks the ownership graph upward (Kubernetes `ownerReferences`, then the
`HelmRelease` Flux installed the resource with, then the Cozystack
`Application`-derived CRD that produced the HelmRelease) and writes the
discovered application's group, kind and name as labels
(`apps.cozystack.io/application.{group,kind,name}`) on the incoming object.
Those labels let the aggregated API server, the Cozystack dashboard, and other
lineage-aware consumers reason about which application a resource belongs to.
The webhook serves TLS on port 9443 with a cert-manager issued certificate, and
runs with `failurePolicy: Fail` — every CREATE/UPDATE on the resources above
is gated on the webhook being reachable.
## Topology
The chart ships a single shape, modelled on `cozystack-api`:
- **Deployment** with two replicas (override via `replicas`).
- **Soft `nodeAffinity`** preferring `node-role.kubernetes.io/control-plane`
(`Exists`, so it matches both Talos's empty value and k3s/kubeadm's `"true"`).
Soft means: the pod lands on a control-plane node when one is reachable, and
on any worker otherwise — no override needed for managed Kubernetes,
Cozy-in-Cozy tenants, or any other cluster where control-plane nodes aren't
visible.
- **Permissive `tolerations`** (`[{operator: Exists}]`) so the pod can land on
tainted control-plane nodes when the soft affinity is satisfiable.
- **Soft `podAntiAffinity`** on `kubernetes.io/hostname` so replicas spread
across nodes when possible (best-effort).
- **`PodDisruptionBudget`** with `maxUnavailable: 1`, unconditional. At
`replicas: 1` it's a useful no-op (allows full drain); at `replicas >= 2`
it caps disruption to one pod.
- **`Service` with `spec.trafficDistribution: PreferClose`** so the apiserver
prefers a webhook endpoint on its own node when one exists, and transparently
falls over to a remote endpoint otherwise. Requires Kubernetes ≥ 1.31; on
older clusters the field is silently ignored and traffic uses default
cluster-wide distribution.
## Parameters
All keys live under the top-level `lineageControllerWebhook:` map.
| Name | Description | Value |
| ----------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `image` | Container image (digest-pinned) | `ghcr.io/cozystack/cozystack/lineage-controller-webhook:v1.3.0@sha256:e898…6fb0` |
| `debug` | Enable `--zap-log-level=debug` instead of `info` | `false` |
| `replicas` | Deployment replica count | `2` |
| `resources` | Container requests/limits; `{}` renders no key | `{}` |
| `localK8sAPIEndpoint.enabled` | **Deprecated.** See note below. | `false` |
### `localK8sAPIEndpoint.enabled` (deprecated)
When enabled, this injects `KUBERNETES_SERVICE_HOST=status.hostIP` and
`KUBERNETES_SERVICE_PORT=6443` so the webhook talks to the kube-apiserver on
its own node. It was originally added to avoid latency on the
webhook-to-apiserver path, but it is only valid when the pod is actually
scheduled on an apiserver-bearing node — which the chart's soft control-plane
affinity no longer guarantees. With this flag enabled and the pod scheduled
off a control-plane node, the controller will crash-loop dialing a non-
apiserver hostIP. Slated for removal once the latency motivation is addressed
in the webhook itself; **leave disabled**.