Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Understanding the Ansible for Junos OS Collections, Roles, and Modules

SUMMARY Juniper Networks provides Ansible modules that you can use to manage Junos devices.

Understanding Ansible Collections, Roles, and Modules for Managing Junos Devices

Ansible is an IT automation framework that is used 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, or you can execute modules through playbooks.

Ansible and Juniper Networks provide Ansible modules that you can use to manage Junos devices. The Juniper Networks Ansible modules are grouped and distributed through Ansible roles and collections, which are hosted in the Ansible Galaxy repository. Table 1 outlines the different content sets available for managing Junos devices.

Table 1: Ansible Content Sets for Managing Junos Devices

Content Set

Description

Ansible Releases

Ansible core modules

Ansible modules included in the Ansible base installation.

In Ansible 2.10, the core modules moved from the base installation into Ansible’s junipernetworks.junos collection.

Ansible 2.1 through Ansible 2.9

juniper.device collection

Collection for managing Junos devices, which Juniper Networks provides and manages as an open-source project.

Ansible 2.10 and later

Juniper.junos role

Role for managing Junos devices, which Juniper Networks provides, maintains, and supports.

This role is superseded by the juniper.device collection.

Ansible 2.1 and later

junipernetworks.junos collection

Collection for managing Junos devices, which Ansible provides, maintains, and supports.

Ansible 2.10 and later

An Ansible role is a set of tasks and supporting variables, files, templates, and modules for configuring a host. Starting in Ansible 2.10, Ansible supports Ansible Content Collections, a format for distributing Ansible content that is not included as part of the Ansible base installation. Ansible collections can include a wider range of content, including modules, playbooks, plugins, and roles. Ansible collections also have their own repositories and can be developed and released independently from the Ansible base installation.

In Ansible 2.9 and earlier, you can manage Junos devices by using the modules provided in the Juniper Networks Juniper.junos role or by using the core modules provided as part of the Ansible base installation. Starting in Ansible 2.10, the Juniper.junos role and the Ansible core modules are superseded by the corresponding collection. With the introduction of Juniper Networks’ juniper.device collection, the modules in the Juniper.junos role were duplicated under new names in the collection and thus retain the same functionality and parameters as the original modules, with the exception of the provider parameter. Although the Juniper.junos role can coexist with the juniper.device collection and will work in later releases, we recommend that you use the juniper.device collection, because new features are only being added to the collection going forward.

How to Execute Modules on Junos Devices

To use collections and roles that are hosted in the Ansible Galaxy repository, you must first install Ansible on the control node and then install the collection or role. For more information about installing the juniper.device collection or Juniper.junos role, 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 a managed node, where it is executed and then removed. 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 Juniper Networks modules in the juniper.device collection and the Juniper.junos role, however, do not require Python on the managed nodes. In contrast to the typical operation, you execute the modules locally on the Ansible control node, and the modules use Junos PyEZ and the Junos XML API over 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 Ansible Communication with a Junos Device

To use the modules in the juniper.device collection or the Juniper.junos role, the playbook or command must:

  • Specify the collection or role—To specify the collection or role, include the collections or roles 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 connection parameter as local, for example, by including connection: local in your playbook or including --connection local on the command line.

    Note:

    When you use connection: local, Ansible establishes a separate connection to the device for each task in the play that requires a connection. The juniper.device collection modules also support using connection: juniper.device.pyez, which still executes the modules locally but instead establishes a single, persistent connection to a device for all tasks in a play.

  • Provide appropriate connection and authentication information to connect to the managed device—For more information, see:

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, and 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 playbook executes the juniper.device collection’s facts module to retrieve the device facts and save them to a file. The example uses existing SSH keys in the default location to authenticate with the device and thus does not explicitly provide credentials in the playbook.

Similarly, the following playbook executes the Juniper.junos role’s juniper_junos_facts module to perform the same operation.

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

Juniper Networks juniper.device Collection

Juniper Networks provides the juniper.device Ansible Content Collection, which is hosted on the Ansible Galaxy website and includes Ansible modules that enable you to manage Junos devices.

