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.

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

cfg

Configure devices using Nornir execution module nr.cfg function

task

Interact with devices using nr.task Execution Module function.

workflow

Executes work flow steps using any SaltStack Execution modules functions

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 jinja

  • 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

task

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

Interact with devices using nr.task Execution Module function.

Parameters
  • pluginpath.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

workflow

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

State function to execute work flow steps using SALT 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

  • 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).

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

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.

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": "*"}
    # 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