Understanding the Ansible for Junos OS Collections and Modules

Learn about the Ansible collections and modules that you can use to manage devices running Junos OS and devices running Junos OS Evolved.

Understanding Ansible Collections and Modules for Managing Junos Devices

Ansible is an IT automation framework that you can use for infrastructure configuration management. You use Ansible modules, which are discrete units of code, to perform specific functions on a managed node. You can execute individual modules on remote hosts to perform ad hoc tasks. You can also execute modules through playbooks.

Juniper Networks provides Ansible modules that you can use to manage Junos devices. The Ansible modules are grouped and distributed through Ansible Content Collections, which are hosted in the Ansible Galaxy repository. Ansible collections are a format for distributing Ansible content that is not included as part of the Ansible core installation. Collections can include a wide range of content, including modules, playbooks, plugins, and roles. Collections also have their own repositories, so they can be developed and released independently from the Ansible core installation.

Table 1 outlines the content sets available for managing Junos devices. Juniper Networks provides the juniper.device collection. Starting in juniper.device Release 2.0.0, we consolidated the Juniper Networks juniper.device collection and the Red Hat Ansible junipernetworks.junos collection into a single collection containing both sets of modules.

Table 1: Ansible Content Sets for Managing Junos Devices
Collection	Module Set	Description
`juniper.device`	`juniper.device`	Modules for managing Junos devices. Juniper Networks provides and manages this collection as an open-source project.
`juniper.device`	`junipernetworks.junos` (`juniper.device.junos_*`)	Modules for managing Junos devices. The Red Hat Ansible Networking team originally maintained this collection. In `juniper.device` Release 2.0.0, we merged the modules into the `juniper.device` collection. Juniper Networks maintains these modules going forward. You can identify these modules by the module name, which starts with `junos_`.

Understanding the `juniper.device` Merged Collection

Merge Overview
Module Set Comparison

Merge Overview

Prior to juniper.device Release 2.0.0, the Juniper Networks juniper.device collection and the Red Hat Ansible junipernetworks.junos collection were separate distinct collections. Each collection owner maintained their respective collection. Starting in juniper.device Release 2.0.0, we merged the junipernetworks.junos collection into the juniper.device collection. Juniper Networks maintains the merged collection going forward.

We will refer to the juniper.device collection to indicate the combined set of modules. To distinguish between the modules sets within the collection, we will refer to the modules as follows:

juniper.device modules or juniper.device original modules
junipernetworks.junos modules or juniper.device.junos_* modules

When you install the juniper.device collection, you can use juniper.device.module_name to execute modules from either module set. To continue using existing playbooks that reference junipernetworks.junos.module_name, you must also install the junipernetworks.junos collection. To execute the junipernetworks.junos modules using either namespace, you must set ansible_network_os to juniper.device.junos. Otherwise, everything else remains the same when using either set of modules.

Although the juniper.device collection includes both sets of modules, each module set uses different Ansible connection values and network OS values. As a result, the two sets of modules cannot use the same inventory file and you cannot intermix the module sets in the same playbook. Thus, we recommend that you select one set of modules to use for your playbooks and tasks. The set you select is a matter of preference. To help you determine which module set works best for your environment, we've provided a high-level overview and comparison of the two sets.

Module Set Comparison

The juniper.device collection and the junipernetworks.junos collection were originally built for different purposes and use cases. Juniper Networks designed the juniper.device modules to provide users with direct access to the full breadth of Junos OS capabilities. Red Hat developed the junipernetworks.junos modules using a consistent approach applied to all Red Hat-maintained networking collections. This approach provided templated configurations for streamlined, repeatable configuration management.

Aside from some distinct differences, both the juniper.device modules and the junipernetworks.junos modules provide similar functions for managing Junos devices. Both sets of modules enable you to:

Get device facts
Execute commands and RPCs on a device
Install software packages
Execute ping operations from a device
Configure a device

Both module sets provide similar options to configure devices. For example, you can:

Load configuration data in one of the accepted formats from a file
Load configuration data as set commands provided in the module arguments
Roll back the configuration
Replace the entire configuration
Specify the format and load operation for loading configuration data
Commit the configuration and include common commit options

The module sets also have some differences with respect to configuration operations. The junipernetworks.junos modules provide numerous configuration templates that enable you to easily configure common statements for specific areas of the configuration hierarchy. For example, you can configure common options for OSPF or static routes.

Similarly, the juniper.device modules provide some additional configuration capabilities. You can compare configurations, load the rescue configuration, and load configuration data using a Jinja2 template. You can also select the configuration mode. For example, you can use batch mode; configure a private copy of the candidate configuration; or configure the dynamic or ephemeral database. The juniper.device modules also provide additional commit options for synchronizing the configuration, committing empty changes, and ignoring commit warnings.