Table 2 outlines the modules in the juniper.device collection. In the collection’s initial release, the collection modules retain the same functionality and parameters as the corresponding module in the Juniper.junos role, with the exception of the provider parameter, which is not supported for the collection modules.

For the most current list, documentation, and usage examples for the modules, see https://ansible-juniper-collection.readthedocs.io/.

Table 2: juniper.device Collection Modules

juniper.device Module Name

Description

command

Execute CLI commands on the Junos device and save the output locally.

config

Manage the configuration of Junos devices.

facts

Retrieve device-specific information from the remote host, including the Junos OS version, serial number, and hardware model number.

jsnapy

Execute Junos Snapshot Administrator in Python (JSNAPy) tests from Ansible.

ping

Execute the ping command on Junos devices.

pmtud

Perform path MTU discovery on Junos devices.

rpc

Execute Junos OS RPCs.

software

Install a Junos OS software package and reboot a Junos device.

system

Perform system operations on Junos devices, including resetting, rebooting, or shutting down the device.

srx_cluster

Create an SRX Series chassis cluster for cluster-capable SRX Series Firewalls.

table

Use Junos PyEZ operational Tables and Views to retrieve operational information from Junos devices.

Juniper Networks Juniper.junos Role

Juniper Networks provides the Juniper.junos Ansible role, which is hosted on the Ansible Galaxy website and includes Ansible modules that enable you to manage Junos devices. Starting in Ansible 2.10, the juniper.device collection supersedes the Juniper.junos role. The modules in the collection have the same functionality and parameters as the modules in the role, with the exception of the provider parameter. Although the collection and role can coexist on the same platform and you can continue to use the Juniper.junos modules in later releases, we recommend that you use the juniper.device collection, because new features are only being added to the collection going forward.

Table 3 summarizes the modules in the Juniper.junos role. For the most current list, documentation, and usage examples for the modules, see https://junos-ansible-modules.readthedocs.io/en/latest/.

Note:

Starting in Juniper.junos Release 2.0.0, the Juniper.junos role includes an enhanced set of modules. Each new module replaces the functionality of one or more existing modules. The enhanced modules support a common set of connection and authentication parameters, aliases that enable you to specify the same connection and authentication-related options as the core modules, and the ability to specify the parameters inside a provider dictionary.

Table 3: Juniper.junos Role Modules

Module Name

Description

Deprecated Modules as of Release 2.0.0

juniper_junos_command

Execute CLI commands on the Junos device and save the output locally.

junos_cli

juniper_junos_config

Manage the configuration of Junos devices.

junos_commit

junos_get_config

junos_install_config

junos_rollback

juniper_junos_facts

Retrieve device-specific information from the remote host, including the Junos OS version, serial number, and hardware model number.

junos_get_facts

juniper_junos_jsnapy

Execute Junos Snapshot Administrator in Python (JSNAPy) tests from Ansible.

junos_jsnapy

juniper_junos_ping

Execute the ping command on Junos devices.

junos_ping

juniper_junos_pmtud

Perform path MTU discovery on Junos devices.

junos_pmtud

juniper_junos_rpc

Execute Junos OS RPCs.

junos_rpc

juniper_junos_software

Install a Junos OS software package and reboot a Junos device.

junos_install_os

juniper_junos_system

Perform system operations on Junos devices, including resetting, rebooting, or shutting down the device.

junos_shutdown

junos_zeroize

juniper_junos_srx_cluster

Create an SRX Series chassis cluster for cluster-capable SRX Series Firewalls.

junos_srx_cluster

juniper_junos_table

Use Junos PyEZ operational Tables and Views to retrieve operational information from Junos devices.

junos_get_table

Change History Table

Feature support is determined by the platform and release you are using. Use Feature Explorer to determine if a feature is supported on your platform.

Release
Description
2.0.0
Starting in Juniper.junos Release 2.0.0, the Juniper.junos role includes an enhanced set of modules.