Groups and overlays

TL;DR

Flow groups

A group draws a frame around nodes and nested groups. It is written group <id> "Name" type=<type> provider=<provider> sub="10.0.0.0/16" {, then its nodes, then } on its own line. type= says what the group is, from the closed list on the group types page; the type gives the group an icon, a tone, and a frame style, and a group nested inside another is shaded one step stronger than the one around it, in light and in dark. icon= and tone= are optional overrides. The frame carries a corner tab in its top-left corner, which holds the group's icon and its name on one line. The tab grows to fit the name with the same padding on both sides, and a name longer than the widest node card is cut with an ellipsis and warning W203. sub= adds a short second line under the name, such as a network address, and stack= puts up to three small marks under that, such as a lock for a network rule or a technology logo. The tab grows to hold both and never covers its own icon. A group with no type= whose name gives its type for certain takes it: a name that is or ends with VPC, Network, Subnet, Kafka, Queue, Event bus, Kubernetes, Region, AWS account, Data, Security, IAM, or Monitoring, a name that is exactly Production, Staging, Dev, Pipeline or Cluster, or a region code such as us-east-1 or westeurope. "Data science team" and "Data pipeline" stay plain. type=none keeps a group plain, and icons=off on the header turns this off. A group with no type and no icon shows only its name. icon=none removes any icon. An edge that passes under a tab goes behind it.

PictureSourceOutline

Overlays

An overlay draws a dashed frame around nodes or groups it does not own, wherever layout put them: a scaling group that spans two zones, or a redundant set of machines inside a tier. It is one line, overlay <id> "Name" members=<id>,<id>, written after the members, and it takes the same look options as a group: type, provider, icon, tone, sub, stack. A dashed frame around nodes or groups it does not own, wherever layout puts them: a scaling group across two zones, or a redundant set inside a tier. Write it after the members, one line: overlay id "Name" members=a,b type=scale-group. Use a group when the frame should own what is inside it.

• When every member sits in one group, the overlay is laid out as a frame of its own, so layout leaves room for its edge and tab and nothing can fall inside by accident.
• When members sit in different groups, nothing moves: the frame is drawn around them after layout, above the group frames it crosses and below the edges and nodes. Its tab never touches a group tab, another overlay tab, a node, or an edge label: it slides along the top edge to a free stretch, and when there is none the frame grows by the same amount on every side until the tab clears them.
• A frame that would also surround a node that is not a member is warning W206, with the three fixes: add the node to members=, put the members in one group one after another, or split the overlay in two.
• A member must exist (E137), be listed once, not be an overlay, not sit inside another member (E138), and belong to no other overlay (E139).
• Edges connect nodes, never an overlay or a group.

PictureSourceOutline

See also