Configuration YAML Reference

Crate uses a YAML-based declarative configuration system. This schema defines the structure for configuring the Gateway via the crate.yml file (for Community Edition) or via the API (for Cloud).

Organization Schema

The top-level configuration represents a single Organization and the domains it manages.

version: "1.0"
plugins:
  - urn: "urn:crate:plugin:auth-handler"
    name: "auth-plugin"
    type: "transform"
    active: true
    config:
      header: "X-Auth-Token"
domains:
  - host: "api.myapp.com"
    details:
      ai_shield:
        enabled: true
        mode: "block"
      routing:
        type: "round_robin"
        destinations:
          - "http://backend:8080"
    routes:
      - path: "/v1/users/*"
        methods: ["GET", "POST"]
        details:
          retry_policy:
            enabled: true
            retry_on_methods: ["GET"]
          rate_limit:
            limit: 60
            rate: "minute"
            identifier_type: "ip"

Field Definitions

Field	Type	Description
`version`	string	Schema version (e.g., “1.0”).
`plugins`	array	List of global or shared plugin configurations. Valid types: `transform`, `cors`, `api_key_validation`, `ip_filter`, `payload_size_filter`, `mock`.
`domains`	array	List of domain configurations.
`details.routing`	object	Defines load balancing strategy and destinations.
`details.rate_limit`	object	Configures distributed or in-memory rate limiting.
`details.ai_shield`	object	(Domain-level only) Protects against aggressive bots and scrapers.
`details.retry_policy`	object	(Route-level only) Configures automatic retries for specific methods.

Routing Strategies

round_robin: Requests are distributed sequentially to each healthy upstream.
weighted_round_robin: Assign more traffic to your beefier servers using weights.
waterfall: Fills targets sequentially until capacity is reached.
header / header_match: Route based on specific request header values.
power_of_two_choices: Distributes load using P2C algorithm for high performance.
static: Always route to a single fixed destination.

Destinations

A list of upstream target URLs (e.g., http://backend:8080).

Managed Cloud: Only publicly routable addresses are allowed. Private IP ranges and localhost are blocked by default for security.
BYOC / Community Edition: Full support for internal network routing, including localhost, 127.0.0.1, and private IP ranges (e.g., 10.x.x.x).

Rate Limiting

limit: Total tokens in the bucket.
rate: Refill rate (second, minute, hour, day).
identifier_type: How to uniquely identify clients (body, cookie, header, ip, path, query, referer).
identifier: The specific key to use (if identifier_type is e.g., header or cookie).
multiplier: Optional multiplier for token consumption.

URNs & Smart Updates

Crate uses Uniform Resource Names (URNs) to provide stable identity for your resources. Including these URNs in your configuration allows Crate to update existing resources (preserving analytics and history) rather than recreating them.