Skip to main content

RouteGroup Specification


A RouteGroup is an entity used to specify routing in relation with sandboxes and sandboxed workloads. You specify a match criteria based on labels to include specific Sandboxes dynamically. You optionally specify one or more endpoints associated with a RouteGroup. API requests to the endpoints are routed to the forked workloads in all the Sandboxes that match the criteria in the RouteGroup.

The specification can be expressed in json or yaml formats, as structured data, for example:

name: my-routegroup
cluster: my-cluster
description: "route group for testing multiple sandboxes together"
- label:
key: feature
value: new-feature-x-*
- name: frontend-endpoint
target: http://frontend.hotrod.svc:8080

Global constraints

The names of endpoints must be unique across the specification.

Update constraints

A routegroup may be updated. Only some fields are mutable, the rest are immutable. In addition, some constraints apply.

The field spec.match may be arbitrarily modified.

The field spec.endpoints may be modified arbitrarily. As this field is of type array, that means that one can add or remove or change endpoints.

No other field may be modified. In particular, as the name of a routegroup acts as an identifier, one cannot rename a routegroup.


The name is a string used to identify the routegroup. The name must be unique amongst all routegroups associated with the Signadot organisation.

A name must match the regular expression ^[a-zA-Z]([a-zA-Z0-9-]*[a-zA-Z0-9])?$ and be no longer than 30 bytes in length.

The name is required and immutable.



The cluster associated with a routegroup is a string which identifies a cluster registered with Signadot by name. The cluster should have the Signadot Operator installed. The cluster name should not exceed 255 bytes in length.

cluster is required and immutable.


The routegroup description is an optional string providing a short summary of what the routegroup is used for. The description must not exceed 255 bytes. The routegroup description is immutable.


The routegroup match section specifies the criteria to match Sandboxes in the same cluster as the routegroup based on label values.

Exactly one of label, any or all must be specified.


A Label match contains a key field and a value field and matches sandboxes which contain a label with the same key as that specified in the key field and whose value matches the glob specified in the value field (see glob.

key: feature
value: new-feature-x-*


This field allows specifying a list of label matches conditions such as:

- label:
key: feature
value: new-feature-x-*

any is the boolean "OR" operation. If one or more of the listed criteria match a sandbox, it will be added to the specified routegroup.


- label:
key: feature
value: new-feature-x-*

all is the boolean "AND" operation. If every one of the listed criteria match a particular sandbox, it will be added to the specified routegroup.


The endpoints section specifies an array of targets that are URLs accessible from the Kubernetes cluster. Corresponding to each endpoint, a hosted preview URL will be returned that allows sending requests to that target with the correct routing context set. The target supports the following values:

Schemehttp, https, grpcProtocol used by the target address
Hostmy-svc.default.svcDNS name that is resolvable from within the cluster
Port8080Port to access on the above host

The following DNS formats are commonly used for the Host part of the target URL.

Kubernetes Internal DNSkubernetes.default.svc
Ingress / Public

Regardless of targets specified, the routing key associated with the routegroup is returned once it is created. This routing key can be used for routing to the sandboxed workloads by injecting the routing key header on requests manually.



TTL was introduced in version v0.7.0 of the cli and sdks. Using earlier versions of these tools can drop the ttl field from the spec.

ttl is a field placing a lifetime time limit on a Route Group. It is an object with 2 keys, duration and offsetFrom:

duration: 1d
offsetFrom: noMatchedSandboxes # Supported values: `noMatchedSandboxes` (default), `createdAt`, `updatedAt`