Nornir State Module

Nornir State module reference.

Introduction

This state module uses Nornir proxy execution module to apply configuration to devices.

Warning

This module does not implement idempotent behavior, it is up to Nornir task plugin to handle idempotency or up to user to define work flow steps to achieve desired level of idempotency.

Example

Example using nr.cfg and nr.task state module functions within SALT state.

File salt://states/nr_state_test.sls content located on Master:

apply_logging_commands:
  nr.cfg:
    - commands:
      - logging host 1.1.1.1
      - logging host 2.2.2.2
    - plugin: netmiko

apply_ntp_cfg_from_file:
  nr.cfg:
    - filename: "salt://templates/nr_state_test_ntp.j2"
    - plugin: netmiko

use_task_to_save_config:
  nr.task:
    - plugin: "nornir_netmiko.tasks.netmiko_save_config"

use_task_to_configure_logging:
  nr.task:
    - plugin: "nornir_netmiko.tasks.netmiko_send_config"
    - config_commands: "logging host 3.3.3.3"

File salt://templates/nr_state_test_ntp.j2 content located on Master:

{%- if host.platform|lower == 'ios' %}
ntp server 1.1.1.1
{%- elif host.platform|lower == 'cisco_xr' %}
ntp peer 1.1.1.1
{%- endif %}

Apply state running command on master:

salt nr_minion_id state.apply nr_state_test

Nornir State Module Functions

State Functions Summary
Name	Description
nr.cfg	Configure devices using Nornir execution module `nr.cfg` function
nr.task	Interact with devices using `nr.task` Execution Module function.
nr.workflow	Executes work flow steps using any SaltStack Execution modules functions

nr.cfg

salt_nornir.states.nornir_proxy_state_module.cfg(*args, **kwargs)

Configure devices using Nornir execution module nr.cfg function.

Parameters

commands – list of commands to send to device
filename – path to file with configuration
template_engine – template engine to render configuration, default is jinja2
saltenv – name of SALT environment
context – Overrides default context variables passed to the template.
defaults – Default context passed to the template.
plugin – name of configuration task plugin to use - napalm (default) or netmiko or scrapli
dry_run – boolean, default False, controls whether to apply changes to device or simulate them
Fx – filters to filter hosts
add_details – boolean, to include details in result or not

Warning

dry_run not supported by netmiko plugin

Sample Usage

File salt://states/nr_state_logging_cfg.sls content located on Master:

apply_logging_commands:
  nr.cfg:
    - commands:
      - logging host 1.1.1.1
      - logging host 2.2.2.2
    - plugin: netmiko
    - FB: "*"

Apply state:

salt nr_minion_id state.apply nr_state_logging_cfg

nr.task

salt_nornir.states.nornir_proxy_state_module.task(*args, **kwargs)

Interact with devices using nr.task Execution Module function.

Parameters

plugin – path.to.plugin.task_fun to use, should form valid python import statement - from path.to.plugin import task_fun
Fx – filters to filter hosts
add_details – boolean, to include details in result or not
args – arguments to pass on to task plugin
kwargs – keyword arguments to pass on to task plugin

Sample Usage

File salt://states/nr_state_ntp_cfg.sls content located on Master:

use_task_to_configure_logging:
  nr.task:
    - plugin: "nornir_netmiko.tasks.netmiko_send_config"
    - config_commands: "ntp server 1.1.1.1"

Apply state:

salt nr_minion_id state.apply  nr_state_ntp_cfg

nr.workflow

salt_nornir.states.nornir_proxy_state_module.workflow(*args, **kwargs)

State function to execute work flow steps using SatlStack Execution modules functions.

State Global Options

State Global Options defined under options key.

Parameters

