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

SUMMARY Use the Juniper Networks Ansible modules to install software on devices running Junos OS.

Using Ansible to Install Software

Juniper Networks supports using Ansible to manage devices running Junos OS and provides modules that enable you to install or upgrade the software image on a device. Table 1 outlines the modules.

Table 1: Software Modules

Content Set

Module Name

juniper.device collection

software

Juniper.junos role

juniper_junos_software

Note:

Starting in Juniper.junos 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 and the general software installation process and options when using the modules to install software packages on devices running Junos OS. They also discuss how to perform more specialized upgrade scenarios such as a VM host upgrade, a unified in-service software upgrade (unified ISSU), or a nonstop software upgrade (NSSU) on devices that support these features.

How to Specify the Software Image Location

When you use the software or juniper_junos_software module to install software on devices running Junos OS, you can download the software package to the Ansible control node, and the modules, by default, copy the package to the target device before performing the installation. For mixed Virtual Chassis environments, the packages must reside on the Ansible control node. For standalone devices or non-mixed Virtual Chassis environments, you can also instruct the module to install a software image that already resides on the target device running Junos OS or resides at a URL that is reachable from the target device.

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

Table 2: Module Arguments for Software Package Location

Software Package Location

no_copy Parameter

local_package or pkg_set Parameter

remote_package Parameter

Ansible control node

Omit or set to false

For standalone devices or non-mixed Virtual Chassis environments:

Set local_package to the file path, including the filename, of the software package on the local control node. 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 includes a filename, it must match the filename specified in local_package.

For mixed Virtual Chassis environments:

Set pkg_set to a list of the file paths, including the filenames, of one or more software packages on the local control node. File paths are relative to the playbook directory.

Remote Location

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

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 node, include the local_package argument to install software on a standalone device running Junos OS or on members in a non-mixed Virtual Chassis, or include the pkg_set argument to install software on the members in a mixed Virtual Chassis. The module argument specifies the absolute or relative file path to the software package or packages on the local control node.

The local_package argument is a single string specifying the software image path. The pkg_set argument contains a list of strings that specify the necessary software image paths, in no particular order, for the various Virtual Chassis members. For example:

By default, when you include the local_package or pkg_set argument, the module copies any software packages to the /var/tmp directory on the target device running Junos OS (individual device or Virtual Chassis primary device). If you want to copy the local_package image to a different directory, define the remote_package argument and specify the target 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 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 default is /var/tmp.

If the software package resides at a location other than the Ansible control node or target device, the 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 software or juniper_junos_software module, and provide any necessary arguments. For example:

When you execute the software or juniper_junos_software module, 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 software package is located on the Ansible control node, and the no_copy parameter is omitted or set to False, the module performs the following operations:
    • Computes the checksum of the local software package or packages using the algorithm specified in the checksum_algorithm argument, if the checksum is not already provided in the checksum argument. Acceptable checksum_algorithm values are md5, sha1, and sha256. The default is md5.

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

    • SCP or FTP copies any packages to the target device.

      When the module includes local_package, the package is copied to the remote_package directory, or if remote_package is not specified, to the /var/tmp directory, if a file with the same name and checksum does not already reside in the target location on the device. When the module includes pkg_set, the packages are always copied to the /var/tmp directory on the Virtual Chassis primary device.

      Note:

      If the cleanfs argument is omitted or set to true, the module copies the software package to the device even if it already exists in the target location, because the storage cleanup operation removes the existing file. If cleanfs: false is present and the file already resides at the target location, the module skips the file copy operation.

    • Computes the checksum of each remote file and compares it to the value of the local file.

Once the software package is on the target device, whether downloaded there initially or copied over by the module, the 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 software and juniper_junos_software modules do 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 software and juniper_junos_software modules enable 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.

How to Specify Timeout Values

The Juniper Networks software modules perform operations over a NETCONF session. The default time for a NETCONF RPC to time out is 30 seconds. During the installation process, certain operations increase the RPC timeout interval as follows:

  • Copying and installing the package on the device—1800 seconds (30 minutes)

  • Computing the checksum—300 seconds (5 minutes)

  • Performing a storage cleanup—300 seconds (5 minutes)

In some cases, the installation process, checksum calculation, or storage cleanup might exceed these time intervals. You can change the timeout value for these operations by setting the install_timeout, checksum_timeout, and cleanfs_timeout arguments to the required number of seconds in the module’s argument list. For example:

How to Specify Installation Options That Do Not Have an Equivalent Module Argument

When you use the software or juniper_junos_software module to install software on a device, the module invokes the appropriate RPC for the given installation arguments, for example, the <request-package-add> RPC for standard Junos OS installations, the <request-vmhost-package-add> RPC for VM host upgrades, the <request-package-in-service-upgrade> RPC for unified ISSU scenarios, and so on. The modules support explicit arguments for many of the installation options, for example, the validate option. The modules also support the kwargs argument, which enables you to include any additional options that are supported by the RPC but which do not have an equivalent module argument. The kwargs argument takes a dictionary of key/value pairs of additional supported options.

For the current list of options supported by the modules, see the API reference documentation for that module. For a list of all available options for a specific RPC, see the documentation for the equivalent command or search for the RPC’s request tag in the Junos XML API Explorer.

Note:

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

In the following playbook, the 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 equivalent to including the <unlink/> option in the <request-package-add> RPC.

How to Perform a VM Host Upgrade

On devices that have Routing Engines with VM host support, Junos OS runs as a virtual machine (VM) over a Linux-based host (VM host). A VM host upgrade, which upgrades the host OS and compatible Junos OS, requires a VM Host Installation Package (junos-vmhost-install-x.tgz) and is performed using the request vmhost software add operational mode command, which corresponds to the <request-vmhost-package-add> RPC.

The software and juniper_junos_software modules support the vmhost: True argument for performing a VM host upgrade. When the argument is present, the module performs the installation using the <request-vmhost-package-add> RPC.

The following playbook upgrades and reboots the Junos OS and host OS on the devices:

How to Perform a Unified ISSU or NSSU

The software and juniper_junos_software modules support 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 software or 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 software or juniper_junos_software module must include the nssu: True argument. For example:

Example: Using Ansible to Install Software

This example uses the software module in the juniper.device collection to install a software image on a device running Junos OS.

Requirements

This example uses the following hardware and software components:

  • Configuration management server running Ansible 2.10 or later with the juniper.device collection 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 control node and device running Junos OS

  • Existing Ansible inventory file with required hosts defined

Overview

This example presents an Ansible playbook that uses the 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 node, 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 node fails to establish a NETCONF session with a device during playbook execution, then it skips the remaining tasks in the play for that device.

The Install Junos OS package task executes the 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 of the Junos OS software package on the Ansible control node. 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 software module reboots each Routing Engine after the installation completes; however, this task explicitly sets reboot: True for clarity.

The task stores the module result in the response 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 node 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

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

  1. Include the boilerplate for the playbook and this play, which executes the modules locally.

  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 node, 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

To execute the playbook:

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

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.

Meaning

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

Release History Table
Release
Description
2.0.0
Starting in Juniper.junos Release 2.0.0, the juniper_junos_software module replaces the functionality of the junos_install_os module.