Policies

Documentation Index

Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

When to use

• Execution rules, like business hours, environment restrictions, or approval workflows.
• Access control, limiting which users, agents, or tools can act on resources.
• Safety constraints, preventing destructive changes, unauthorized workflows, or sensitive tool calls.
• Organization-wide standards, such as label requirements, naming rules, or mandatory parameters.
• Consistent governance, applied across multiple agents, teams, or environments without duplicating configuration.

​

How policies fit into Kubiya

​

Scope & attachment

• Environments — strongest, inherited by every team/agent running in that environment
• Teams — applies to all member agents
• Agents — most specific level

​

Evaluation model

• Policies are checked before the task starts and at relevant steps during execution.
• Any deny or lack of allow halts the action and returns a clear violation message.
• Allowed steps run normally.

​

Versioning & lifecycle

• Each update creates a new version (v1, v2, …).
• Policies can be enabled/disabled at any time.
• The policy card shows:
  • Associations (where it is attached)
  • Last updated
  • Status (“Enabled”, “Disabled”)

​

Prerequisites

• You must have permission to manage policies in the active control plane.
• Determine where the policy should apply (Environment, Team, Agent).
• Prepare any business logic or conditions you want to enforce.

​

Creating a Policy

​

1. Details

• Policy Name Use clear, consistent naming such as business-hours-policy or prod-restrictions.
• Description A short explanation of what it enforces.
• Enable Policy Turn on if you want it enforced immediately.
• Tags Add labels such as security, governance, operations.

​

2. Policy Content

• Templates (Business Hours, Approved Users, etc.)
• Blank (write your own Rego)

package my_policy

default allow = false

allow {
  # conditions go here
}

violations[msg] {
  not allow
  msg := "Policy violation: explain reason here"
}

​

Attach & Test Policies

​

Attach a policy

• Environment: Environments → Edit → Policies
• Team: Teams → Configure → Advanced → OPA Policies
• Agent: Agents → (open agent) → Policies

​

Verify

• Allowed (confirm normal behavior), and
• Denied (confirm your violations[msg] message appears)

​

Runtime Behavior

• All applicable policies are evaluated for every task or workflow step.
• A deny halts only the relevant action, not the entire system.
• Detailed violation messages appear in the task log.
• Policies stack: stricter rules win.

​

Managing Policies

• Enable / Disable policies from the policy card.
• Update to publish a new version.
• Detach from specific agents/teams/environments without deleting.
• Delete unused policies.

​

Useful Starter Policies

• Business Hours — restrict execution to weekdays 09:00–17:00.
• Approved Users — only members of a specific group/team may execute.
• Required Labels — block runs missing owner, service, purpose.
• Rate Limits — restrict frequency of tool/API calls.
• Sensitive Actions Require MFA — require explicit confirmation or security signals.

​

Best Practices

• Start permissive in dev/test; tighten policies in production.
• Always define a useful violations[msg] explaining how to resolve the issue.
• Use consistent tagging (e.g., security, cost, compliance).
• Prefer attaching policies at Environment level for broad governance.
• Update carefully: disable → edit → re-enable → test with read-only tasks.

​

Troubleshooting

• Unexpected block: Check violation message, then review all attached policies.
• Policy not enforced: Verify it is Enabled and attached, and Enforcer Healthy is active.
• Tool call denied: Look for deny rules tied to tool name, args, or missing metadata.
• Workflow blocked in prod but not staging: A prod-level environment policy is likely enforcing stronger restrictions.

​

CLI Usage

kubiya policy <command>

kubiya policy <command> --help

​

1. List Policies

​

Commands

kubiya policy list

kubiya policy list --output json

​

Flags

​

2. Get Policy Details

​

Commands

kubiya policy get my-policy

kubiya policy get my-policy --output json

​

Flags

​

3. Create a New Policy

​

Commands

kubiya policy create --name "prod-restrictions" --file policy.rego --env prod

kubiya policy create --name "tool-access" \
  --policy 'package tools; default allow=false; allow { input.tool == "kubectl" }'

​

Flags

​

4. Update a Policy

​

Commands

kubiya policy update prod-restrictions --file updated.rego

kubiya policy update tool-access --policy 'package tools; allow=true'

​

Flags

​

5. Delete a Policy

​

Command

kubiya policy delete prod-restrictions --confirm

​

Flags

​

6. Validate a Policy Without Creating It

​

Commands

kubiya policy validate --name "test" --file policy.rego

kubiya policy validate --name "test" --policy 'package x; allow=true'

​

Flags

​

7. Evaluate a Policy Against Input Data

​

Usage

kubiya policy evaluate [flags]

​

Examples

kubiya policy evaluate \
  --policy-file policy.rego \
  --input-file input.json \
  --query "data.tools.allow"

kubiya policy evaluate \
  --policy "package tools; allow = true" \
  --input '{"tool": "kubectl"}' \
  --query "allow"

​

Flags

​

8. Test Tool Permissions

​

Commands

kubiya policy test-tool --tool kubectl --args '{"command": "get pods"}' --runner prod

​

Flags

​

9. Test Workflow Permissions

​

Commands

kubiya policy test-workflow --file workflow.yaml --runner prod

kubiya policy test-workflow --file workflow.yaml --params '{"env":"prod"}'

​

Flags

​

Next Steps

• Add policies to all relevant environments to enforce consistent governance.
• Combine policies with Teams to enforce multi-agent guardrails.
• Use test-tool and test-workflow to validate safety before enabling strict enforcement.