Build
=====

The build tool can be used to clone out pods from a manifest. The manifest is a
`toml <https://toml.io>`_ file, that will be further explained below. Simply create
a toml file and run `netlab build my_manifest_file.toml` to run it.

The build tool can be used to:

- Clone out pods.
- Delete pods.
- Rebuild pods.
- Bring pods online or take them offline.

Builder files can have any number of `[[range]]` blocks. This is the minimal
example.

.. literalinclude:: includes/quickstart.toml

`[range.pc_clone_specs]` can take keys found in :py:class:`netlab.datatypes.PCCloneSpec`

.. literalinclude:: includes/clone-specs.toml

This is an advanced example.

.. literalinclude:: includes/advanced.toml

Running this manifest will result in this output:

.. code-block:: shell

  $ netlab build var/baz.toml
  Fetching pods ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
  var/baz.toml#0
     SUPERSEDED pod-A.H85.P1400.v2
     SUPERSEDED pod-B.H85.P1401.v2
     SUPERSEDED pod-A.H85.P1402.v2
     SUPERSEDED pod-B.H85.P1403.v2
     SUPERSEDED pod-A.H85.P1404.v2
     SUPERSEDED pod-B.H85.P1405.v2
     SUPERSEDED pod-A.H85.P1406.v2
     SUPERSEDED pod-B.H85.P1407.v2
     SUPERSEDED pod-A.H85.P1408.v2
     SUPERSEDED pod-B.H85.P1409.v2
     SUPERSEDED pod-A.H85.P1410.v2
     SUPERSEDED pod-B.H85.P1411.v2
     SUPERSEDED pod-A.H85.P1412.v2
     SUPERSEDED pod-B.H85.P1413.v2
     SUPERSEDED pod-A.H85.P1414.v2
     SUPERSEDED pod-B.H85.P1415.v2
     SUPERSEDED pod-A.H85.P1416.v2
     SUPERSEDED pod-B.H85.P1417.v2
     SUPERSEDED pod-A.H85.P1418.v2
     SUPERSEDED pod-B.H85.P1419.v2
  var/baz.toml#1
     CREATE pod-A.H85.P1400.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1402.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1404.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1406.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1408.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1410.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1412.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1414.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1416.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-A.H85.P1418.v2
             [state]    ABSENT -> EXISTS
  var/baz.toml#2
     CREATE pod-B.H85.P1401.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1403.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1405.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1407.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1409.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1411.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1413.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1415.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1417.v2
             [state]    ABSENT -> EXISTS
     CREATE pod-B.H85.P1419.v2
             [state]    ABSENT -> EXISTS
  Continue? [y/N]:


Using clone_name_template
-------------------------

`clone_name_template` allows for more customization of the names of cloned pods.
Variables inside curly braces will be replaced. These variables are allowed:

pod_id
  The id of the created pod.

pod_role
  The abbreviated role of the created pod.

vh_name
  The abbreviated name of the virtual host of the created pod.

pt_org
  The org name of the pod type.

pt_apdid
  The author pod designer id of the pod type.

default
  The default generated name of the created pod.