Nornir Automation Framework

Nornir is a pure Python automation framework designed to be used directly within Python scripts. Unlike frameworks that rely on a Domain Specific Language (DSL), Nornir provides full control through standard Python code.

Key Benefits:

• Direct Python Control: Use all standard Python features, libraries, and logic.
• Ease of Troubleshooting: Since the framework is pure Python, you can use standard debugging tools like pdb directly within your automation scripts.
• Inventory & Dispatch Management: Nornir handles the complexities of managing device inventories and dispatching tasks across nodes.

The inventory plugin system has undergone significant changes in Nornir 2.x:

• Base Class: The new base class is nornir.core.deserializer.inventory.Inventory.
• Pydantic Integration: Plugins are now based on Pydantic. Consequently, plugin instances do not allow arbitrary class members. If your plugin needs to maintain state during initialization, you may need to refactor it.

For implementation references, you can examine the SimpleInventory, NetboxInventory, or AnsibleInventory plugins included with Nornir.

Nornir 3 is a pluggable system where certain components must be registered to be recognized. The types of plugins that require registration include:

• Inventory plugins: Create Inventory objects from external sources.
• Transform functions: Manipulate inventory data (e.g., extending data via secret stores) independently of the inventory plugin. These are called in a loop for each host during inventory initialization.
• Connection plugins: Manage connections with devices.
• Runners: Dictate how tasks are executed over hosts.
• Processors: Tap into specific events to execute arbitrary code.

You can register plugins using entry points in your build configuration or programmatically in your Python code.

Nornir configuration is composed of sections and parameters. You can define these settings using three different methods. If multiple methods are used, Nornir follows a specific order of precedence (from lowest to highest priority):

1. Environment Variables: Lowest priority.
2. YAML Configuration File: Medium priority.
3. Programmatic Code: Highest priority (overrides others).

You can use any combination of these methods to build your final configuration object.

Nornir parallelizes task execution using a thread-per-host model. You control the level of parallelization via the num_workers parameter in the nornir.core.Nornir.run method.

• Parallel Execution: Set num_workers > 1 (the default is 20). Nornir will spawn a different thread for each host to run the task.
• Serial Execution: Set num_workers = 1. Nornir will run the task over all hosts one after another in a simple loop. This mode is recommended for debugging, troubleshooting, or when performing operations that require sequential access, such as writing to a single file or database, or printing to the screen.

Because Nornir uses pure Python instead of a custom configuration language, you gain several advantages:

1. Extensibility: You are not limited by the features of a specific configuration language; you can use any Python library or logic.
2. Troubleshooting: You can debug your automation scripts using standard Python debugging tools and practices, which is often more difficult when using specialized configuration languages.
3. Consistency: Your automation logic follows the same patterns and debugging workflows as the rest of your Python codebase.

Nornir allows you to nest tasks within other tasks. This creates a hybrid execution model that gives you control over the workflow logic:

1. Outer Tasks: Run in parallel across different hosts (based on num_workers).
2. Inner (Nested) Tasks: For any given host, the inner tasks run serially.

This pattern is useful for composing complex workflows where certain steps must happen in a specific order for a host, even while multiple hosts are being processed simultaneously. For example, you can group tasks to ensure a specific sequence:

• Step 1: Configure all hosts in parallel.
• Step 2: Run verification tests (sequentially per host).
• Step 3: Enable services (sequentially per host).

A transform function is a plugin used to manipulate inventory data independently of the primary inventory plugin. This is useful for injecting data from environment variables, secret stores, or other external sources.

Lifecycle: During inventory initialization, the transform function is called in a loop for every host in the inventory.

Arguments:

1. The first parameter is the host object.
2. Additional keyword arguments are provided via the config.inventory.transform_function_options dictionary.

When contributing code to the Nornir core:

• Discussion: Open a GitHub issue to discuss significant code changes before implementing them.
• Testing: Ensure all existing tests pass and add new tests for any code you write to prevent future regressions.

Starting with version 3.0.0, Nornir uses a plugin architecture where functionality is decoupled from the core framework. To use specific features (such as inventory loaders or task runners), you must install the corresponding plugin packages via pip.

You can find a list of community-maintained plugins in the official documentation.

When writing custom plugins for Nornir, follow these guidelines to ensure they are useful to the community:

• Genericity: Make plugins as generic as possible so they are not tied to a specific environment.
• Testability: Ensure the plugin can be unit tested automatically.