Environment variables in Normir Automation offer a robust mechanism to override defaults and inject context-specific details, such as environment selection, inventory location, and debug output, without editing configuration files. This is especially useful in CI/CD pipelines, production deployments, or when handling sensitive information.

• NORMIR_ENV:
  Specifies which environment configuration to use (e.g., prod, staging, dev). This variable controls which set of variables and inventory files Normir loads during execution.
  Example: NORMIR_ENV=prod
• NORMIR_INVENTORY:
  Defines the path to a custom inventory file, allowing for flexible infrastructure targeting or on-the-fly testing without modifying source YAML.
  Example: NORMIR_INVENTORY=/etc/normir/hosts-custom.yml
• NORMIR_DEBUG:
  Enables or disables verbose debugging and diagnostics output. Useful for troubleshooting task failures, playbook logic, or configuration rendering.
  Example: NORMIR_DEBUG=true

To set an environment variable for a single Normir session, use the following command pattern:

export NORMIR_ENV=prod
normir apply -t base_network

These environment variables are read at runtime and can greatly enhance operational flexibility by allowing quick adjustments without code changes.

Normir Automation uses a modular, role-based structure to organize configuration logic, making it scalable and easy to reuse across multiple infrastructure components such as routers, switches, firewalls, or generic templates. Each role encapsulates the configuration logic, templates, defaults, and task execution steps related to a specific device type or function.

Typical folder hierarchy for a role:

roles/
└── cisco-ios/
    ├── defaults/
    │   └── main.yml
    ├── vars/
    │   └── main.yml
    ├── tasks/
    │   └── main.yml
    └── templates/
        └── config.j2

• defaults/main.yml
  Contains the lowest precedence default variables. These are safely overridden by more specific variables in host_vars or group_vars.
• vars/main.yml
  Stores high precedence static values such as vendor-specific constants or hardcoded parameters related to the role.
• tasks/main.yml
  This is the execution entrypoint for the role. It defines a list of tasks to be performed — like generating a configuration, applying it over SSH/NETCONF/REST, or validating outcomes.
• templates/config.j2
  Houses Jinja2 templates used to render the final configuration text that gets applied to the target device. Templating supports dynamic variable substitution.

Sample usage in a playbook:

- name: Configure core router
  hosts: core_routers
  roles:
    - cisco-ios

This modular abstraction enables infrastructure teams to define consistent logic for each vendor or device type without duplicating tasks or templates. It also simplifies testing and CI/CD pipelines by allowing isolated testing per role.

In complex automation environments, the same variable might exist in several places. Normir Automation follows a strict precedence order to determine which variable value takes effect at runtime. Understanding this order ensures your configurations behave predictably and don't get overridden unintentionally.

Variable Precedence Order (Highest to Lowest):

1. Command-Line Defined Variables
   Variables passed with the -e or --extra-vars flag at runtime.
   Example: normir apply -e "env=prod"
2. Host Variables (host_vars/)
   Specific variables set per device hostname.
   Example: host_vars/router1.yml
3. Group Variables (group_vars/)
   Variables shared across inventory groups like cores or edge_switches.
4. Role Variables (vars/main.yml)
   Predefined within a role, typically for vendor constants or fixed options.
5. Role Defaults (defaults/main.yml)
   Low-priority defaults defined inside roles. Designed to be overridden by group or host variables.
6. Global Defaults (defaults.yml)
   Top-level user-defined defaults used across all roles and inventories.
7. Built-in System Defaults
   Hardcoded defaults defined by Normir’s processing engine.

Variables defined higher up in this list will override those below. This order allows flexibility in defining general behavior while still enabling fine-tuned control over specific hosts or conditions.

Tip: Prefer lower-precedence definitions (like role defaults) when you want to establish sane defaults without interfering with more specific configurations at the host or group level.

