|
| 1 | +--- |
| 2 | +title: Guardrails and Policies |
| 3 | +--- |
| 4 | + |
| 5 | +# Guardrails and Policies |
| 6 | + |
| 7 | +A policy is a pluggable unit of behavior that runs in the gateway's request or response pipeline. Policies handle cross-cutting concerns: authentication, rate limiting, header manipulation, content moderation, and LLM-specific controls such as prompt decoration, semantic caching, and guardrails. Several policies can be chained on the same resource. |
| 8 | + |
| 9 | +Policies are built into the gateway image, not installed at runtime. Which policies a [Gateway](./gateway.mdx) can offer is fixed when its image is built; what you choose in the console is which of those policies to apply, and with what settings. |
| 10 | + |
| 11 | +## Where Policies Come From |
| 12 | + |
| 13 | +Every policy originates in one of two places: |
| 14 | + |
| 15 | +- **Hub policies** are published to the WSO2 API Platform Policy Hub and referenced by Go module path. These are the policies a stock gateway image ships with. |
| 16 | +- **Local policies** are your own implementations, referenced by file path when the image is built. See [Use a Custom Gateway Image](../guides/use-a-custom-gateway-image.mdx). |
| 17 | + |
| 18 | +Both kinds are compiled into the image by the same build. Once the gateway is running, nothing distinguishes them except where their source came from. |
| 19 | + |
| 20 | +## How Agent Manager Learns Which Policies Exist |
| 21 | + |
| 22 | +Agent Manager does not read the gateway image. It is told what the gateway has: |
| 23 | + |
| 24 | +1. The gateway controller connects to Agent Manager over its internal endpoint and authenticates with its registration token. |
| 25 | +2. It pushes a **policy manifest**: the set of policy definitions compiled into its image, with each policy's name, version, display name, description, and parameter schemas. |
| 26 | +3. Agent Manager caches that manifest and serves it back to the console. |
| 27 | + |
| 28 | +The manifest is re-pushed on a heartbeat, so the cached copy reflects whatever the gateways are currently running. Because every gateway in a deployment normally runs the same policy bundle, the cache holds one copy shared across all of them rather than one per gateway. |
| 29 | + |
| 30 | +A policy is offered only when every gateway in scope reports it. If gateways disagree on a policy's version, as happens during a rolling upgrade, the lowest reported version is used, so a policy already applied does not disappear mid-rollout. |
| 31 | + |
| 32 | +## The Three Configuration Layers |
| 33 | + |
| 34 | +Most confusion about policies comes from conflating these. A policy can be present at one layer and absent at the next, and each layer fails differently. |
| 35 | + |
| 36 | +| Layer | Set where | Scope | Failure when missing | |
| 37 | +|---|---|---|---| |
| 38 | +| **Build time** | `build.yaml`, compiled into the image | The image | Policy never appears anywhere | |
| 39 | +| **System parameters** | Helm values on the gateway extension release | Whole deployment | Policy appears but fails at request time | |
| 40 | +| **Policy parameters** | Console, when you apply the policy | One resource | Policy is rejected when you try to apply it | |
| 41 | + |
| 42 | +**Build time** decides which policies exist at all. |
| 43 | + |
| 44 | +**System parameters** are the deployment-wide settings a policy needs to reach an external service, such as an endpoint, a region, or an API key. They are shared by every use of that policy and are supplied as Helm values, never through the console. A policy whose system parameters are missing is still offered in the console and still applies cleanly; it fails when a request reaches it. See [Configure Guardrail System Parameters](../guides/configure-guardrail-system-parameters.mdx). |
| 45 | + |
| 46 | +**Policy parameters** are the per-use settings you fill in when applying a policy to an LLM Service Provider or MCP Proxy, such as the regex to match, the token ceiling, or the categories to block. |
| 47 | + |
| 48 | +Policies that need no external service, such as the regex and word-count guardrails, have no system parameters at all. They work as soon as the image contains them. |
| 49 | + |
| 50 | +## Visibility in the Console |
| 51 | + |
| 52 | +What the console offers is narrower than what the gateways report, and the two pickers narrow it differently. |
| 53 | + |
| 54 | +The **LLM guardrail picker** treats the gateway-reported list as authoritative. It consults the Policy Hub only to borrow friendly display names for built-in policies, and a Hub failure never blocks the list. A custom policy appears here as soon as your gateways report it. |
| 55 | + |
| 56 | +The **MCP policy picker** intersects the gateway-reported list with the public Policy Hub catalog. A policy that is not published to the Hub is filtered out even when every gateway reports it, so custom MCP policies do not appear. |
| 57 | + |
| 58 | +Separately, guardrails that depend on an external service are hidden behind capability flags on the Agent Manager release, so an operator who has not configured the backing service does not see a policy that cannot yet work. These flags only filter the console list; they do not stop the policy being applied through the API. |
| 59 | + |
| 60 | +## Relationship to Other Concepts |
| 61 | + |
| 62 | +- **[Gateway](./gateway.mdx)**: the component policies run in. A gateway's policy set is fixed by its image. |
| 63 | +- **[LLM Service Provider](./llm-service-provider.mdx)** and **[MCP Proxy](./mcp-proxy.mdx)**: the resources policies are applied to. |
0 commit comments