.. _bootaction:

============
Boot Actions
============

Boot actions can be more accurately described as post-deployment file placement. This file placement
can be leveraged to install actions for servers to take after the permanent OS is installed
and the server is rebooted. Including custom or vendor scripts and a SystemD service to run the
scripts on first boot or on all boots allows almost any action to be configured.

Boot Action Schema
==================

Boot actions are configured via YAML documents included in the site topology definition. The schema
for these YAML documents is described below.

.. code-block:: yaml

  data:
    signaling: true
    assets:
      - path: /save/file/here
        location: http://get.data.here/data
        type: unit|file|pkg_list
        data: |
          inline data here
        location_pipeline:
          - template
        data_pipeline
          - base64_decode
          - template
          - base64_encode
        permissions: 555
    node_filter:
      ...


``signaling`` is a boolean noting whether Drydock should expect a signal at the completion
of this boot action. If set to ``true`` for a boot action that does not send a signal, it
will elongate the deployment step and consider the boot action failed.

``assets`` is a list of data assets. More details below on how each data asset is rendered.

``node_filter`` is an optional filter for selecting to which nodes this boot action will apply.
If no node filter is included, all nodes will receive the boot action. Otherwise it will be
only the nodes that match the logic of the filter set. See :ref:`task` for a definition of
the node filter.

Rendering Data Assets
=====================

The boot action framework supports assets of several types. ``type`` can be ``unit`` or ``file`` or ``pkg_list``.

    - ``unit`` is a SystemD unit, such as a service, that will be saved to ``path`` and enabled via ``systemctl enable [filename]``.
    - ``file`` is simply saved to the filesystem at ``path`` and set with ``permissions``.
    - ``pkg_list`` is a list of packages

Data assets of type ``unit`` or ``file`` will be rendered and saved as files on disk and assigned
the ``permissions`` as specified. The rendering process can follow a few different paths.

Referenced vs Inline Data
-------------------------

The asset contents can be sourced from either the in-document ``data`` field of the asset
mapping or dynamically generated by requesting them from a URL provided in ``location``.
Currently Drydock supports the schemes of ``http``, ``deckhand+http`` and
``promenade+http`` for referenced data.

Package List
------------

For the ``pkg_list`` type, the data section is expected to be a YAML mapping
with key: value pairs of ``package_name``: ``version`` where ``package_name`` is
a Debian package available in one of the configured repositories and ``version``
is a valid apt version specifier or a empty/null value. Null indicates no version
requirement.

If using a referenced data source for the package list, Drydock expects a YAML
or JSON document returned in the above format.

Pipelines
---------

The boot action framework supports pipelines to allow for some dynamic rendering. There
are separate pipelines for the ``location`` field to build the URL that referenced assets should
be sourced from and the ``data`` field (or the data sourced from resolving the ``location`` field).

The ``location`` string will be passed through the ``location_pipeline`` before it is queried. This response
or the ``data`` field will then be passed through the ``data_pipeline``. The data entity will start the pipeline
as a bytestring meaning if it is defined in the ``data`` field, it will first be encoded into a bytestring.
Below are pipeline segments available for use.

base64_decode
    Decode the data element from base64

base64_encode
    Encode the data element in base64

utf8_decode
    Decode the data element from bytes to UTF-8 string

utf8_encode
    Encode the data element from a UTF-8 string to bytes

template
    Treat the data element as a Jinja2 template and apply a node context to it. The defined context available
    to the template is below.

    - node.network.[network_name].ip - IP address of this node on network [network_name]
    - node.network.[network_name].cidr - CIDR of [network_name]
    - node.network.[network_name].dns_suffix - DNS suffix of [network_name]
    - node.hostname - Hostname of the node
    - node.domain - DNS Domain of the primary network on the node
    - node.tags - Sequence of tags assigned to this node
    - node.labels - Key, value pairs of both explicit and dynamic labels for this node
    - action.action_id - A ULID that uniquely identifies this boot action on this node. Can be used for signaling boot action result.
    - action.action_key - A random key in hex that authenticates API calls for signaling boot action result.
    - action.report_url - The URL that can be POSTed to for reporting boot action result.
    - action.design_ref - The design reference for the deployment that initiated the bootaction

    Also available in the Jinja2 template is the ``urlencode`` filter to encode a string for inclusion
    in a URL.

Reporting Results
=================

The assets put in place on a server can report the results of applying the boot action using the Drydock :ref:`bootaction-api`. The
report API URL and boot action key are both available via the ``template`` pipeline segment context. It is up to the boot action
assets to implement the call back to the API for reporting whatever data the boot action desires.