Skip to main content

Rules

Rules define how external traffic reaches your services. Each rule maps hostnames and a path to a target service, creating Kubernetes ingress resources under the hood.

Basic Routing​

A rule needs a service to target, at least one hostname, and a path:

services:
  - name: web
    image: nginx:1.27-alpine
    ports:
      - containerPort: 80

rules:
  - service: web
    hostnames:
      - myapp.example.com
    path: /

The service field must match the name of a service defined in your config, and that service must expose at least one port.

Multiple Routes​

Route different paths to different services:

rules:
  - service: api
    hostnames:
      - myapp.example.com
    path: /api
  - service: web
    hostnames:
      - myapp.example.com
    path: /

A service can also be reached on multiple hostnames:

rules:
  - service: api
    hostnames:
      - api.example.com
      - api-internal.example.com
    path: /

Visibility​

Control which ingress class handles the rule. This determines whether the service is reachable only within the cluster or publicly:

rules:
  - service: api
    hostnames:
      - api.example.com
    path: /
    visibility: nginx-internal

The ingress class defaults to nginx-internal when not specified.

Available Ingress Classes​

Ingress ClassVisibilityDescription
nginx-internalInternalInternal traffic
nginx-publicExternalPublic traffic
warning

Exposing traffic publicly carries significant security risks and requires additional networking changes. If you need to expose your environment publicly, contact the platform tools team in #proj-ephemeral-environments.

Read Timeout​

Set the upstream read timeout (in seconds) for requests routed through this rule:

rules:
  - service: api
    hostnames:
      - api.example.com
    path: /
    read_timeout: 30

Defaults to 59 seconds. Increase this for long-running requests like file uploads or report generation.

warning

Increasing this value beyond 60 seconds can lead to deployment failures. Only do so if you know what you are doing.

Annotations​

Pass custom annotations to the generated ingress resource:

rules:
  - service: api
    hostnames:
      - api.example.com
    path: /
    annotations:
      nginx.ingress.kubernetes.io/proxy-body-size: '50m'

Schema Reference​

See the Rule schema for the full configuration reference.