Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Using Ansible to Install Software on Devices Running Junos OS

 

Using Ansible to Install Software

Juniper Networks provides support for using Ansible to manage devices running Junos OS. The juniper_junos_software module in the Juniper.junos role and the junos_package Ansible core module enable you to install a Junos OS software image or other software package on devices running Junos OS.

Note

Starting in Ansible for Junos OS Release 2.0.0, the juniper_junos_software module replaces the functionality of the junos_install_os module.

The following sections discuss how to specify the software image location, the general software installation process and options, and support for unified in-service software upgrades (unified ISSU) and nonstop software upgrades (NSSU) when using the juniper_junos_software module to install software packages on devices running Junos OS. For more information about the junos_package Ansible core module, see https://docs.ansible.com/ansible/latest/junos_package_module.html.

Specifying the Software Image Location

When you use the juniper_junos_software module to install software on devices running Junos OS, you can download the software package to the Ansible control machine or another remote location, and the module, by default, copies the package to the target device before performing the installation. You can also download the software package directly to the managed device running Junos OS and instruct the module to install it from there.

Table 1 outlines the juniper_junos_software module arguments that you must set depending on the software package location. The module must always include either the local_package or remote_package argument. The no_copy argument defaults to false, which instructs the module to copy the software package from the specified location to the target device.

Table 1: juniper_junos_software Module Arguments for Software Package Location

Software Package Location

no_copy Parameter

local_package Parameter

remote_package Parameter

Ansible control machine

Omitted or set to false

Absolute or relative file path including the filename of the software package on the server.

File paths are relative to the playbook directory.

(Optional) File path on the target device to which the software package is copied. The default directory is /var/tmp.

If remote_package is a directory (ends with slash ( / )), the module copies the package to the specified directory.

If remote_package includes a filename, the filename must match the filename specified in local_package.

Remote Location

Omitted or set to false

URL from the perspective of the target device running Junos OS from which the software package is retrieved.

Target device

Set to true

File path on the target device where the software package must already reside. The default directory is /var/tmp/.

If the software package resides on the Ansible control machine, the juniper_junos_software module must include the local_package argument, which specifies the absolute or relative file path to the software package on the local server. By default, when you include the local_package argument, the module copies the software package to the target device running Junos OS. The software image is placed in the /var/tmp directory unless the remote_package argument specifies a different directory. If the remote_package argument includes a filename, the filenames of the local_package and remote_package arguments must be identical, or the module generates an error.

If the software package already resides on the target device running Junos OS, the juniper_junos_software module must include the no_copy: true argument as well the remote_package argument, which specifies the file path to an existing software package on the target device. If remote_package does not specify a directory, the module uses the /var/tmp directory.

If the software package resides at a location other than the Ansible control machine or target device, the juniper_junos_software module must include the remote_package argument and specify the location of the software package. The value of remote_package is a URL from the perspective of the target device running Junos OS. For information about acceptable URL formats, see Format for Specifying Filenames and URLs in Junos OS CLI Commands.

Installation Process Overview

To use Ansible to install a software package on a device running Junos OS, execute the juniper_junos_software module, and provide any necessary arguments. For example:

When the juniper_junos_software module is executed, it performs the following operations:

  1. Compares the Junos OS version specified in the version argument, or in the software package filename if the version argument is omitted, to the installed version on the managed device. If the installed and desired versions are identical, the module skips the remaining installation steps and sets changed and failed to false.
  2. If the local_package argument is present, the module:
    • Computes the MD5 checksum of the local software package, if it is not provided in the checksum argument.

      Note

      To specify a different checksum algorithm, include the checksum_algorithm argument with the value for the desired algorithm.

    • Performs a storage cleanup on the target device to create space for the software package, unless the cleanfs argument is set to false.

  3. Copies the software package to the device, if the no_copy argument is omitted or set to false.

    • If the local_package argument is present, and a file with the same name and MD5 checksum does not already reside in the target location on the device, the module copies the package to the /var/tmp directory unless the remote_package argument specifies a different directory. The module verifies the MD5 checksum of the copied package against the checksum computed for the local package.

      Note

      If the cleanfs argument is omitted or set to true, the module copies the file to the device even if it already exists in the target location, because the storage cleanup operation removes the existing file. To prevent the module from copying the local_package file to the device when it already resides at the target location, include the cleanfs: false argument. If cleanfs: false is present and the file already resides at the target location, the module skips the file copy operation. If the file does not already reside at the target location, the module performs the file copy operation.

    • If the remote_package argument is present and contains a URL external to the target device, the module copies the package to the /var/tmp directory on the target device.

