> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/plugins/configuration-scopes.md). # Configuration and attachment scopes A collection plugin instance combines common placement and execution fields with a package-specific `config` object. ```json { "name": "acl_control", "tenant_id": "tenant-a", "enabled": true, "trigger": "before_request", "scope": "gateway", "gateway_id": "gateway-1", "labels": { "owner": "platform" }, "priority": 90, "execution": { "timeout_ms": 1000, "hook_timeouts_ms": { "before_request": 250 }, "failure_threshold": 3, "recovery_timeout_ms": 30000, "failure_mode": "inherit", "max_concurrency": 32 }, "config": { "allowed_groups": ["gold"] } } ``` ## Common fields | Field | Behavior | | --------------- | ------------------------------------------------------------------------------------------------------------------------- | | `name` | Exact installed package name. | | `enabled` | Controls whether the instance is loaded into the runtime chain. | | `trigger` | `before_request`, `after_response`, `on_error`, `stream`, `tcp`, `both`, `request_response`, or `all`. | | `scope` | `global`, `tenant`, `gateway`, `workspace`, `service`, `route`, `consumer`, or `consumer_group`. | | Scope selectors | `gateway_id`, `workspace_id`, `service_id`, `service_name`, `route_id`, `route_name`, `consumer_id`, or `consumer_group`. | | `labels` | Operator metadata that does not affect traffic matching. | | `priority` | Integer from `-100000` through `100000`; higher values run first. | | `execution` | Timeout, circuit, failure-mode, and concurrency controls for the instance. | | `config` | Package-specific JSON validated before persistence. | ## Scope matching | Scope | Selector | Match requirement | | -------------------- | ------------------------------ | ------------------------------------------------------------------ | | `global` or `tenant` | None | Matches traffic for the resolved tenant. | | `gateway` | `gateway_id` | The request must use the selected gateway. | | `workspace` | `workspace_id` | The request must belong to the selected workspace. | | `service` | `service_id` or `service_name` | The selected route must resolve to the service. | | `route` | `route_id` or `route_name` | The selected route must match. | | `consumer` | `consumer_id` | A matching consumer must be authenticated before plugin execution. | | `consumer_group` | `consumer_group` | The authenticated consumer must belong to the named group. | When you provide more than one selector, all selectors must match. For example, a service-scoped instance with both `gateway_id` and `service_id` applies only to that service on that gateway. Consumer and consumer-group scopes depend on established identity. Add a supported authentication plugin to protected traffic, then apply ACL or scoped policies to the identified consumer. Tenant and gateway instances can both match one request. Kangal runs every matching enabled instance; a narrower scope does not replace a broader one. ## Trigger selection * `before_request` runs before upstream proxying. * `after_response` runs after a response is available. * `both` and `request_response` select both request and response stages. * `on_error` runs for matching request failures. * `all` selects every stage exposed by the package. Use the package's documented trigger. A `before_request` plugin may return a response and stop upstream proxying; matching response-stage plugins still receive that response. ## Deterministic order Within a collection stage, matching instances run in this order: 1. higher `priority`; 2. plugin `name` in ascending order; 3. instance ID in ascending order; 4. source order as the final tie-breaker. Request and response stages use the same ordering direction. Set explicit priorities whenever plugins depend on one another. For example, run `sampling` before an observability emitter that consumes its decision. ## Collection and inline route plugins Collection request-stage plugins run before the selected route's inline plugins. On responses and errors, route-inline plugins run before collection plugins. Priorities are evaluated within each chain. Add inline plugins to a route create or update payload: ```json { "tenant_id": "tenant-a", "name": "orders", "path": "/orders", "service_id": "service-orders", "methods": ["POST"], "plugins": [ { "name": "oas_validation", "enabled": true, "trigger": "before_request", "priority": 200, "config": { "spec": { "openapi": "3.0.3", "info": { "title": "Orders", "version": "1.0.0" }, "paths": {} } } } ] } ``` Inline entries support `name`, `enabled`, `config`, trigger/stage fields, and `priority`. Collection scope fields belong on collection instances. ## Execution policy | Field | Default | Range or values | | --------------------- | --------- | -------------------------------------------- | | `timeout_ms` | `5000` | `10..30000` | | `hook_timeouts_ms` | `{}` | Per-hook values `10..30000` | | `failure_threshold` | `3` | `1..100` consecutive infrastructure failures | | `recovery_timeout_ms` | `30000` | `100..3600000` | | `failure_mode` | `inherit` | `inherit`, `fail_open`, `strict` | | `max_concurrency` | `32` | `1..256` per instance and hook | After the configured failure threshold, the instance circuit remains open for the recovery interval and then tests recovery. Authentication, access-control, rate-limit, request-protection, contract, and enforcement plugins remain fail-closed on runtime infrastructure errors. ## Troubleshooting | Symptom | Check | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Package installation returns `409` | Confirm the requested version and tenant package state. | | Create or configuration update returns `422` | Compare `config` with `config_schema`; verify exact field names and required alternatives. | | Instance does not run | Verify `enabled`, tenant, trigger, scope selectors, and the request's resolved gateway, service, route, or consumer. | | Multiple instances run | Review every matching scope and disable or narrow instances that should not stack. | | Plugin order is incorrect | Set explicit priorities and review collection and inline chains separately. | | Circuit is open | Review timeout, failure, and concurrency metrics; restore the dependency and allow the recovery probe to run. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/plugins/configuration-scopes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.