Another key difference between the modules sets is that the juniper.device modules integrate with several other Juniper Networks products. For example, your Ansible playbooks can reference Junos PyEZ operational Tables to retrieve operational state data from a device. Ansible playbooks can also perform Junos Snapshot Administrator in Python (JSNAPy) operations. JSNAPy enables you to capture and audit runtime environment snapshots of your Junos devices. Thus you can use your existing Junos PyEZ Tables and JSNAPy configuration and test files in your Ansible playbooks.

How to Execute Modules on Junos Devices

To use collections hosted in the Ansible Galaxy repository, you must first install Ansible on the control node and then install the collection. For more information about installing the juniper.device collection, see Ansible for Junos OS Server Requirements.

Ansible modules can perform operations on a managed node. Typically, the Ansible control node sends a module to the managed node to perform the operation. The node executes the module and then removes it. In this scenario, the managed node must have the ability to execute the module. Because most Ansible modules are written in Python, Ansible typically requires Python on the managed node.

The modules in the juniper.device collection, however, do not require Python on the managed nodes. In contrast to the typical operation, the Ansible control node executes the modules locally. The modules use the Junos XML API and NETCONF to interface with the managed node. This method of execution enables you to use Ansible to manage any supported Junos device. Figure 1 illustrates the communication between the Ansible control node and a managed Junos device.

Figure 1: Ansible Communication with a Junos Device

To use the juniper.device modules or the junipernetworks.junos modules, your Ansible playbook or command must:

Specify the collection or FQCN—To specify the collection, include the collections key in the play. Alternatively, you can omit the collections key and instead reference collection content by its fully qualified collection name (FQCN), which is the recommended method.

Execute the modules locally on the control node—To run Ansible modules locally, you define the appropriate connection parameters in your playbook, inventory file, or command options. Define the connection parameter in the playbook or define the ansible_connection parameter in the inventory file or host or group variable files. For the junipernetworks.junos modules, you must also specify the ansible_network_os parameter. You generally define this parameter in the inventory file. Table 2 outlines the supported values.

Table 2: Connection Parameters
Module Set	Playbook	Inventory File
`juniper.device` (original modules)	`connection: (local \| juniper.device.pyez)`	`ansible_connection=(local \| juniper.device.pyez)`
`junipernetworks.junos` (all `junos_*` modules except `junos_netconf` and `junos_ping`)	`connection: netconf`	`ansible_connection=netconf` `ansible_network_os=juniper.device.junos`
`junipernetworks.junos` (`junos_netconf` and `junos_ping`)	`connection: network_cli`	`ansible_connection=network_cli` `ansible_network_os=juniper.device.junos`

Provide appropriate connection and authentication information to connect to the managed device.

You can execute Ansible modules using any user account that has access to the managed Junos device. When you execute Ansible modules, Junos OS user account access privileges are enforced. The class configured for the Junos OS user account determines the permissions. Thus, if a user executes a module that loads configuration changes onto a device, the user must have permissions to change the relevant portions of the configuration.

The following sections provide some sample playbooks and inventory files for the different module sets.

Sample Playbook for juniper.device Modules
Sample Inventory File and Playbook for junipernetworks.junos Modules

Sample Playbook for juniper.device Modules

The following playbook executes the juniper.device.facts module to retrieve the device facts and save them to a file. In this example, we define the connection type in the playbook instead of the inventory file. The user authenticates with the device using SSH keys loaded in an SSH key agent.

You can also perform ad hoc operations on the command line. The following command executes the juniper.device.facts module and retrieves device facts from the hosts in inventory group junos.

Sample Inventory File and Playbook for junipernetworks.junos Modules

If you are using the junipernetworks.junos module set, you can define the ansible_connection and ansible_network_os variables in your inventory file or your host or group variable files. The following example inventory file defines the connection parameters for group dc1 under dc1:vars.

The following playbook executes the junipernetworks.junos.junos_facts module under the juniper.device namespace. The playbook references the dc1 group, which defines the appropriate connection and network OS values in the inventory file.

juniper.device Modules

Table 3 outlines the original juniper.device modules in the juniper.device collection. For the current module list, documentation, and usage examples for the modules, see https://ansible-juniper-collection.readthedocs.io.

Table 3: `juniper.device` Modules
Module Name	Description	Supported Ansible Connections
`command`	Execute operational mode commands on the Junos device and save the output locally.	`local` `juniper.device.pyez`
`config`	Manage the configuration of Junos devices.	`local` `juniper.device.pyez`
`facts`	Retrieve device-specific information from the remote host, including the Junos OS version, serial number, and hardware model number.	`local` `juniper.device.pyez`
`file_copy`	Transfer a file between the local Ansible control node and the Junos device.	`local` `juniper.device.pyez`
`jsnapy`	Execute Junos Snapshot Administrator in Python (JSNAPy) tests through Ansible.	`local` `juniper.device.pyez`
`ping`	Execute the `ping` command from a Junos devices.	`local` `juniper.device.pyez`
`pmtud`	Perform path MTU discovery (PMTUD) on Junos devices.	`local` `juniper.device.pyez`
`rpc`	Execute Junos OS RPCs.	`local` `juniper.device.pyez`
`software`	Install a software package and reboot a Junos device.	`local` `juniper.device.pyez`
`srx_cluster`	Create an SRX Series chassis cluster for cluster-capable SRX Series Firewalls.	`local` `juniper.device.pyez`
`system`	Perform system operations on Junos devices, including resetting, rebooting, or shutting down the device.	`local` `juniper.device.pyez`
`table`	Use Junos PyEZ operational Tables and Views to retrieve operational information from Junos devices.	`local` `juniper.device.pyez`

