Getting started

The gateway is configured with one YAML file. Everything reusable is defined once under Rules, then referenced by name from the scope that needs it.

Distribution

The gateway is distributed as a Docker image and as a standalone binary. Image names and download locations are shown as <placeholders> below until they are published.

1. Write a config. One backend, one route, and a rate limit bound to the route.

   gateway.yaml

   ApiVersion: v1Beta
   
   Rules:
     UsageControlRules:
       per-minute:
         RequestCount: 60
         WindowTime: 1m
   
   ServerConfigs:
     my-api:
       URL: "http://localhost:9090"
   
   ServerRoutes:
     api:
       TargetServer: my-api
       PathPattern: /api
       UsageControlRules: [per-minute]

   A request to /api/users is forwarded to http://localhost:9090/api/users, and each caller gets 60 requests per minute.

2. Validate it. nocleye check reports errors and warnings without starting the gateway.

   Binary

   nocleye check --gConfigPath ./gateway.yaml

   Docker

   docker run --rm \
     -v "$PWD/gateway.yaml:/etc/gateway/gateway.yaml:ro" \
     -e GATEWAY_CONFIG_PATH=/etc/gateway/gateway.yaml \
     <your-registry>/nocleye:<tag> check

   See the check reference for every message.

3. Run it.

   Binary

   nocleye gateway --gConfigPath ./gateway.yaml --gPort 8080

   Docker

   docker run --rm -p 8080:8080 \
     -v "$PWD/gateway.yaml:/etc/gateway/gateway.yaml:ro" \
     -e GATEWAY_CONFIG_PATH=/etc/gateway/gateway.yaml \
     <your-registry>/nocleye:<tag> gateway

   Every flag has an environment variable, see Command line.

One shape, three scopes

Global, server and route all use the same binding keys, so a rule behaves the same wherever you attach it. See Configuration file.

Next

• How requests are handled: the order the gateway applies routing, limits and auth.
• Servers and routes: path rewriting and HTTPS backends.
• Logs and metrics: the access log and Prometheus.