Features

Protection plans

Lock chosen changes on an application or namespace for a set time window, prove the lock is in force, and keep a report of what it blocked.

In a shared cluster, anyone with write access can delete, scale or re-image a critical app at any time. RBAC is permanent and per object; it cannot say "nobody changes checkout's images or Secrets between 22:00 and 02:00 tonight". A change freeze announced in chat depends on everyone reading it.

A plan is enforced at admission, so it binds every writer in its scope alike: people, pipelines and AI agents.

What you get

  • A plan that locks specific kinds of change (creation, deletion, image changes, scaling, ConfigMap and Secret edits, storage, …) for chosen applications or namespaces.
  • A time window: the plan arms itself at its start and disarms itself at its end, repeats in weekly windows, or stays on until you cancel it.
  • Audit mode to see what would have been blocked, then enforce mode to block it.
  • Optional approval before anything is enforced. Plans in the Production environment always require one.
  • Health checked against the live cluster, with drift repaired while the plan is active.
  • Admission decisions, with who sent each, while the plan runs, and a downloadable report (HTML, Markdown, JSON or CSV) when it ends.

The Protection plans page: one card per plan with its window, scope, mode, templates, health and what it refuses

Plans live on the Protection plans page of the dashboard.

How it works

A plan (ProtectionPlan, protectionplans.telark.io) has three parts:

  1. Scope. A list of applications, or a list of namespaces. Exclusions carve kinds, or named resources of the selected applications, back out.
  2. Templates. One or more of the nine built-in policy templates, with parameters where a template needs them. block-replica-scaling supports the applications scope only.
  3. Window. permanent (until canceled), time_range with startAt and endAt, or repeating with repeat: the weekdays, a startTime and an endTime (HH:MM) and an IANA timeZone, for example every Sunday from 02:00 to 04:00 in Europe/Paris.

While the plan is active, discovery renders each template into Kyverno NamespacedValidatingPolicy objects (policies.kyverno.io/v1), one per template and namespace, and applies them. Kyverno (bundled with the chart by default, or one you already run) enforces them at admission. When the plan ends or is canceled, or a window of a repeating plan closes, those policies are deleted. Nothing stays in the cluster outside the window.

Audit and enforce

The plan's mode sets validationActions on every policy it deploys: Audit or Deny.

  • audit: the change is admitted and recorded as an admission decision. The message reads "would be blocked by protection plan …". A server dry run (kubectl diff, --dry-run=server) changes nothing and is not recorded.
  • enforce: the change is refused. The caller sees the Kubernetes API error at the source of the change.

Each message names the plan as you wrote it and ends with (requested by "<username>"), the Kubernetes user who sent the request.

Enforcing a namespace scope needs Owner on protection-plans; a Contributor can create audit plans on namespaces and enforce plans on applications.

Lifecycle

PhaseMeaningPolicies in the cluster
pending_approvalWaiting for an approver.None
scheduledstartAt is in the future, or a repeating plan is between windows.None
activeIn force. Health and admission decisions are live.Deployed
terminatedThe time range ended, while active or still waiting for approval, or passed whole while Telark was down (the plan then never activates). Time never ends a repeating plan.Removed
canceledCanceled by a user, or rejected by an approver.Removed
failedActivation failed (scope resolution, render or deploy).Removed

A controller on the discovery leader moves plans across window edges, every 31 seconds by default (PROTECTION_PLAN_TICK_INTERVAL_SEC) and on a timer set for the next edge.

A repeating plan is active during each window and scheduled between them, and one approval covers every window. Windows follow the wall clock of the plan's time zone, so a window that spans a daylight-saving change is shorter or longer, and one that lies in the hour the change skips (02:00 to 03:00 in Paris on the spring-forward day) does not run that day.