`junipernetworks.junos` Modules

Starting in juniper.device Release 2.0.0, the juniper.device collection includes the junipernetworks.junos modules. Table 4 outlines the junipernetworks.junos modules in the juniper.device collection. The module set enables you to perform operational tasks. It also includes many configuration template modules that configure common settings for various features, protocols, and services on Junos devices.

Table 4: `junipernetworks.junos` Modules
Module Name	Description	Supported Ansible Connections
Operational Modules
`junos_command`	Execute operational mode commands on the Junos device.	`ansible.netcommon.netconf` `ansible.netcommon.network_cli`
`junos_facts`	Retrieve device-specific information from the remote host.	`ansible.netcommon.netconf`
`junos_package`	Install a software package and reboot a Junos device.	`ansible.netcommon.netconf`
`junos_ping`	Execute the `ping` command from a Junos devices.	`ansible.netcommon.network_cli`
`junos_rpc`	Execute Junos OS RPCs over NETCONF on a Junos device.	`ansible.netcommon.netconf`
Configuration Modules
`junos_acl_interfaces`	Apply firewall filters on an interface.	`ansible.netcommon.netconf`
`junos_acls`	Configure firewall filters, sometimes called access control lists (ACLs).	`ansible.netcommon.netconf`
`junos_banner`	Configure banners.	`ansible.netcommon.netconf`
`junos_bgp_address_family`	Manage the BGP Address Family attributes of interfaces.	`ansible.netcommon.netconf`
`junos_bgp_global`	Configure BGP global properties.	`ansible.netcommon.netconf`
`junos_config`	Manage the configuration of Junos devices.	`ansible.netcommon.netconf`
`junos_hostname`	Configure the device hostname.	`ansible.netcommon.netconf`
`junos_interfaces`	Configure basic physical and logical interface properties.	`ansible.netcommon.netconf`
`junos_l2_interfaces`	Configure L2 interfaces.	`ansible.netcommon.netconf`
`junos_l3_interfaces`	Configure L3 interfaces.	`ansible.netcommon.netconf`
`junos_lacp`	Configure global Link Aggregation Control Protocol (LACP) properties for aggregated Ethernet interfaces.	`ansible.netcommon.netconf`
`junos_lacp_interfaces`	Manage the LACP attributes of an interface.	`ansible.netcommon.netconf`
`junos_lag_interfaces`	Configure Link Aggregation Groups (LAGs).	`ansible.netcommon.netconf`
`junos_lldp_global`	Configure global settings for the Link Layer Discovery Protocol (LLDP).	`ansible.netcommon.netconf`
`junos_lldp_interfaces`	Manage the LLDP attributes of an interface.	`ansible.netcommon.netconf`
`junos_logging_global`	Configure system logging.	`ansible.netcommon.netconf`
`junos_netconf`	Configure the NETCONF system service.	`ansible.netcommon.network_cli`
`junos_ntp_global`	Configure the Network Time Protocol (NTP).	`ansible.netcommon.netconf`
`junos_ospf_interfaces`	Manage the OSPF configuration of interfaces.	`ansible.netcommon.netconf`
`junos_ospfv2`	Configure OSPFv2.	`ansible.netcommon.netconf`
`junos_ospfv3`	Configure OSPFv3.	`ansible.netcommon.netconf`
`junos_prefix_lists`	Configure routing policy prefix lists.	`ansible.netcommon.netconf`
`junos_routing_instances`	Configure routing instances.	`ansible.netcommon.netconf`
`junos_routing_options`	Configure routing options.	`ansible.netcommon.netconf`
`junos_security_policies`	Configure and manage security policies.	`ansible.netcommon.netconf`
`junos_security_policies_global`	Configure global security policy settings.	`ansible.netcommon.netconf`
`junos_security_zones`	Configure security zones.	`ansible.netcommon.netconf`
`junos_snmp_server`	Manage the SNMP server configuration.	`ansible.netcommon.netconf`
`junos_static_routes`	Configure static routes.	`ansible.netcommon.netconf`
`junos_system`	Manage the hostname and DNS configuration.	`ansible.netcommon.netconf`
`junos_user`	Configure local user accounts.	`ansible.netcommon.netconf`
`junos_vlans`	Configure VLANs.	`ansible.netcommon.netconf`
`junos_vrf`	Manage the VRF definitions on the device.	`ansible.netcommon.netconf`

ON THIS PAGE