Activate, roll out and roll back

Activating a version makes it decide every call of the policy's agents, starting with the next call. This page covers what happens when you activate, the checks that can refuse an activation, the staged rollout the dashboard offers, and how to undo a change with a rollback.

Activation and rollback require a signed-in owner or admin. No API key can activate or roll back, and K-Block checks your role again at the moment it applies the change, so a role removed a moment ago no longer works. See Roles and permissions.

What activation does

When an owner or admin activates a draft:

1. The draft becomes active and the previously active version becomes superseded, as one change: there is never a moment with both or neither in force.
2. Every Gateway reads the agent's active version on every call, without caching, so the next call of every agent assigned to the policy is decided by the new version.
3. Calls the old version had already allowed but that have not executed yet are re-checked immediately before they run: K-Block evaluates their recorded inputs under the new version, and if the new version no longer allows them, the call is refused with POLICY_CHANGED and nothing executes. A call an observe window relaxed under the old version is not re-evaluated: it is refused with POLICY_CHANGED. Calls a person already approved are not re-checked by an activation.
4. If the activated version was the shadow, the shadow is cleared.
5. K-Block records a policy.activated audit event (with the trigger, the impact and the examples result) and sends a policy.activated webhook.

Open observe windows stay open: the new version is evaluated in observe mode for those agents. See Observe and shadow.

Activate a version

1. Open the activation sheet

   On the policy's Versions tab, select Activate on a draft, or use Review and activate v… on the Rollout tab.

2. Review what changes

   The sheet shows:

   • What changes: the decisions that change for your enabled tools, the rule changes and the line-by-line document diff against the active version (see Compare versions);
   • Recorded calls of the last 7 days and saved examples: a simulation of the draft against the active version over your agents' recorded calls, and the result of the saved examples;
   • Observe mode: agents of this policy in an open observe window;
   • Gateways: whether every Gateway can evaluate the document (the language gate).

3. Confirm the impact

   If recorded calls would become less restricted, tick I reviewed the … recent calls that become less restricted. If saved examples fail, either fix the draft or tick Activate anyway (recorded with the activation). You can type a note, but in this version its text is not stored: the policy.activated audit event only records that a note was given. Put the reason for a change in the version's own note when you save it.

4. Activate

   Select Activate v… (or Promote v… when the draft is the shadow). The sheet confirms v… is active and shows the impact over the last 7 days.

Through the API: POST /orgs/:orgId/policies/:id/versions/:versionId/activate, with the optional fields expected_active_version_id, shadow_version_id, note, acknowledge_failing_examples, max_loosened and simulation_id. Without expected_active_version_id and max_loosened, the concurrency and impact checks that use them are skipped; the language gate and the examples gate always apply.

Activation gates

A version that is already active or superseded is refused first (see Other refusals). Then the server checks these in order. A refusal changes nothing.

Language gate

A document that uses rule description or guard (language revision 2) relies on newer policy features. Every K-Block Gateway must support them: a Gateway that does not would deny every call of the policy. Until K-Block can confirm that every Gateway supports revision 2, activating such a document is refused with 409 GATEWAYS_NOT_UPGRADED.

Revision-1 documents always pass. The validation result in the editor and the Gateways section of the activation sheet show the gate's state. While it is closed, they show Activation blocked and one of these reasons:

• no Gateway has reported its version yet: K-Block has not recently received a version report from any Gateway;
• an outdated Gateway is still running (signed-in owners and admins see how many Gateways are outdated);
• an older Gateway decided calls of this organization in the last 30 minutes.

When the gate is open, signed-in owners and admins also see how many live Gateways can evaluate the document.

If the activation is refused with GATEWAYS_NOT_UPGRADED, you can:

