Skip to main content

Gateway API Route Customization (Alpha)

Alpha Feature

Route customization is an alpha feature for operators and platform teams who need fine-grained control over how Signadot derives routes from baseline HTTPRoute and GRPCRoute resources. Most users do not need this capability. Standard Gateway API routing handles the common cases automatically.

Requires Operator v1.3.1+.

Overview​

When Signadot generates derived HTTPRoute or GRPCRoute resources for sandbox traffic, it uses sensible defaults. Some environments require customization of these generated routes — for example, adding custom headers, masking out fields from the baseline that should not be inherited, or attaching gateway-specific configuration. Route customization patches are specified via annotations on the baseline HTTPRoute or GRPCRoute, giving mesh and gateway owners control over how sandbox routes behave.

The patch can also be used to mask certain fields in the baseline route that you would like the operator to not incorporate into the Signadot derived routes.

Configuration​

The following annotation is supported on baseline HTTPRoute and GRPCRoute resources:

AnnotationFormat
gateway-api.signadot.com/json-patchJSON Patch array (RFC 6902)

JSON Patch Format​

The gateway-api.signadot.com/json-patch annotation accepts a JSON Patch array. Each operation specifies op, path, and value, and is applied to every Signadot-derived route rule:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: frontend-route
  namespace: hotrod
  annotations:
    gateway-api.signadot.com/json-patch: |
      [
        {"op": "add", "path": "/timeouts", "value": {"request": "30s"}}
      ]
spec:
  parentRefs:
  - name: my-gateway
    namespace: gateway-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: frontend
      port: 8080

The path field uses JSON Pointer syntax relative to a single rule of the derived route.

Examples​

The available fields depend on the route type — HTTPRoute and GRPCRoute rules have different schemas. For example, timeouts exists on HTTPRouteRule but not on GRPCRouteRule, so the timeout examples below apply only to HTTPRoute baselines.

Adding Request Headers​

gateway-api.signadot.com/json-patch: |
  [{"op": "add", "path": "/filters", "value": [
    {"type": "RequestHeaderModifier",
     "requestHeaderModifier": {"set": [{"name": "x-routed-by", "value": "signadot"}]}}
  ]}]

Setting Timeouts​

gateway-api.signadot.com/json-patch: |
  [{"op": "add", "path": "/timeouts", "value": {"request": "60s"}}]

Removing a Field from the Baseline​

gateway-api.signadot.com/json-patch: |
  [{"op": "remove", "path": "/timeouts"}]

Debugging​

To verify patches were applied, inspect the derived route:

kubectl get httproute -n hotrod -l signadot.com/baseline-route=frontend-route -o yaml

Signadot-derived routes carry the signadot.com/baseline-route label pointing back to the baseline route they were generated from.

Common issues:

  • JSON Patch path errors: Paths must exist or use appropriate operations (add for new fields, replace for existing).

Limitations​

  • Annotation values are subject to Kubernetes size limits (256KB total).
  • Patches apply equally to every rule of the derived route.