The inventory is a YAML-based file that defines the complete list of devices managed by Normir Automation. It’s structured into groups and hosts, allowing scalable configuration and role assignment across diverse infrastructures such as routers, switches, firewalls, and servers.

Basic Inventory Structure:

all:
  children:
    core_switches:
      hosts:
        switch1:
          ansible_host: 10.0.10.1
          role: cisco-ios
        switch2:
          ansible_host: 10.0.10.2
          role: cisco-ios
    edge_routers:
      hosts:
        router1:
          ansible_host: 192.168.1.1
          role: juniper-junos

• all:
  The top-level group containing all inventory groups and hosts.
• children:
  Nested groupings of related infrastructure (e.g., core_switches, edge_routers).
• hosts:
  Individual network devices, each defined by a hostname. Each host can include metadata like its IP address, assigned role, or custom tags.
• ansible_host:
  The actual IP or DNS address used by Normir or underlying execution engines (like Nornir or Ansible) to connect to the device.
• role:
  Assigns the appropriate automation logic to the device (e.g., cisco-ios, juniper-junos).

Advanced: Tagging and Metadata

        tags:
          - edge
          - primary
        site: san-antonio-dc
        os_version: 18.4R3

Tags and metadata fields provide additional classification and filtering capability. These attributes can be used in playbooks, templating logic, or role conditionals to drive dynamic behaviors.

Common Use Cases:

• Segmenting devices by data center or site.
• Defining platform-specific variables per group.
• Applying roles only to target sets using conditions.
• Mapping configurations across multi-vendor topologies.

Multiple inventories can be defined for different environments (e.g., inventory/prod.yml, inventory/lab.yml) and selected using the NORMIR_INVENTORY environment variable at runtime.

In Normir Automation, individual device configurations are defined using YAML under the host_vars/ directory. This per-device approach allows fine-grained customization for interfaces, routing protocols, SNMP, and other features specific to the device.

Sample file: host_vars/router1.yml

hostname: router1

interfaces:
  - name: GigabitEthernet0/0
    description: Uplink to Core Switch
    ip_address: 10.0.1.1/24

  - name: GigabitEthernet0/1
    description: Link to Branch
    ip_address: 10.0.2.1/24

routing:
  ospf:
    process_id: 1
    networks:
      - network: 10.0.1.0/24
        area: 0
      - network: 10.0.2.0/24
        area: 0

snmp:
  enabled: true
  community: noc123!ro

• hostname:
  Sets the router’s hostname in the final generated config.
• interfaces:
  Defines interface-level attributes like descriptions and IP addresses.
• routing:
  Contains dynamic routing configuration. In this example, OSPF is being configured with specific networks and areas.
• snmp:
  Enables SNMP and applies read-only community strings.

This device-level YAML feeds into templated configuration files via Jinja2 logic in each role. It ensures that configurations are rendered dynamically based on the parameters set per device. Each host can vary independently while still benefiting from shared logic within its associated role.

Normir Automation leverages Jinja2 templates to dynamically generate device configurations based on YAML variables defined in your inventory, role, or host files. This approach enables powerful reuse, custom logic, and conditional configuration, making your automation both flexible and maintainable.

Basic Jinja2 Syntax Example:

hostname {{ hostname }}

{% for iface in interfaces %}
interface {{ iface.name }}
 description {{ iface.description }}
 ip address {{ iface.ip_address }}
{% endfor %}

• {{ variable }}: Inserts the value of a variable from your YAML configuration.
• {% for ... %} ... {% endfor %}: Loops over a list (such as interfaces) to generate repeated config blocks.
• {% if ... %} ... {% endif %}: Adds configuration lines conditionally, only if a variable or expression evaluates to true.
• Filters:
  - {{ var | default('unset') }} — Use a fallback value if var is not defined.
  - {{ hostname | upper }} — Converts hostname to uppercase letters.
  - {{ list | join(', ') }} — Joins a list into a single comma-separated string.

Advanced Example: Optional SNMP Block