You can:

  • cancel an active, scheduled, pending_approval or failed plan;
  • reactivate a terminated, canceled or failed plan. It re-enters the lifecycle and asks for approval again where required;
  • edit a plan in any phase. Changing the window recomputes the phase; an active plan given a future start withdraws its policies until then. An edit of a canceled or terminated plan takes effect on reactivation. The scope type cannot change. An approved plan locks its material fields, with an exception for repeating plans (see Approvals).
  • duplicate a plan into a new one.

Exclusions

  • Kinds: exclude whole kinds, for example ConfigMap, from either scope type.
  • Resources: exclude named resources (kind, name, namespace) of the selected applications. Applications scope only.

Exclusions apply to every template's rules, and an excluded kind or resource also excludes its /scale subresource. Changing them re-renders the plan's policies and follows the same approval rules as any scope change.

Approvals

The server derives approvalMode when a plan is created or duplicated:

A plan details page: the summary band, then the plan summary with its status, timeline, participants, scope and policies, and its health

  • A plan in the Production environment is always required.
  • Elsewhere the default is automatic. A client may ask for required; asking for automatic counts only from an Owner on protection-plans.
  • A Contributor's duplicate of an approval-required plan stays approval-required; only an Owner may relax it.
  • The mode cannot change afterwards, and an edit may not move an automatic plan into Production.

A required plan waits in pending_approval with nothing deployed, and every user who may approve it gets an in-app notification. An approver (Owner on protection-plans) approves it, and the plan becomes scheduled or active, or rejects it with a mandatory comment, which cancels the plan.

  • Nobody who put the current version up for approval can decide it: the creator, and anyone who reactivated or materially edited it since the last approval.
  • A decision names the request it answers, so a stale or concurrent decision is refused (409).
  • Once approved, material edits (scope, exclusions, templates, mode, window) are refused. Duplicate the plan, or cancel and reactivate it, to request a new approval. A material edit of a plan still pending asks for approval again.
  • An approved repeating plan is the exception: a material edit is refused while a window is open and, between windows, applied and sent back for approval.

Kinds, environments and tags

A plan carries at most one kind, one environment and up to 20 tags, all categories. QA, Testing, Release and Maintenance window ship as kinds; Production, Staging and Development as environments; Compliance, Security and Baseline as tags. Add your own on the Categories page in the sidebar, which Organize on the Protection plans page also opens. They filter the plan list and never change what a plan renders. A category still in use can't be deleted: move its plans to another one first.

The Categories page on its Plan tags tab: built-in and custom tags, beside the Groups, Roles, Plan kinds and Plan environments tabs

Health

Health is read from the cluster, not assumed from the API write. On each controller tick, discovery compares the Kyverno policies labeled telark.io/protection-plan=<plan id> with a fresh render of the plan, by the telark.io/render-hash annotation and by the live spec, compared as Kyverno's ValidatingPolicySpec. A hand edit of the spec reads as drift even when it keeps the annotation. The render sets the CRD's two defaults itself, so the API server's defaulting never reads as drift.

HealthMeaning
healthyEvery declared policy is present, ready, current, and uses the plan's mode.
driftedThe plan lists no rendered policies, a declared policy is missing or edited, its validation actions no longer match the mode, an unexpected policy carries the plan label, or the plan now renders a policy it has not listed yet.
degradedA policy is present but Kyverno has not made it ready. Wins over drift. Every active plan also reads degraded when the cluster serves no policies.kyverno.io kind (Kyverno older than 1.18). Right after the upgrade to 0.2.0, a new policy that is still not ready 2 minutes after its creation reads degraded while its 0.1.x predecessor keeps enforcing.
unknownThe plan is not active.

While the plan is active, the same tick repairs drift: missing policies are redeployed, a stale one is replaced whole, changed validation actions are patched back, and unexpected policies with the plan label are deleted. Managed policies left behind by a plan that ended are swept too. The tick stores the result on the plan's status, with the conditions Ready, Approved and PoliciesHealthy. Refresh health in the dashboard computes health on request without repairing or storing it.

