Configuration YAML Reference

Crate uses a YAML-based declarative configuration system at the organization level. This single schema is used by both the Managed Cloud (via the Configuration API) and the Community Edition (via local files).

Organization Schema

The top-level configuration represents a single Organization.

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

Field Definitions

Field	Type	Description
`name`	string	Display name for the organization.
`domains`	array	List of domain configurations.
`details.routing`	object	Defins load balancing strategy and destinations.
`details.rate_limit`	object	Configures distributed or in-memory rate limiting.
`details.ai_shield`	object	Protects against aggressive bots and scrapers.
`details.retry_policy`	object	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.

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: The header or metadata key used to identify the user.

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.