report_all – (bool) if True (default) adds skipped steps in summary report
sumtable – (bool or str) default is False, if True uses text table for summary report, report_all always set to True if sumtable is True. If sumtable is string, it is must correspond to one of the python-tabulate module’s table format names e.g. grid, simple, jira, html
fail_if_any_host_fail_any_step – (list) steps to decide if state execution failed
fail_if_any_host_fail_all_step – (list) steps to decide if state execution failed
fail_if_all_host_fail_any_step – (list) steps to decide if state execution failed
fail_if_all_host_fail_all_step – (list) steps to decide if state execution failed
filters – (dict) set of Fx filters to apply for all steps, per-step filters have higher priority. If no Fx filters provided, state steps run without any filters, depending on proxy nornir_filter_required setting, steps might fail (if nornir_filter_required is True) or run for all hosts (if nornir_filter_required is False). If no hosts matched by filters, state execution stops with appropriate comment included in report.
hcache – (bool) if True (default) saves step’s per-host results in host’s data under step’s name key so that other steps can use it
dcache – (bool) if True (default) saves step’s full results in defaults data under step’s name key so that other steps can use it
kwargs – (dict) common arguments to merge with each step kwargs, step kwargs more specific and overwrite common kwargs

Warning

If proxy minion nornir_filter_required parameter set to True, workflow options filters must not be empty, but provided to limit overall execution scope.

Individual Step Arguments

Each step in a work flow can have a number of mandatory and optional attributes defined.

Parameters

name – (str) mandatory, name of this step
function – (str) mandatory, name of Nornir Execution Module function to run
kwargs – (dict) **kwargs for Execution Module function
args – (list) *args for Execution Module function
report – (bool) if True (default) adds step execution results in detailed report
run_if_fail_any – (list) this step will run if any of the previous steps in a list failed
run_if_pass_any – (list) this step will run if any of the previous steps in a list passed
run_if_fail_all – (list) this step will run if all of the previous steps in a list failed
run_if_pass_all – (list) this step will run if all of the previous steps in a list passed
stop_if_fail – (bool) Stop workflow execution for host if this step failed

While workflow steps can call any execution module function, run_if_x properly supported only for Nornir Execution Module functions: nr.task, nr.cli, nr.cfg_gen, nr.cfg, nr.test, nr.nc, nr.http, nr.do - for all other functions step considered as PASS unconditionally.

If function reference nr.test with test suite, each test suite test item added to summary report, in addition, step’s arguments run_if_x conditions must reference test suite individual tests’ names attribute.

Warning

if you use per host filename feature, e.g. filename="salt://path/to/{{ host.name }}.cfg" make sure to either disable state file jinja2 rendering using #!yaml shebang at the beginning of the state file or escape double curly braces in filename argument.

Execution of steps done on a per host basis, or, say better, each step determines a set of hosts it needs to run for using Fx filters and run_if_x conditions. If multiple run_if_x conditions specified, host must satisfy all of them - AND logic - for step to be executed for that host.

If no run_if_x conditions provided, step executed for all hosts matched by filters provided in state global options and/or step **kwargs.

If hcache or dcache set to True in State Global Options in that case for compatible Nornir Execution Module function each step results saved in Nornir in-memory Inventory host’s and defaults data under step’s name key. That way results become part of inventory and available for use by Nornir Execution Module function in other steps. Once workflow execution completed, cached results cleaned. Individual step’s hcache or dcache kwargs can be specified to save step’s results under certain key name, in such a case after workflow completed cache not removed for that particular step’s results.

Sample state salt://states/configure_ntp.sls:

