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
Name |
Description |
---|---|
Configure devices using Nornir execution module |
|
Interact with devices using |
|
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) ornetmiko
orscrapli
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 bynetmiko
pluginSample 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 ifsumtable
is True. Ifsumtable
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 noFx
filters provided, state steps run without any filters, depending on proxynornir_filter_required
setting, steps might fail (ifnornir_filter_required
is True) or run for all hosts (ifnornir_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 optionsfilters
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 functionargs – (list)
*args
for Execution Module functionreport – (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 failedrun_if_pass_any – (list) this step will run if
any
of the previous steps in a list passedrun_if_fail_all – (list) this step will run if
all
of the previous steps in a list failedrun_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 asPASS
unconditionally.If function reference
nr.test
with test suite, each test suite test item added to summary report, in addition, step’s argumentsrun_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 andrun_if_x
conditions. If multiplerun_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 byfilters
provided in state global options and/or step**kwargs
.If
hcache
ordcache
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 anddefaults
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’shcache
ordcache
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 resultfailed
attribute is False orsuccess
attribute is TrueFAIL
- step failed, Nornir Execution Module task resultfailed
attribute is True orsuccess
attribute is FalseSKIP
- step skipped and not executed, usually due torun_if_x
conditions not met for the hostERROR
- 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 tojira
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 |