Specification

Overview

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
spec:
  cluster: my-cluster
  description: "route group for testing multiple sandboxes together"
  match:
    any:
    - label:
        key: feature
        value: new-feature-x-*
  endpoints:
  - 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.

name

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.

spec

spec.cluster

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 unless you have multi-cluster routegroups enabled. In this case, cluster may be omitted and the routegroup will match sandboxes in any cluster.

spec.description

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.

spec.match

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.

spec.match.label

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.

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

spec.match.any

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

  match:
    any:
    - 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.

spec.match.all

  match:
    all:
    - 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.

spec.endpoints

The endpoints section specifies an array of named targets that are URLs accessible from the Kubernetes cluster.

- name: my-endpoint
  target: http://my-svc.namespace.svc:8080

If you have multi-cluster routegroups enabled, you should also specify a cluster associated with each endpoint:

- name: my-endpoint
  target: http://my-svc.namespace.svc:8080
  cluster: staging

Each endpoint will cause a hosted preview URL to be served that allows sending requests to that target with the correct routing context set.

The target supports the following values:

Part	Values	Description
Scheme	http, https, grpc	Protocol used by the target address
Host	my-svc.default.svc	DNS name that is resolvable from within the cluster
Port	8080	Port to access on the above host

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

Target	Example
Kubernetes Internal DNS	kubernetes.default.svc
Ingress / Public URL	something.internal.com

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.

spec.ttl

note

TTL was introduced in version v0.7.0 of the cli. Using earlier versions 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:

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