{% if snmp.enabled %}
snmp-server community {{ snmp.community }} RO
{% endif %}

Jinja2 templates live inside a role’s templates/ directory (e.g., roles/cisco-ios/templates/config.j2). During automation runs, Normir combines your device’s YAML variables with these templates to render complete, device-ready configs tailored to your topology.

By using Jinja2 logic in your templates, you can programmatically alter network device configurations based on variables, groups, or conditional facts—leading to robust, scalable automation for multi-vendor environments.

Normir Automation delivers cross-vendor support through modular roles and templates tailored to the most widely deployed network operating systems. This multivendor capability allows you to automate configuration and compliance checks across diverse infrastructures — from data centers to branch offices — using a single automation platform.

Current Supported Platforms:

As vendor support expands, new roles can be contributed by users or added from the community, enabling future-proof automation and simplified onboarding of additional plataformas and devices. Each supported system includes best-practice templates, task logic, and variable structures designed to abstract away device specifics so you can focus on intent, not syntax.

• Multi-vendor roles allow consistent deployment patterns across your stack.
• OS version minimums ensure access to necessary API or configuration features.
• Custom roles can be developed for platforms beyond this list by following Normir’s role framework.

Check the official Normir documentation or your community repo for the latest compatibility charts, release notes, and platform additions.

Even with robust automation, issues can arise during configuration management. Normir Automation provides clear troubleshooting strategies to quickly resolve common problems and maintain smooth deployments.

Typical Symptoms and Solutions:

• Enable debugging: Set NORMIR_DEBUG=true to display more detailed logs and quickly pinpoint where errors are occurring in the workflow.
• Validate configurations offline: Test Jinja2 templates and YAML files locally before pushing changes to production devices.
• Leverage dry runs: Use dry run or check modes to preview changes and catch issues without affecting live infrastructure.
• Check environment variables: Confirm NORMIR_ENV and NORMIR_INVENTORY are properly set to avoid applying settings to the wrong environment.

For persistent or complex issues, consult error logs output by Normir and review documentation for best practices on structuring roles, inventories, and variables.

Normir Automation can be seamlessly integrated with a wide range of external systems to extend its capability, create automation workflows, and enhance network management through orchestration, monitoring, and continuous delivery.

Commonly Supported Integrations:

• NetBox: Acts as a source of truth for inventory, device metadata, and IP management. Normir can dynamically pull inventory or update device state from NetBox APIs for always-accurate automation.
• Nornir: Used as an execution backend, enabling parallel tasking, inventory management, and plugin extensibility for custom workflow steps.
• Ansible Tower / AWX: Optional integration for organizations standardizing on Ansible Tower or AWX as their automation orchestration platform. This allows scheduling, RBAC, and workflow chaining within enterprise gates.
• Prometheus & Grafana: Metrics can be exported for visualization and alerting. Track automation run statuses, device reachability, configuration drift, or network health indicators over time.
• CI/CD Pipelines (GitLab, Jenkins, etc.): Integrate Normir tasks as jobs in CI/CD pipelines, enabling automated testing, configuration validation, and zero-touch deployments with every commit or merge.

Integration Workflow Example:

1. Source Control: Store configurations and playbooks in a git repository (GitLab, GitHub).
2. CI/CD Trigger: On push or merge, the CI pipeline kicks off and invokes Normir to lint, validate, and render device configs.
3. NetBox Sync: Latest device and site metadata is pulled from NetBox to drive inventory and templating logic.
4. Automation Run: Nornir or Ansible applies configurations across the infrastructure based on validated data.
5. Monitoring: Automation outcomes, logs, and metrics can be sent to Prometheus/Grafana dashboards for real-time visibility and alerting.

Integrating with these systems not only boosts operational efficiency but also ensures consistency, visibility, and auditability of your network automation efforts. Normir’s open architecture allows new plugins and connectors to be added as requirements evolve.