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.
| Step | What the controller does |
|---|---|
| Validate | Checks block types, names, links, port types, required inputs, values and cycles. A single error makes the diagram Invalid, and nothing is changed. |
| Evaluate | Computes values in the order of the links. A block that needs another block's output waits until that object has reported it. |
| Realize | Each resource block becomes an object named after the block and labelled with the diagram. The diagram owns the fields it sets. |
| Clean up | A labelled object with no matching block is deleted, dependents first. With deletePolicy: Orphan it is released instead and lives on. |
| Report | Each 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
| Property | Value |
|---|---|
| Size | Up to 500 blocks and 2 000 links in a diagram. |
| Links | A link is valid only if the output type matches the input type. Bad values make the diagram Invalid, with the port named. |
| Names | A block's name is a DNS label and becomes the name of its object, so it is unique per kind in the project. |
| Rights | A diagram cannot do more than its author could do directly. The author needs rights on every kind it creates. |
| Modules | Modules 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. |
| Coverage | Blocks cover Network objects and a few other kinds. Billing, projects and IAM have no blocks. |
| Secrets | No port carries a password, token or key. |
| Monitor | Read-only, refreshed every 3 seconds. |
| Editing | Saving detects a change someone else made since you opened the diagram. There is no shared live editing. |
When something goes wrong
| What happens | What you see |
|---|---|
| The diagram does not validate | It becomes Invalid, with the block and port named. Nothing is changed. |
| The API refuses a change | A 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 use | An object of that name that the diagram did not create is never adopted. The block reports NameInUse. |
| A block, or the whole diagram, is removed | The 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.