Once the software package is on the target device, whether downloaded there initially or copied over by the juniper_junos_software module, the juniper_junos_software module then performs the following operations:

  1. Validates the configuration against the new package if the validate parameter is set to true.Note

    By default, the juniper_junos_software module does not validate the software package or bundle against the existing configuration as a prerequisite to adding the software package. To ensure that the active configuration will work with the new software image, set the validate argument to true.

  2. Installs the package on each individual Routing Engine, unless all_re is set to false.
  3. Reboots each upgraded Routing Engine, unless the reboot argument is set to false.

The default time for an RPC to time out is 30 seconds. During the installation process, the RPC timeout intervals are increased to 1800 seconds (30 minutes) when copying and installing the package on the device, to 300 seconds (5 minutes) when computing the checksum, and to 300 seconds (5 minutes) when performing a storage cleanup. You can change the timeout value for these operations by setting the install_timeout, checksum_timeout, and cleanfs_timeout arguments, respectively, to the required number of seconds in the juniper_junos_software module argument list. For example:

The juniper_junos_software module enables you to log the progress of the installation by including the logfile module argument. By default, only messages of severity level WARNING or higher are logged. To log messages of severity level INFO or higher, which is required to log messages for the general installation process, execute the playbook with the -v or --verbose command-line option.

Specifying Installation Options That Do Not Have an Equivalent Module Argument

When you use the juniper_junos_software module to install a Junos OS image or other package, the module invokes the <request-package-add> RPC, which is equivalent to the request system software add operational mode command. The module supports explicit arguments for many of the installation options, for example, the validate option. The module also supports the kwargs argument, which enables you to include any additional <request-package-add> options that do not have an equivalent juniper_junos_software argument. The kwargs argument takes a dictionary of key/value pairs of any options supported by the <request-package-add> RPC.

For the current list of options supported by the juniper_junos_software module, see https://junos-ansible-modules.readthedocs.io/en/latest/juniper_junos_software.html. For a list of all available <request-package-add> options, search for the request tag in the Junos XML API Explorer.

Note

The juniper_junos_software module should only include installation options that are supported on the target device running Junos OS.

In the following sample playbook, the juniper_junos_software module installs a new software image on the target hosts. The module includes the kwargs argument with unlink: true. This argument, which removes the software package from the directory after a successful upgrade is completed, is equivalent to including the <unlink/> option in the <request-package-add> RPC.

Performing ISSU or NSSU

The juniper_junos_software module provides support for performing a unified in-service software upgrade (unified ISSU) or a nonstop software upgrade (NSSU) on devices that support the feature and meet the necessary requirements. For more information about the unified ISSU and NSSU features, see the software documentation for your product.

The unified ISSU feature enables you to upgrade between two different Junos OS releases with no disruption on the control plane and with minimal disruption of traffic. To perform a unified in-service software upgrade, the juniper_junos_software module must include the issu: true argument. For example:

The NSSU feature enables you to upgrade the Junos OS software running on a switch or Virtual Chassis with redundant Routing Engines with minimal disruption to network traffic. To perform a nonstop software upgrade, the juniper_junos_software module must include the nssu: true argument. For example:

Example: Using Ansible to Install Software

Juniper Networks provides support for using Ansible to manage devices running Junos OS. The juniper_junos_software module in the Juniper.junos role enables you to install a Junos OS software image or other software package on a device running Junos OS. This example outlines how to use the juniper_junos_software Ansible module to install a software image on a device running Junos OS.

Note

Starting in Ansible for Junos OS Release 2.0.0, the juniper_junos_software module replaces the functionality of the junos_install_os module.

