RouteGroup 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.
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 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:
| 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
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`