Manage HTTP container path rules with Reis (YAML Mode)

Declare path rules for a Bahriya HTTP container in YAML: basic auth, rate limiting and IP lists per URL path, where the longest matching path wins.

Updated 11 Nov 20263 min read

Declare path rules in YAML alongside the rest of your infrastructure. The pathrule kind targets an existing HTTP container by handle.

YAML structure

kind: pathrule
container: my-api
handle: admin-area
path: /api/admin
priority: 100
 
security:
  basic_auth:
    - username: alice
      password: s3cret
  rate_limiting:
    enabled: true
    per_minute: 60
  ip_allowlist:
    enabled: true
    ips:
      - 10.0.0.0/8
FieldRequiredDescription
containeryesHandle (or UUID) of the HTTP container the rule belongs to.
handleyesUnique among active rules on the container. DNS-1123 compliant.
pathyesURL prefix the rule applies to. Must start with /.
prioritynoTiebreaker for equal-length prefix matches. Higher wins. Default 0.
security.basic_auth_enablednoTurn on HTTP basic authentication for this path.
security.basic_authnoList of {username, password} pairs. Setting it turns basic authentication on.
security.rate_limiting.enablednoTurn on per-IP rate limiting for this path.
security.rate_limiting.per_secondnoMaximum requests per second per IP.
security.rate_limiting.per_minutenoMaximum requests per minute per IP.
security.rate_limiting.per_hournoMaximum requests per hour per IP.
security.ip_allowlist.enablednoRestrict access to the listed IPs.
security.ip_allowlist.ipsnoList of IP addresses or CIDR ranges.
security.ip_denylist.enablednoBlock the listed IPs.
security.ip_denylist.ipsnoList of IP addresses or CIDR ranges.

Files written before Reis 1.4 put these fields at the top level under their API names (basicauthenabled, ratelimitingrequestsperminute, ipwhitelist, …). Those files still apply.

At least one control (basic auth, rate limiting, IP allow-list, or IP deny-list) must be enabled — the apply step fails otherwise.

Heads up

Do not enable both the IP allow-list and the IP deny-list on the same rule, or on the container itself. Enable one or the other. An apply that enables both is refused.

Multi-rule file

Combine multiple rules and the parent container in a single file using the YAML document separator. Apply order is top-to-bottom, so declare the container first:

kind: container
type: http
project: production
handle: my-api
name: Public API
regions:
  - falkenstein-1
workload:
  image: ghcr.io/myorg/api:latest
  cpu: "500"
  memory: "256"
  port: 8080
networking:
  external: true
 
---
kind: pathrule
container: my-api
handle: admin-area
path: /api/admin
security:
  basic_auth:
    - username: alice
      password: s3cret
 
---
kind: pathrule
container: my-api
handle: webhook
path: /webhook
security:
  rate_limiting:
    enabled: true
    per_minute: 60

Apply:

reis apply -f infrastructure.yml

How matching works

Per request, the longest matching path wins. A rule on /api/admin/users takes precedence over a rule on /api/admin for any request whose URL starts with /api/admin/users. If two rules tie on path length, the higher priority wins.

A path rule's controls fully override the container-wide settings for the same control type on that path — there is no merge. For example, if the container has rate limiting at 1000 / minute and a rule has rate limiting at 60 / minute, requests to that path are capped at 60 / minute (not 1000, not 1060).

Updating an existing rule

Re-apply the same YAML with changed fields. Reis looks up the rule on the container by handle and updates it to match the file: a field the file leaves out returns to its default, and if that would clear values the rule holds today, such as an IP list or basic auth credentials, Reis asks first (--yes confirms in scripts). Removing a rule is done via reis pathrule:delete — the YAML apply step does not delete rules implicitly.

Billing note

Each enabled control on each rule bills at the same per-region rate as the corresponding container-wide control. A rule with two enabled controls counts as two instances per region.

See also