Protect a function

Decorate the function that acts, name the action and the consequence, and put the call inside a context that names who is acting. From then on every call is decided, reserved, executed and recorded, and a refusal is an exception raised before the function body runs. Prerequisites: pip install ctrlrun, Python 3.11 or later, an empty directory. Every block below runs offline; the deploy tool is a stand-in that records calls.

Write the policy

Three actions across two domains: a rollout restart that is cheap to undo, a namespace delete that needs a human, and a role grant that is autonomous for readers and needs a human for anything else.

runnable

schema: ctrlrun.policy/v2

actions:
  k8s.rollout_restart:
    effect: "restart:{cluster}:{deployment}"
    decision: allow
  k8s.delete_namespace:
    effect: "namespace:{cluster}:{name}"
    decision: approve
  iam.grant_role:
    effect: "grant:{principal}:{role}"
    rules:
      - when: { role_in: [reader, viewer] }
        decision: allow
      - decision: approve

Decorate the functions

effect= is a template over the function’s own parameters. It names the consequence, so the same delete proposed twice, by a retry or by a second worker, is one effect.

runnable file=infra.py

import sys

import ctrlrun

calls: list[str] = []


def kubectl(*args: str) -> str:
    calls.append(" ".join(args))
    return "ok"


@ctrlrun.protect("k8s.rollout_restart", effect="restart:{cluster}:{deployment}")
def restart(cluster: str, deployment: str) -> str:
    return kubectl("rollout", "restart", f"deployment/{deployment}", "--context", cluster)


@ctrlrun.protect("k8s.delete_namespace", effect="namespace:{cluster}:{name}")
def delete_namespace(cluster: str, name: str) -> str:
    return kubectl("delete", "namespace", name, "--context", cluster)


@ctrlrun.protect("iam.grant_role", effect="grant:{principal}:{role}")
def grant_role(principal: str, role: str) -> str:
    return kubectl("create", "rolebinding", f"{principal}-{role}", "--role", role, "--user", principal)


with ctrlrun.context(agent="deploy-agent"):
    print("restart:", restart(cluster="prod-eu", deployment="checkout"))
    print("grant reader:", grant_role(principal="ana@example.com", role="reader"))

    try:
        delete_namespace(cluster="prod-eu", name="checkout")
    except ctrlrun.ApprovalRequired as pending:
        print("delete namespace: a human decides:", pending.request_id)
    else:
        sys.exit("a namespace delete ran without a human")

    try:
        restart(cluster="prod-eu", deployment="checkout")
    except ctrlrun.DuplicateEffect as refused:
        print("restart again:", type(refused).__name__)
    else:
        sys.exit("the same restart ran twice")

    try:
        grant_role(principal="ana@example.com", role="admin")
    except ctrlrun.ApprovalRequired:
        print("grant admin: a human decides")

print("kubectl calls:", len(calls))

Run it with python infra.py:

restart: ok
grant reader: ok
delete namespace: a human decides: apr_…
restart again: DuplicateEffect
grant admin: a human decides
kubectl calls: 2

Two calls reached the stand-in: the restart and the reader grant. The delete and the admin grant are waiting for a person, and the second restart was refused because restart:prod-eu:checkout had already committed.

Read what happened

runnable

ctrlrun receipts
ctrlrun effects

Every call that reaches a decision has a receipt, denied ones included, and every effect key has a state. A call waiting on a human has an approval request and no receipt yet. The pending approvals are what ctrlrun approve <request id> answers; the quickstart walks through presenting one.

The decorator’s arguments

Argument	What it does
`name`	the action name the policy decides
`effect=`	a template over the parameters naming the consequence; without it the call gets no reservation, which is right for a read
`resource=`	a template for the resource, part of the hash and what a grant’s `resources:` matches
`wait=True`	block on the approval provider instead of raising `ApprovalRequired`; what an adapter or a webhook provider needs
`lease=`	how long the reservation is held for a slow call; past it the effect is `AMBIGUOUS`, never released
`reconcile=`	a function that asks the remote what happened to an effect key; Reconcile automatically
`control=`	a `Control` you built, instead of the one discovered from `ctrlrun.yaml`

Template syntax is checked at decoration time, so a typo fails at import rather than mid-run. A protected function may not take *args or **kwargs, and may not name a parameter after a reserved subject.

If it didn’t work

ActionDenied: ... no principal is available: the call is outside ctrlrun.context(...).
ActionDenied: ... unknown_action: the decorator’s name is not a key under actions:.
EffectKeyError: ... {cluster}: the template names a parameter the function does not have, or the argument was None.
PolicyError: ... could not be read: no ctrlrun.yaml in the working directory and $CTRLRUN_CONFIG is unset.

Put the gateway in front of MCP: the same guarantees with no code change.
Effect keys · Get started · Why.

Start

Get started

Production

MCP

Concepts

Guides

Cookbook

Compare

FAQ

More

Protect a function

The decorator’s arguments

If it didn’t work

Next

​The decorator’s arguments

​If it didn’t work

​Next

The decorator’s arguments

If it didn’t work

Next