BahriyaBAHRIYAby Mamluk

Manage HTTP container path rules with Reis (YAML Mode)

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

Updated 1 Jul 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
 
basicauthenabled: true
basic_auth:
  - username: alice
    password: s3cret
 
ratelimitingenabled: true
ratelimitingrequestsperminute: 60
 
ipwhitelistenabled: true
ipwhitelist:
  - 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.
basicauthenablednoTurn on HTTP basic authentication for this path.
basic_authnoList of {username, password} pairs. Implies basicauthenabled: true.
ratelimitingenablednoTurn on per-IP rate limiting for this path.
ratelimitingrequestspersecondnoMaximum requests per second per IP.
ratelimitingrequestsperminutenoMaximum requests per minute per IP.
ratelimitingrequestsperhournoMaximum requests per hour per IP.
ipwhitelistenablednoRestrict access to the listed IPs.
ipwhitelistnoList of IP addresses or CIDR ranges.
ipblacklistenablednoBlock the listed IPs.
ipblacklistnoList of IP addresses or CIDR ranges.

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

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
image: ghcr.io/myorg/api:latest
regions:
  - falkenstein-1
workload:
  cpu: "500"
  memory: "256"
  port: 8080
 
---
kind: pathrule
container: my-api
handle: admin-area
path: /api/admin
basicauthenabled: true
basic_auth:
  - username: alice
    password: s3cret
 
---
kind: pathrule
container: my-api
handle: webhook
path: /webhook
ratelimitingenabled: true
ratelimitingrequestsperminute: 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 in place. 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