• try again later: K-Block has not yet enabled these policy features everywhere, and the gate opens by itself once K-Block can confirm that every Gateway supports revision 2. This can take up to about 30 minutes after an older Gateway last decided a call of your organization. If activation keeps being refused, contact K-Block support with the error code, the policy and the time of your attempt (through the API, also the request ID from the response's X-Request-Id header);
• or save a version without rule descriptions and guards (revision 1) and activate that instead.

Examples gate

Every saved example with an expected outcome is evaluated against the version. If any fails, the activation is refused with 409 EXAMPLES_FAILING, listing the failing examples, unless the request acknowledges them (acknowledge_failing_examples, the Activate anyway box). The acknowledgement is recorded with the activation. See Saved examples.

Impact preview

The server evaluates the version against your agents' recent decisions: the newest 2000 decisions of the policy's agents in the last 7 days, with a time budget of 1.5 seconds (if it runs out, the impact is not computed and nothing is refused). The result is recorded on the policy.activated event and returned to you.

The activation sheet sends the number of less-restricted calls you confirmed (max_loosened). If the server counts more, for example because new calls arrived meanwhile, it refuses with 409 IMPACT_CHANGED and the new count; review it and confirm again.

Other refusals

Rollout stages

The Rollout tab shows a stepper: Observe → Shadow → Require approval → Enforce. The stage is derived from the policy's state; it is not a mode stored anywhere, and each step is one ordinary action (setting a shadow, creating a version, activating a version).

The tab offers one Next step at a time:

1. Open the editor or Start from a template, when the policy has no version.
2. Review and activate v…, when drafts exist but none is active.
3. Shadow v…, when a draft is newer than the active version.
4. Create the require-approval draft, while a version is shadowed.
5. Review and activate v… for that require-approval copy, keeping the target as the shadow.
6. Review and promote v…: activate the target itself; the shadow is cleared.

In the shadow stage you can also skip the require-approval step with Promote v… directly. Observe windows are started from the agent's page, not from this tab. During an emergency stop the stepper is paused and the only next step is a rollback.

The advisory notes on the tab (for example how many recorded calls in the last 24 hours the shadow would loosen) never block a step.

The require-approval stage

Create the require-approval draft derives a new draft from the shadowed target version:

• every deny rule becomes a require_approval rule with the same id, approvers {"roles": ["owner", "admin"]} and guard: true, placed first;
• every other rule is unchanged;
• the default becomes require_approval.

Activating this copy, while the target stays the shadow, means calls the target would deny by a rule now wait for an owner's or admin's approval instead of failing, and the shadow report shows what full enforcement will change.

Because the derived rules carry guard: true, the copy is a language-revision-2 document when the target had any deny rule, so its activation passes through the language gate. It is listed in the Versions tab with the badge require approval ("v… = v… with denials as approvals").

Roll back

A rollback returns the policy to an earlier version in one step. It never edits history: K-Block creates an exact copy of the target version as a new version number and activates it immediately.

1. Open the rollback sheet

   As an owner or admin, select Roll back to v… in the policy's header (the version activated before the current one), or Roll back to this on any superseded version in the Versions tab.

2. Choose the target and open actions

   Pick the Target. The sheet states what happens, for example "v9 will be created as an exact copy of v4 (sha256:…) and activated immediately". Tick Also close the approvals still pending… to close the approval requests made under the replaced version or any earlier version of the policy, or by agents moved into it; otherwise they stay pending and a person decides them. Optionally add a note: it is stored on the new version.

3. Roll back

   Select Roll back to v…. The next call of every agent of the policy follows the restored version.

What a rollback does and does not do:

• It needs no examples, simulation or impact check: a rollback is never blocked by them.
• It bypasses the language gate. If the restored version is revision 2 and K-Block cannot confirm that every Gateway supports it, the rollback still happens: the sheet shows Some Gateways may be outdated and the API answer carries the warning GATEWAYS_NOT_UPGRADED. A Gateway without revision-2 support denies every call of the policy that it serves (it fails closed) until K-Block upgrades it. To avoid this, roll back to a revision-1 version; if you see the warning, contact K-Block support and tell them the policy and the time of the rollback.
• It clears the shadow if the shadow was the restored version.
• It does not end observe windows.
• Calls the replaced version allowed but that have not run yet are re-checked before they run, as after any activation.
• It records policy.activated (trigger rollback) and policy.rolled_back audit events and sends a policy.activated webhook.

Through the API: POST /orgs/:orgId/policies/:id/rollback with expected_active_version_id (required; the version you saw active, or null if none), and optionally to_version_id (default: the superseded version activated most recently), note and open_actions.

Open actions after a rollback

open_actions decides what happens to actions decided under the versions the rollback replaces that are still open:

The covered actions are those decided under any version of the policy activated before the rollback, not only the version directly replaced, plus those of agents moved into the policy from another one. From the moment the rollback takes effect, K-Block refuses to approve or execute a covered action; a closed action's identical call gets a new decision under the version now in force. K-Block closes the covered actions right after the rollback and closes any that remain automatically, usually within about 15 seconds. If the sheet reports actions still open, select Close the remaining open actions (POST /orgs/:orgId/policies/:id/supersede-open-actions).

Next steps