Requirements

This example uses the following hardware and software components:

  • Configuration management server running Ansible 2.1 or later with version 2.0.0 or later of the Juniper.junos role installed

  • Device running Junos OS with NETCONF enabled and a user account configured with appropriate permissions

  • SSH public/private key pair configured for the appropriate user on the Ansible server and device running Junos OS

  • Existing Ansible inventory file with required hosts defined

Overview

The juniper_junos_software module enables you to install a software image on a device running Junos OS. This example presents an Ansible playbook that uses the juniper_junos_software module to upgrade Junos OS on the hosts in the specified inventory group. In this example, the software image resides on the Ansible control machine, and the module copies the image to the target device before installing it. The module does not explicitly define a host argument, so the module operates on the default host, which is {{ inventory_hostname }}.

This playbook includes the Checking NETCONF connectivity task, which utilizes the wait_for module to try to establish a NETCONF session with the device running Junos OS using the default NETCONF port 830. If the control machine fails to establish a NETCONF session with a device during playbook execution, then it skips over the other tasks in the play for that device.

The task to install the Junos OS software image on the device executes the juniper_junos_software module provided that the NETCONF check was successful. The version argument defines the desired Junos OS version as it would be reported by the show version command on the device running Junos OS. During playbook execution, the module first checks that the requested version is not already installed on the device. If the requested version is different from the currently installed version, the module installs the requested version.

The local_package argument defines the path to the new Junos OS image on the Ansible control machine. During the installation, the module performs a storage cleanup operation on the target device, copies the software image to the /var/tmp directory on the device, verifies the file’s checksum, validates the new software against the active configuration, and then installs the software on each Routing Engine on the target host. By default, the juniper_junos_software module reboots the device after the installation is complete; however, this task explicitly sets reboot: true for clarity.

The task stores the module result in the sw variable and notifies one handler. If the user does not execute the playbook using check mode, the wait_reboot handler then tries to establish a session with the device to verify that the device is back online. The wait_time variable defines the length of time that the control machine attempts to reconnect with the device.

This example includes the logfile parameter to log the progress of the installation. This is important for debugging purposes should the installation fail as well as for logging the dates and times of installations on the devices. The user executing the playbook must have permissions to write to the specified log file. By default, only messages of severity level WARNING or higher are logged. In this example, the playbook is executed with the -v option to log messages of severity level INFO or higher to monitor the installation.

Configuration

Creating the Ansible Playbook

Step-by-Step Procedure

To create a playbook that uses the juniper_junos_software module to install a software image on a device running Junos OS:

  1. Include the boilerplate for the playbook and this play, which must contain connection: local and the Juniper.junos role.

  2. Define or import any necessary variables, which for this example, includes the desired Junos OS version and the path to the new image, among others.

  3. (Optional) Create a task to verify NETCONF connectivity.

  4. Create the task to install the Junos OS package on the device and notify the handler.

  5. (Optional) Create a task to print the module response.

  6. Create the handler that verifies that the device comes back online after rebooting.

    The handler name should be the same as that referenced in the installation task.

Results

On the Ansible control machine, review the completed playbook. If the playbook does not display the intended code, repeat the instructions in this example to correct the playbook.

Executing the Playbook

Step-by-Step Procedure

To execute the playbook:

  • Issue the ansible-playbook command on the control machine, and provide the playbook path and any desired options.

    user@ansible-cm:~/ansible$ ansible-playbook -v ansible-pb-junos-install-os.yaml

Verification

Verifying the Installation

Purpose

Verify that the software installation was successful.

Action

The playbook output should indicate any failed tasks. However, you can also review the contents of the log file defined in the playbook for details about the installation. Sample log file output is shown here. Some output has been omitted for brevity.

user@ansible-cm:~/ansible$ cat /var/log/ansible/software.log

Meaning

The log file contents indicate that the image was successfully copied to and installed on the target device.

Release History Table
Release
Description
Starting in Ansible for Junos OS Release 2.0.0, the juniper_junos_software module replaces the functionality of the junos_install_os module.