GET protectionplans/{id}/status names the affected policies in its drift object: missing and unexpected, plus mismatched (validation actions differ from the mode), stale (edited or outdated) and added (rendered but not listed yet). The last three are omitted when empty.

Admission decisions

The plan's admission decisions are the Kyverno PolicyViolation events of its policies, across the namespaces its scope resolves to, newest first. Each carries the policy, rule, resource (kind, name, namespace), result, message, timestamp and requestedBy, the Kubernetes user who sent the request (events from before 0.2.0 name none). The dashboard shows the results as Allowed (pass), Blocked (fail, or Would block on an Audit plan), Warning (warn), Policy error (error) and Not checked (skip). A write the API server retries after a conflict is judged again on each attempt, so it can show more than once.

The Admission decisions section of a plan: a blocked replica scaling, with the resource and the user who sent it

Kubernetes keeps events for one hour by default, so discovery copies them into a per-plan ledger before they expire. The plan's page lists every decision since the plan started (since the window opened, for a repeating plan), read from the ledger and the live events, and says when the oldest ones no longer fit. Between windows a repeating plan shows "No window is open": each past window has its own report. A finished plan keeps its list.

Reports

A report covers what happened while a plan was in effect: its configuration, scope and policies, timeline, health over the run, and the admission decisions it recorded.

  • A final report is captured automatically when an active plan ends or is canceled. Parking an active plan (an edit that moves its start into the future) writes an end report for that run. A plan that never started has none.
  • Each window of a repeating plan gets its own report when it ends. The newest 100 window reports per plan are kept.
  • Generate one on demand from the plan's page once the plan has started. Two renders run at a time. The newest 10 on-demand reports per plan are kept; final reports are never pruned.
  • While a plan runs, its admission decisions are checkpointed into a per-plan ledger every 15 minutes (PROTECTION_PLAN_REPORT_CHECKPOINT_SEC), so a report is not limited to the one-hour event window. A report keeps at most 5,000 decisions and says when it was truncated.
  • The Reports tab lists every plan's reports, filterable by plan, environment, trigger (manual, cancel, end, window) and date.
  • Reports live on the exporter's reports volume. Deleting a plan deletes its reports, unless you select Keep its reports in the delete dialog: they then stay in the Reports tab under the plan's name with "(deleted)" until someone deletes them. Whoever may delete plans (Owner, deleteprotectionplan) may also delete any single report, from the plan's page or the Reports tab.

Permissions

Every plan action has its own permission on the protection-plans scope, and a custom role can withhold any one of them with protection-plans.<action>.deny.

ActionMinimum level
viewprotectionplans, viewprotectionplanviolations, viewprotectionplanreports, downloadprotectionplanreportReadOnly
createprotectionplan, editprotectionplan, duplicateprotectionplan, cancelprotectionplan, reactivateprotectionplan, generateprotectionplanreport, addprotectionplancategoryContributor
approveprotectionplan, rejectprotectionplan, deleteprotectionplan, editprotectionplancategory, deleteprotectionplancategoryOwner

The three *protectionplancategory actions govern kinds, environments and tags. deleteprotectionplan also covers deleting a single report. Report files include admission decisions, so withholding violations alone does not hide them.

Validation

Discovery refuses a plan when:

  • its name is taken, ignoring case and surrounding spaces (409);
  • its name or description contains {{ or }} (400);
  • its window has already ended (400);
  • it targets the release namespace, an excluded namespace or a namespace that does not exist (400); while the excluded list cannot be read, a namespace-scoped plan answers 503;
  • a template does not support the scope, is listed twice, or gets a parameter it does not declare (400).

Names are at most 64 characters and descriptions 512.

Limits

  • The bundled Kyverno fails open by default (kyverno.features.forceFailurePolicyIgnore.enabled=true): while its webhook is down, changes are admitted even for enforcing plans. Set it to false to fail closed.
  • Plans act at admission, inside the cluster. They do not gate CI pipelines, and they cannot undo a change made before the plan started.
  • Templates are a fixed catalog.

Reference