Variables
Declaring variables, computing them, and passing them to the designs a design uses.
Declaring variables
Every design has a variables mapping, {} when it takes none. Each entry is one of:
| Value | Means |
|---|---|
A mapping with a type, such as {type: int, min: 1} | A typed input: required unless it has a default, asked for in the form its type takes, and checked before anything plans. See Typed variables |
$USER | Required text, checked by nothing until a field uses it. The deploy page asks for it, and planning without it is refused |
$USER_OPTIONAL | Optional text. When you don't give it, every field that uses it is left out, as if its line weren't there |
A value, such as active or 42 | A default. The deploy page doesn't ask for it |
An expression, such as '{{ variables.site_name | slugify }}' | Computed when the design renders, from other variables |
A computed variable can use the same filters and arithmetic as a field. See Expressions and loops.
Typed variables
A variable can say what it is. Declare it as a mapping with a type, and what you enter is checked when you deploy, before anything plans, in the variable's own terms: "Variable 'spine_count' is 'forty', not a whole number." The deploy page asks for each typed variable in the right form and shows its description.
variables:
spine_count: {type: int, min: 1, max: 32, default: 2, description: Spine switches in the pod}
supernet: {type: cidr, description: The site's supernet, such as 10.20.0.0/16}
redundancy: {type: string, choices: [n+1, 2n], default: n+1}
fast_start: {type: bool, default: false}
status: {type: netbox_field, model: Rack, field: status, default: active}
rack_name: {type: netbox_new, model: Rack, field: name}
site: {type: netbox_ref, model: Site, filter: {status: active}}| Type | The value is | Takes |
|---|---|---|
string | Text | choices: the values it may be |
int | A whole number; "8" typed in a form is 8 | min, max |
bool | true or false; yes, no, on, off, 1 and 0 are read as such | |
cidr | An IP prefix, such as 10.0.0.0/24 or 2001:db8::/32 | |
netbox_field | A value of a NetBox field, checked against what that field takes in your NetBox's version: a status's choices, a number's range | model, field |
netbox_new | The identifier of an object the design creates, checked against the field's length and pattern: a slug that is one, a name that fits | model, field |
netbox_ref | A selection of an object your NetBox already has, as a mapping of identifying fields ({slug: riga-dc}) or its name. filter narrows what the deploy page offers | model, filter |
Every declaration may carry required, default and description. A declaration with no default is required; with one, the deploy may leave it out. model is the object type as infra_type names it: Site, Rack, Device.
Once a target NetBox is chosen, the deploy page offers what that NetBox has: for a netbox_ref, a list of its objects of the model, by name, narrowed by the filter (a rack's list says its site beside the name, so two racks of a name can be told apart); for a netbox_field, the values the field takes in that NetBox's version. A list of more than five hundred is typed into, with the first five hundred suggested. Until the target has answered, or when it cannot, the variable is typed as text.
What a NetBox field takes is read from your NetBox's own data model, not written in the design: a design never lists a status's choices or a slug's rule, so it needs no change when NetBox's do. A status is one NetBox lets an administrator extend; netbox_field checks against the choices Designs knows, so a design that must take a custom choice declares that variable string.
A mapping with a type that isn't one of the seven is a default value that happens to be a mapping (an interface's {type: 1000base-t, mode: access}), unless it also carries a key only a declaration has, such as required or model, in which case the type is refused as unknown.
Using variables
{{ variables.<name> }} is the variable's value. An expression that names a variable the design doesn't declare refuses the render, naming the object and field.
Passing variables to the designs you use
An item with design: nbd:<catalogue name> includes another design. Its template_vars mapping sets that design's variables:
devices:
- design: nbd:devices/Dell_R640_w_module
template_vars:
name: '{{ variables.rack_name }}-COMPUTE-01'
position: 1
site: '{{ parent.site }}'
rack: '{{ parent }}'- Each value is worked out in the including design:
variables,parentandloopare the including design's. - The included design's required variables must all be given, and its optional ones may be.
- Its defaults apply to whatever
template_varsleaves out, and its computed variables are worked out for each inclusion, so ten included servers each compute their own. - Values pass one level down. A design two levels down gets only what the design that includes it passes on.