Skip to main content

Policy Lifecycle

The kt policy command group manages two distinct document families:

Document familyPurposeCommands
Runtime gateway configProvider routing, request policies, runtime behavior, and tests in policy-config.yamllint, test, push, deploy
IAM policy documentControl-plane allow/deny statements over actions and resource KRNslint, diff, apply, evaluate, export

Do not apply an IAM policy bundle as a gateway configuration, or deploy a gateway policy-config.yaml as an IAM policy. kt policy lint --mode auto detects the family, but the mutation commands are deliberately separate.

Runtime gateway workflow​

1. Validate and test locally​

kt config validate --file policy-config.yaml
kt policy lint --mode runtime --file policy-config.yaml
kt policy test --pack-dir .
kt gateway check --config policy-config.yaml

Run a local, agent-bound gateway and exercise a representative request before a remote rollout:

kt gateway run \
  --agent policy-review \
  --policy-config policy-config.yaml \
  --listen 127.0.0.1:41002

2. Publish a version for one gateway​

kt policy push \
  --file policy-config.yaml \
  --gateway-id gw_source \
  --change-detail "Enable reviewed DLP chain"

push creates a configuration version for the source gateway and makes that version current. It does not roll the version out to other gateways.

3. Roll out to target gateways​

kt policy deploy \
  --file policy-config.yaml \
  --source-gateway-id gw_source \
  --target-gateway-id gw_canary_1 \
  --target-gateway-id gw_canary_2 \
  --change-detail "Canary rollout"

In text mode, the command creates the rollout and then polls for application on every target. The default timeout is 60 seconds and the default polling interval is 1,000 ms; override them with --timeout-secs and --poll-interval-ms only when the deployment environment warrants it.

With --json, the command prints the rollout-creation response and returns without polling. Treat that response as an accepted rollout, not proof of application: query the target gateways and verify that each one reports the returned source version before automation marks the deployment complete.

Use a canary target first. After application, verify the active configuration version and a real governed request on the target. A successful upload alone is not runtime verification.

IAM policy workflow​

An IAM policy file can hold one policy or a bundle. Each policy contains statements with an allow or deny effect, action patterns, resource KRN patterns, and optional conditions.

1. Export a reviewable baseline​

Export every remote IAM policy:

kt policy export --file iam-policies.yaml

Select policies by repeatable ID or name flags:

kt policy export \
  --file evidence-policies.yaml \
  --name "Evidence Reader" \
  --format yaml

Omitting selectors exports all policies. --format accepts yaml or json; otherwise the destination extension determines the format.

2. Lint and diff​

kt policy lint --mode abac --file iam-policies.yaml
kt policy diff --file iam-policies.yaml

diff fetches current remote policies and computes a dry-run reconcile plan. It does not mutate the organization.

By default, a policy missing from the local file is left untouched. Add --prune only when the local file is intended to be the complete desired state:

kt policy diff --file iam-policies.yaml --prune

Review every proposed deletion before continuing.

3. Evaluate a decision​

Evaluate local statements without applying them:

kt policy evaluate \
  --file iam-policies.yaml \
  --action events:read \
  --resource-krn 'krn:keeptrusts:events:eu:org_example:events'

Or select one or more existing remote policies:

kt policy evaluate \
  --name "Evidence Reader" \
  --action events:read \
  --resource-krn 'krn:keeptrusts:events:eu:org_example:events' \
  --json

Choose exactly one input mode: --file, or at least one repeatable --policy-id/--name selector. Optional --caller-attrs, --resource-attrs, and --request-attrs values must be valid JSON; use objects that match the simulator's attribute schema.

Evaluation calls the control-plane simulator. It helps review policy logic; it does not prove that a caller currently has the surrounding authentication, role assignment, or resource context used by a production request.

4. Apply reviewed changes​

kt policy apply --file iam-policies.yaml

The command prints the plan and prompts before changes. In automation, use --yes only after storing and reviewing the JSON diff:

kt policy diff --file iam-policies.yaml --json > reviewed-plan.json
kt policy apply --file iam-policies.yaml --yes --json

Current --json apply output is noninteractive even if --yes is omitted. Include --yes to make the mutation intent explicit in reviewed automation; never use JSON mode as a dry run.

Current JSON apply mode can return a successful process exit after individual operations fail. Automation must require applied == true and an empty failed array in the response, in addition to checking the exit status.

--prune authorizes removal of remote policies absent from the document. Pair it with a reviewed diff --prune; never add it merely to make remote state match unexpectedly.

Safety checklist​

  • Keep runtime config and IAM policy documents in clearly named paths.
  • Use stable policy names and statement identifiers so reviews are legible.
  • Apply least privilege and test both expected allows and expected denies.
  • Treat deny precedence and wildcard resources as high-impact changes.
  • Export before destructive reconciliation when you need a recovery record.
  • Use --json, inspect command-specific result fields, and also check exit status; do not assume exit status alone captures per-operation failures.
  • Preserve the Trail event and change detail for production rollouts.

Next steps​