Deployment via Docker

To deploy the Getaway gateway, utilize the official container image. The following command initializes the container, mapping the host port 8080 to the container's port 8080:

docker run -d \
  --name getaway-gateway \
  -p 8080:8080 \
  --restart on-failure \
  getaway/getaway:stable

Defining Routes and Services

Gateway behavior is controlled using a YAML configuration file. This file defines backend endpoints and the routing logic to reach them. Below is a sample configuration setting up two distinct backend services.

endpoints:
  catalog_api:
    location: "http://catalog.svc.local:8080"
    prefix: "/v1/catalog"
  user_api:
    location: "http://user.svc.local:8080"
    prefix: "/v1/users"

rules:
  - pattern: "/v1/catalog/*"
    target: catalog_api
  - pattern: "/v1/users/*"
    target: user_api

Loading Configuration

For the gateway to apply custom rules, the configuration file must be mounted into the container. The container reads the file specified by the CONFIG_PATH environment variable.

docker run -d \
  -p 8080:8080 \
  -v $(pwd)/gateway.yaml:/app/config/gateway.yaml \
  -e CONFIG_PATH=/app/config/gateway.yaml \
  --name getaway-gateway \
  getaway/getaway:stable

Configuration Directives

• endpoints: Defines the upstream services.
• location: The full URL of the upstream service.
• prefix: The base path associated with the service.
• rules: Determines how incoming traffic is mapped to endpoints.
• pattern: The URL matching criteria for the rule.
• target: The specific endpoint key to forward traffic to.

Middleware and High Availability

Advanced deployment scenarios often require request interception and high availability. The following example demonstrates enabling API key authentication and load balancing across multiple upstream instances.

middleware:
  api_key_filter:
    type: "api_key"
    options:
      header_name: "X-API-KEY"
      keys:
        - "client-secret-123"

endpoints:
  order_api:
    locations:
      - "http://order-node-1.svc.local"
      - "http://order-node-2.svc.local"
    strategy: "round_robin"
    prefix: "/v1/orders"

rules:
  - pattern: "/v1/orders/*"
    target: order_api
    plugins:
      - api_key_filter

Observability and Logging

To maintain visibility into gateway performance and traffic, configure the logging and metrics modules. This setup enables JSON-formatted logs and exposes a Prometheus-compatible metrics endpoint on port 9090.

observability:
  logging:
    level: "debug"
    format: ""
  metrics:
    enabled: true
    port: 9090
    path: "/metrics"

endpoints:
  status_api:
    location: "http://status.svc.local"
    prefix: "/status"

rules:
  - pattern: "/status/*"
    target: status_api