Groups

A group is a named handle for one or more instances. Instead of referencing individual container or service names, your reverse proxy references a group, and a session for that group starts every instance in it.

Why groups exist

• Decouple your proxy from workload names. The proxy route names a group, not a container. You can rename, replace or scale the underlying workload without touching your proxy configuration.
• Start related workloads together. Put an app and the database it needs in the same group, and a single request warms both at once.
• Target many instances at once. A group can contain any number of instances; one session request starts them all.

Assigning a group

Set the sablier.group label on the instance:

services:
  whoami:
    image: acouvreur/whoami:v1.10.2
    labels:
      - "sablier.enable=true"
      - "sablier.group=demo"

The label lives wherever your provider keeps labels. See Configuring instances for the per-provider syntax (Kubernetes annotations, Proxmox sablier-group-<name> tags, and so on).

Targeting a group from the reverse proxy

Your reverse-proxy plugin names the group to start for a given route. For example, with Caddy:

route /whoami {
    sablier http://sablier:10000 {
        group demo
        session_duration 1m
    }
    reverse_proxy whoami:80
}

When a request hits /whoami, Sablier starts the demo group and waits according to the configured strategy before letting the request through. Each reverse proxy expresses this differently; see Reverse proxies.

One instance, several groups

An instance can belong to more than one group at the same time; a session for any of them starts it. This is useful for shared dependencies. See Instance groups for the rules and per-provider examples.

Groups and sessions

A session is created when a group is requested and is kept alive by ongoing traffic. When it expires after the inactivity window, every instance in the group is stopped. The Glossary has the precise definitions of session and group.