Policies, scope, and precedence
Policies add reusable behavior to the request pipeline without duplicating the same settings on every route. Clearplane has policy families for access control, authentication, auto-ban, cache, compression, CORS, rate limit, request headers, response headers and the web application firewall (WAF).
Policy names
Policies have a display Name and a System name (SystemName in the API). The name is free text shown in lists. The system name is generated from the name while creating a policy and can be edited. For example, PublicAPI generates publicapi; you can edit that to public-api.
Labels resolve the system name. Renaming a saved policy leaves its system name and label references unchanged. Editing the system name requires updating labels that reference it. The API preserves the existing system name when an update omits SystemName.
Route policy state
Every route has one state per policy family: Inherit, On or Off. The state decides which policies apply to the route.
| State | Policies applied to the route |
|---|---|
| Inherit | The enabled Global policy of the family, or its enabled Global policies. This is the default. |
| On | The route's own enabled policies. They replace the Global ones. |
| Off | None, even when a Global policy exists. |
The families differ only in how many policies a route and the installation can hold:
| Families | Policies per route | Global policies |
|---|---|---|
| Cache, CORS, compression, request headers, response headers, WAF | One | At most one |
| Access control, rate limit, automatic bans | One or more | Any number |
| Authentication | One or more, combined by the policy's combine mode | None, so Inherit and Off both mean no authentication |
A route that is On keeps its own policies even when they are disabled. A disabled policy stops applying, and its routes get no policy of that family until it is enabled again; they never fall back to the Global policy. A policy's Enabled switch never changes a route's state.
In the UI, set the state in the Policies section of the route dialog. On asks for the route's policies. Assigning a policy to a route from a policy dialog sets that family to On. Removing the route's last policy of the family sets it back to Inherit. The REST API accepts the same {Family}PolicyState and {Family}PolicyIds fields on a route.
Docker labels
Every family has one root label and the same label shape:
clearplane.proxy.<family>: Inherit | On | Off
clearplane.proxy.<family>.policy
clearplane.proxy.<family>.<inline-setting>
clearplane.proxy.<family>.<semantic-collection>.<index>.<field>
Only the root label switches a route to its own policies. With on, set policy to reference existing route-scoped policies by system name, or give inline settings to create a policy for this route alone. The one-policy families accept one system name, and the others accept a space-separated list. Combining policy with inline settings rejects the container. Inline settings you leave out take their documented defaults, never the Global policy's values. An inline WAF policy defaults to Detection when clearplane.proxy.waf.mode is omitted.
clearplane.proxy.waf: "On"
clearplane.proxy.waf.policy: "strict-api"
clearplane.proxy.rate-limit: "On"
clearplane.proxy.rate-limit.policy: "login-throttle api-burst"
clearplane.proxy.cors: "Off"
Family labels without the root label reject the container, and the rejection names the missing clearplane.proxy.<family>: On. Under Inherit or Off, the family's other labels are kept but ignored, so you can switch a route off without removing its settings. The Docker label reference has an example for every family, and the configuration catalog lists every supported field.
Ownership
An inline policy is generated for one discovered route and remains owned by that service. Clearplane updates it as labels change and deletes it when the service, the family labels or the inline selection disappears, or when the root label leaves on. Container-managed policies are visible but read-only through the UI and REST API, and one service cannot select another service's inline policy by system name. A container-managed WAF policy is the exception for rule tuning: its disabled rules, target exclusions and per-ruleset thresholds stay editable, because labels cannot address individual rules, and discovery keeps them.
Named policies remain managed by the source that created them. Switching from inline labels to policy deletes the generated policy and attaches the named policy; removing policy and supplying inline settings performs the inverse transition.
Global scope
A Global policy is the default for its family. It applies to every route whose state for that family is Inherit.
A new installation ships the Global WAF policy Default WAF in Detection, so every route that inherits the WAF is inspected once a ruleset is active. Set a route's WAF state to Off to opt it out.
Precedence
A route's own policies replace the Global ones of the same family. Clearplane never merges a Global policy into the route's own policies.
Evaluation inside the selected policy depends on the policy family. For example, access-control entries decide whether an address is allowed or blocked, while a rate limit policy decides whether capacity is available. Use Reference for each family's exact fields and accepted values.
Auto-ban policies observe behavior on the routes in their scope. Once an address is banned, the resulting IP ban is enforced across Clearplane until it expires or is removed. Start with Ban abusive clients automatically for the recommended protection workflow.