Diagrams

Draw your network, and a controller builds it.

If you would rather sketch a network than write it out as YAML, draw it. A Diagram is infrastructure drawn as blocks with typed ports, joined by arrows. Put down a VPC block, wire DNS and DHCP blocks to it, add an account for a laptop that should join, and save. A controller creates the objects the blocks stand for, and the same canvas then shows you the status of each one.

What a diagram is made of

A Diagram is a resource in your project. It holds blocks with typed ports, and links that run from an output port to an input port. A BlockType is one entry in the catalog of blocks. A controller validates the diagram, creates the object each resource block stands for, and writes each block's phase and output values into the diagram's status. You change the diagram, and the controller changes the objects to match.

Diagram

The drawing, stored as a resource. It holds blocks, links, modules and a paused switch.

kubectl get diagrams

BlockType

The catalog of blocks. It has VPCs, accounts, DNS and DHCP, plus values, arithmetic and conditions, and every authenticated user can read it.

kubectl get blocktypes

Canvas

The editor in the console. Drag blocks, draw arrows, undo, import and export, and see validation as you type.

Live monitor

The same canvas, read-only and refreshed every 3 seconds. Each block shows its state and each output shows its value.

Behind the canvas it is the same API as everything else, so a diagram can be exported and reviewed like any other file. The architecture page explains that API. There is more in the diagrams guide.

What happens when you save

The controller works through the same steps every time.

StepWhat the controller does
ValidateChecks block types, names, links, port types, required inputs, values and cycles. A single error makes the diagram Invalid, and nothing is changed.
EvaluateComputes values in the order of the links. A block that needs another block's output waits until that object has reported it.
RealizeEach resource block becomes an object named after the block and labelled with the diagram. The diagram owns the fields it sets.
Clean upA labelled object with no matching block is deleted, dependents first. With deletePolicy: Orphan it is released instead and lives on.
ReportEach block gets the phase of its object and its output values.

An input that is not linked takes a value typed into the block. If you want to see what a diagram would do before it does it, pause it. A paused diagram is validated and reports its plan, and changes nothing.

Who owns a field

The diagram owns every field it sets. If someone changes one of those fields on the object directly, the controller puts it back, and a field you remove from a block goes back to its default. We wanted one place to look for what a field should be. It does mean that a quick fix made with kubectl on a diagram-owned field will not stick, and that removing a block deletes its object unless the diagram uses Orphan.

Whose rights a diagram uses

The controller creates the objects, but it checks your rights, not its own. A diagram cannot do more than its author could do directly, so the author needs rights on every kind the diagram creates, changes or deletes. That is also why IAM has no blocks and why modules are not shared between diagrams. Either one would let a person change more than their rights allow.

Typed ports

A link only joins ports of the same type, so a bad value is caught when the diagram is validated, before anything changes. Where text has to become a number, or a value has to become text, you put a conversion block in between. It is a little more drawing, and in exchange a wrong type is reported against a named port before any object is touched.

Limits

PropertyValue
SizeUp to 500 blocks and 2 000 links in a diagram.
LinksA link is valid only if the output type matches the input type. Bad values make the diagram Invalid, with the port named.
NamesA block's name is a DNS label and becomes the name of its object, so it is unique per kind in the project.
RightsA diagram cannot do more than its author could do directly. The author needs rights on every kind it creates.
ModulesModules nest up to four levels and repeat with count or forEach. Up to 20 modules, 200 blocks per module, 100 instances per module block, and 1 000 blocks after expansion. A module belongs to one diagram; to use it in another, export it and import it there.
CoverageBlocks cover Network objects and a few other kinds. Billing, projects and IAM have no blocks.
SecretsNo port carries a password, token or key.
MonitorRead-only, refreshed every 3 seconds.
EditingSaving detects a change someone else made since you opened the diagram. There is no shared live editing.

When something goes wrong

What happensWhat you see
The diagram does not validateIt becomes Invalid, with the block and port named. Nothing is changed.
The API refuses a changeA field that cannot change, say, or an admission error. The block and the diagram become Failed with the API's message. The old object is left alone; rename the block to replace it. Conflicts and server errors are retried and shown as Pending.
A name is already in useAn object of that name that the diagram did not create is never adopted. The block reports NameInUse.
A block, or the whole diagram, is removedThe objects it created are deleted, dependents first. With deletePolicy: Orphan they are released and live on.

The canvas is in the console, and the quickstart is the place to begin. Send us a sketch of the network you have in mind.

Request access