main_workflow:
  nr.workflow:
    - options:
        fail_if_any_host_fail_any_step: []
        fail_if_any_host_fail_all_step: []
        fail_if_all_host_fail_any_step: []
        fail_if_all_host_fail_all_step: []
        report_all: False
        filters: {"FB": "*"}
        hcache: True
        dcache: False
        sumtable: False
        kwargs: {"event_progress": True}
    # define pre-check steps
    - pre_check:
        - name: pre_check_if_ntp_ip_is_configured_csr1kv
          function: nr.test
          kwargs: {"FB": "CSR*"}
          args: ["show run | inc ntp", "contains", "8.8.8.8"]
        - name: pre_check_if_ntp_ip_is_configured_xrv
          function: nr.test
          kwargs: {"FB": "XR*"}
          args: ["show run formal ntp", "contains", "8.8.8.8"]
    # here goes definition of change steps
    - change:
        - name: apply_ntp_ip_config
          function: nr.cfg
          args: ["ntp server 8.8.8.8"]
          kwargs: {"plugin": "netmiko"}
          run_if_fail_any: ["pre_check_if_ntp_ip_is_configured_csr1kv", "pre_check_if_ntp_ip_is_configured_xrv"]
          report: True
    # run post check steps
    - post_check:
        - name: check_new_config_applied_csr1kv
          function: nr.test
          args: ["show run | inc ntp", "contains", "8.8.8.8"]
          kwargs: {"FB": "CSR*"}
          run_if_pass_any: ["apply_ntp_ip_config"]
        - name: check_new_config_applied_xrv
          function: nr.test
          args: ["show run ntp", "contains", "8.8.8.8"]
          kwargs: {"FB": "XR*"}
          run_if_pass_any: ["apply_ntp_ip_config"]
    # execute rollback steps if required
    - rollback:
        - name: run_rollback_commands
          function: nr.cfg
          args: ["no ntp server 8.8.8.8"]
          kwargs: {"plugin": "netmiko"}
          run_if_fail_any: ["apply_ntp_ip_config", "check_new_config_applied_csr1kv", "check_new_config_applied_xrv"]

Sample usage:

salt nrp1 state.sls configure_ntp

Executing workflow returns detailed and summary reports. Detailed report contains run details for each step being executed. Summary report contains per-host brief report of all steps statuses, where status can be:

PASS - step passed, Nornir Execution Module task result failed attribute is False or success attribute is True
FAIL - step failed, Nornir Execution Module task result failed attribute is True or success attribute is False
SKIP - step skipped and not executed, usually due to run_if_x conditions not met for the host
ERROR - State Module encountered exception while running this step

Sample report:

nrp1:
----------
          ID: change_step_1
    Function: nr.workflow
      Result: True
     Comment:
     Started: 12:01:58.578925
    Duration: 5457.171 ms
     Changes:
              ----------
              details:
                  |_
                    ----------
                    apply_logging_config:
                        ----------
                        ceos1:
                            ----------
                            netmiko_send_config:
                                ----------
                                changed:
                                    True
                                connection_retry:
                                    0
                                diff:
                                exception:
                                    None
                                failed:
                                    False
                                result:
                                    configure terminal
                                    ceos1(config)#logging host 5.5.5.5
                                    ceos1(config)#end
                                    ceos1#
                                task_retry:
                                    0
                        ceos2:
                            ----------
                            netmiko_send_config:
                                ----------
                                changed:
                                    True
                                connection_retry:
                                    0
                                diff:
                                exception:
                                    None
                                failed:
                                    False
                                result:
                                    configure terminal
                                    ceos2(config)#logging host 5.5.5.5
                                    ceos2(config)#end
                                    ceos2#
                                task_retry:
                                    0
              summary:
                  ----------
                  ceos1:
                      |_
                        ----------
                        apply_logging_config:
                            PASS
                  ceos2:
                      |_
                        ----------
                        apply_logging_config:
                            PASS

If sumtable set to True in workflow’s options, summary report section formatted as text table:

summary:
    Headers:
    (1) collect_clock
    (2) collect_version
    (3) sleep_1_second
    (4) collect_clock

        host    1     2     3     4
    --  ------  ----  ----  ----  ----
     0  ceos1   PASS  PASS  PASS  PASS
     1  ceos2   PASS  PASS  PASS  PASS

Or, if sumtable value set to jira string:

summary:
    Headers:
    (1) collect_clock
    (2) collect_version
    (3) sleep_1_second
    (4) collect_clock

    ||    || host   || 1    || 2    || 3    || 4    ||
    |  0 | ceos1  | PASS | PASS | PASS | PASS |
    |  1 | ceos2  | PASS | PASS | PASS | PASS |