Every team's setup has rules that nobody wrote down. That namespace belongs to
another team. That chart is pinned on purpose. Our PodDisruptionBudgets (rules that limit
how many pods a node drain may evict)
are percentages. The assistant reads these rules from two places that you control.
One is a POLICY.md at the root of the repository. The other is annotations
on individual objects. The assistant shapes its proposals to match, or withholds them.
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 that the assistant
applies exactly. These are extra namespaces to leave alone, the
minAvailable for new PodDisruptionBudgets, and the user and
group ids for security-context fixes.
The body is ordinary prose. Use it for things that do not fit a setting.
The assistant reads the file at the start of each run. It stamps the file with its git blob id, so you can trace any decision to the exact version. Every setting passes a strict check. The assistant refuses a value that does not fit. The built-in default stays, and a warning names the setting and the fallback.
policy-inspect --lint shows what the assistant read, what it
applied and what it refused. policy-init prints a
commented starting file.
Another team runs legacy-erp. You list it under
excluded_namespaces_extra. The assistant then does not send its manifests
for analysis, and it makes no repository-scan proposals for them.
The list can only add to the exclusions that your installation already has. It never removes 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 has three replicas and no PodDisruptionBudget, so the assistant proposes one.
Without a policy the proposal says
minAvailable: 1. With pdb.min_available: "50%"
it says 50%.
The assistant does not propose a floor that would block every voluntary eviction, such as
100%. A PDB that stops node
drains is worse than none.
The prose body reaches one place today: the repository-scan analysis. The assistant caps it at 2,000 characters, labels it with its source and wraps it 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. This 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. An
annotation on the HelmRelease with the token
chart-upgrade does stop it. The next scan finds the newer chart,
sees the annotation, and stays quiet.
Each token covers one proposal class (chart-upgrade,
image-upgrade, monitoring,
right-sizing, rename, …), or
all covers every class. Each installation sets its own annotation key.
A service on its way out keeps attracting proposals, such as probes,
upgrades and monitoring. retired:replacement=orders-v2
silences every agent for that object, like all. It also
carries the reason, so the assistant logs the suppression with its
rationale. The silence then does not look like a gap.
MRs from the repository scan, right-sizing, monitoring, naming and
migration agents end with opt-out instructions. They give 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 is planned
Roadmap. It will name the POLICY.md
setting and version behind a value. Until then, 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 the page marks it as such.
gitops-ai/add-poddisruptionbudget-for-orders-api into main · 2 files · +10 −0Creates PodDisruptionBudget orders-api-pdb (minAvailable: 50%) for the pods of Deployment orders-api, so a node drain cannot evict every replica at once. The MR adds the new file 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 from being evicted together.
Low. It adds a new object only. The Deployment does not change. 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. It stops making the same proposal class for this resource.
The availability rules honour this token today. They do not yet print these instructions into their MR bodies, as other agents already do.
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.
The selector matches the Deployment's pod labels. 50% of 3 allows one eviction. The Kustomization wiring is present, so Flux applies the file. LGTM.
Whoever can push to the repository writes the policy file. That person is not always the one who configured the assistant. So the assistant trusts the file only as far as it needs to.
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