Every estate has rules nobody wrote down: that namespace belongs to
another team, that chart is pinned on purpose, our PodDisruptionBudgets
are percentages. The assistant reads them from two places you control,
a POLICY.md at the root of the repository and annotations
on individual objects, and shapes or withholds its proposals to match.
POLICY.md in the repository, and skip annotations on the objects themselves.
POLICY.md sits at the root of the repository, next to
your README. The header block holds settings the assistant
applies exactly: extra namespaces to leave alone, the
minAvailable for new PodDisruptionBudgets, the user and
group ids for security-context fixes.
The body is ordinary prose, for the things that do not fit a setting.
The file is read at the start of each run and stamped with its git blob id, so any decision can be traced to the exact version. Every setting passes a strict validator. A value that does not fit is refused, the built-in default stays, and a warning names the setting and the fallback taken.
policy-inspect --lint shows what was read, what was
applied and what was refused. policy-init prints a
commented starting file.
legacy-erp is run by another team. Listed under
excluded_namespaces_extra, its manifests are not sent
for analysis and get no repository-scan proposals.
The list can only add to the exclusions your installation already has, never remove one. Agents that scan the whole cluster (upgrades, monitoring, migration) still use the installation-wide list; per-repository exclusions there are planned Roadmap.
A Deployment with three replicas and no PodDisruptionBudget gets
one proposed. Without a policy it would say
minAvailable: 1. With pdb.min_available: "50%"
it says 50%.
A floor that would block every voluntary eviction, such as
100%, is not proposed at all: a PDB that stops node
drains is worse than none.
The prose body reaches one place today: the repository-scan analysis. It is capped at 2,000 characters, labelled with its source and wrapped as untrusted content. "NetworkPolicy is not enforced on this cluster" steers the analysis away from proposing NetworkPolicies. "Ignore all previous instructions" does nothing.
Other agents do not read the prose yet Roadmap, which matters for the next rule.
A sentence in the prose will not stop an upgrade MR, because the
upgrade agent does not read the prose. The lever that does is an
annotation on the HelmRelease with the token
chart-upgrade. The next scan finds the newer chart,
sees the annotation, and stays quiet.
Tokens are per proposal class (chart-upgrade,
image-upgrade, monitoring,
right-sizing, rename, …), or
all. The annotation key itself is set per installation.
A service on its way out keeps attracting proposals: probes,
upgrades, monitoring. retired:replacement=orders-v2
silences every agent for that object, like all, and
carries the reason with it, so the suppression is logged with its
rationale instead of looking like a gap.
MRs from the repository scan, right-sizing, monitoring, naming and
migration agents end with opt-out instructions: the exact annotation
and token that would stop this class of proposal for this object.
On any MR, a /skip comment prepares that change for you.
A "Policy applied" section naming the POLICY.md
setting and version behind a value is planned
Roadmap; today that trail lives in
the run log and in policy-inspect.
--- excluded_namespaces_extra: - legacy-erp pdb: min_available: "50%" security_context: run_as_user: 10001 run_as_group: 10001 --- # Platform policy NetworkPolicy is not enforced on this cluster; do not propose NetworkPolicies. Namespace legacy-erp is owned by the ERP team and deployed from their own pipeline.
POLICY.md @ blob 7e1c0a4 · prose 212 chars · read knob value from excluded_namespaces_extra legacy-erp repo ∪ global pdb.min_available 50% repo security_context.run_as_user 10001 repo security_context.run_as_group 10001 repo security_context.fs_group — global default unknown keys: pdb.min_availble (ignored)
+apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: orders-api-pdb + namespace: shop +spec: + minAvailable: 50% + selector: + matchLabels: { app: orders-api }
kind: HelmRelease metadata: name: opensearch annotations: gitops-assistant/skip: chart-upgrade spec: chart: spec: { chart: opensearch, version: 2.17.0 }
metadata: name: orders-legacy annotations: gitops-assistant/skip: retired:replacement=orders-v2
skip_annotations: Deployment orders-legacy retired (retired; replacement=orders-v2) — suppressing action 'monitoring' skip_annotations: Deployment orders-legacy retired (retired; replacement=orders-v2) — suppressing action 'image-upgrade'
Illustrative. The PDB file name, selector and kustomization wiring follow what the assistant writes today; the "Policy applied" block is the planned addition and is marked as such.
gitops-ai/add-poddisruptionbudget-for-orders-api into main · 2 files · +10 −0Creates PodDisruptionBudget orders-api-pdb (minAvailable: 50%) selecting Deployment orders-api's pods, so a node drain can't evict every replica at once. The new file is added to the directory's kustomization.yaml.
orders-api runs 3 replicas across 3 nodes with no disruption budget. A node pool upgrade drains nodes one at a time but nothing stops two replicas being evicted together.
Low. New object only; no change to the Deployment. With 3 replicas, 50% keeps 2 available and still allows one eviction at a time, so drains are not blocked.
| Setting | Value | Source |
|---|---|---|
pdb.min_available | 50% | POLICY.md @ blob 7e1c0a4 (installation default: 1) |
excluded_namespaces_extra | legacy-erp | not relevant to this MR |
apps/shop/orders-api/poddisruptionbudget_orders-api.yaml (new) +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: orders-api-pdb + namespace: shop +spec: + minAvailable: 50% + selector: + matchLabels: + app: orders-api apps/shop/orders-api/kustomization.yaml resources: - deployment.yaml - service.yaml + - poddisruptionbudget_orders-api.yaml
To opt out of availability proposals for Deployment/orders-api, add the annotation gitops-assistant/skip: availability to the resource's metadata.annotations. The assistant respects this annotation across runs and stops emitting the same proposal class for this resource.
The availability rules honour this token today; printing these instructions into their MR bodies, as other agents already do, is not done yet.
Use all to opt the resource out of every proposal, or retired:replacement=<name> if it is being replaced. Commenting /skip on this MR prepares the annotation change for you.
Selector matches the Deployment's pod labels; 50% of 3 leaves one eviction allowed. Kustomization wiring present, so the file is actually applied. LGTM.
A policy file is written by whoever can push to the repository. That is not always the same person who configured the assistant, so the file is trusted only as far as it needs to be.
all and retired, honoured across agents/skip prepares the annotation on any MRPOLICY.md settings: extra excluded namespaces, PDB floor, security-context ids, ExternalSecret refresh intervalpolicy-inspect --lint and policy-initPOLICY.md additions