Using Ansible to Halt, Reboot, or Shut Down Devices Running Junos OS
SUMMARY Use the Juniper Networks Ansible modules to halt, reboot, or shut down devices running Junos OS.
Using Ansible to Halt, Reboot, or Shut Down Devices
Juniper Networks supports using Ansible to manage devices running Junos OS and provides Ansible modules that enable you to halt, reboot, or shut down a device. Table 1 outlines the available modules.
Content Set |
Module Name |
|---|---|
|
|
|
Starting in Juniper.junos Release 2.0.0, the juniper_junos_system module replaces the functionality of the junos_shutdown and junos_zeroize modules.
You can use the modules to request the following operations on devices running Junos OS. By default, the modules immediately execute the requested operation and perform the operation on all Routing Engines in a dual Routing Engine or Virtual Chassis setup.
An immediate system halt, reboot, or shutdown
A halt, reboot, or shutdown operation with an optional delay
A halt, reboot, or shutdown operation scheduled at a specific date and time
The system and juniper_junos_system modules require one argument, action,
which defines the action that the module performs. Table 2 defines the action parameter value that is required to halt, reboot,
or shut down a device and provides a brief description of each action
as well as the corresponding CLI command. For information about the "zeroize" action, see Using Ansible to Restore a Device Running Junos OS to the Factory-Default Configuration Settings.
Value of |
Description |
Equivalent CLI Command |
|---|---|---|
|
Gracefully shut down the Junos OS software but maintain system power |
|
|
Reboot the Junos OS software |
|
|
Gracefully shut down the Junos OS software and power off the Routing Engines |
|
The following Ansible playbook uses the system module with action: "reboot" to immediately reboot all Routing Engines on the hosts in the specified
inventory group.
---
- name: Reboot devices running Junos OS
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Reboot all REs on the device
juniper.device.system:
action: "reboot"
How to Perform a Halt, Reboot, or Shut Down with a Delay or at a Specified Time
To delay the halt, reboot, or shut down operation by
a specified number of minutes, set the optional in_min parameter to the number of minutes that the system should wait before
executing the operation. The following task requests a reboot of all
Routing Engines in 30 minutes:
---
- name: Reboot devices running Junos OS
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Reboot all REs in 30 minutes
juniper.device.system:
action: "reboot"
in_min: 30
To schedule the halt, reboot, or shutdown at a specific time,
include the at parameter, which takes a
string that can be specified in one of the following ways:
now—Immediately initiate the halt, reboot, or shut down of the software.+minutes—Number of minutes from now when the requested action is initiated.yymmddhhmm—Absolute time at which to initiate the requested action, specified as year, month, day, hour, and minute.hh:mm—Absolute time on the current day at which to initiate the requested action, specified in 24-hour time.
The following task schedules a system shutdown of all Routing Engines at 22:30 on the current day:
tasks:
- name: Shut down all REs at 22:30 on the current day
juniper.device.system:
action: "shutdown"
at: "22:30"
How to Specify the Target Routing Engine
By default, the system and juniper_junos_system modules perform the requested
operation on all Routing Engines in a dual Routing Engine or Virtual
Chassis setup. You can also instruct the modules to perform the operation
on only the Routing Engine to which the application is connected or
to perform the operation on all Routing Engines except the one to
which the application is connected.
To specify the Routing Engines, you use the all_re and other_re parameters. Table 3 summarizes the all_re and other_re values that are required to execute the requested
operation on specific Routing Engines.
Affected Routing Engines |
|
|
|---|---|---|
All Routing Engines (default) |
Omit or set to |
– |
Only the connected Routing Engine |
Set to |
– |
All Routing Engines except the Routing Engine to which the application is connected |
– |
Set to |
To explicitly indicate that the operation should be performed
on all Routing Engines in a dual Routing Engine or Virtual Chassis
setup, include the all_re: True argument,
which is the default.
---
- name: Reboot devices running Junos OS
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Reboot all Routing Engines
juniper.device.system:
action: "reboot"
all_re: True
To perform the requested action on only the Routing Engine
to which the application is connected, include the all_re: False argument.
tasks:
- name: Reboot only the connected Routing Engine
juniper.device.system:
action: "reboot"
all_re: False
To perform the requested action on all Routing Engines
in the system except for the Routing Engine to which the application
is connected, include the other_re: True argument.
tasks:
- name: Shut down all other Routing Engines
juniper.device.system:
action: "shutdown"
other_re: True
How to Reboot a VM Host
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).
The system and juniper_junos_system modules support the vmhost argument,
which enables you to reboot a VM Host. When you include the action: "reboot" and vmhost: True arguments, the system reboots the host OS and compatible Junos OS
on all Routing Engines by executing the <request-vmhost-reboot> RPC, which corresponds to the request vmhost reboot operational
mode command.
The following playbook performs a VM host reboot, which reboots both the host OS and the guest Junos OS.
---
- name: Reboot VM Hosts
hosts: vm_hosts
connection: local
gather_facts: no
tasks:
- name: Reboot VM host
juniper.device.system:
action: "reboot"
vmhost: True
all_re: False
Example: Using Ansible to Reboot Devices Running Junos OS
The system module
in the juniper.device collection enables
you to halt, reboot, or shut down a device running Junos OS. This
example uses the system module to reboot
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.devicecollection installedDevice 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 system module to reboot a device running Junos OS.
The value of the module’s action argument
defines the operation to execute on the host.
When calling the module from a playbook, we recommend that you
use an interactive prompt to confirm that the user does intend to
reboot the specified devices. If a user unintentionally runs the playbook
and there is no check, it could adversely affect any networks that
require the impacted devices. As a precaution, this playbook uses
an interactive prompt to verify that the user intends to reboot the
devices and requires that the user manually type 'yes' on the command line to execute the module. If the Confirmation check task fails, the Ansible control
node skips the other tasks in the play for that device.
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 the device during playbook execution,
then it skips the remaining tasks in the play for that device.
The task that reboots the device executes the system module provided that the confirmation and NETCONF checks were successful.
The action argument is set to the value "reboot", which indicates that the software should
be rebooted. The in_min: 2 argument
instructs the module to wait for the specified number of minutes before
executing the reboot command. This provides time for any users to
log out of the system.
The task stores the module result in the result variable and notifies two handlers. The pause_for_reboot handler waits a specified amount of time after the reboot operation
is initiated to prevent the wait_reboot handler from falsely detecting that the device is online before
the reboot takes place. The wait_reboot handler then tries to establish a session with the device to verify
that the device comes back online after the reboot. The wait_time_after_reboot variable defines the length
of time that the control node attempts to reconnect with the device.
Configuration
Creating and Executing the Ansible Playbook
Step-by-Step Procedure
To create a playbook that uses the system module to reboot a device running Junos OS:
Include the boilerplate for the playbook and this play, which executes the modules locally.
--- - name: Reboot devices running Junos OS hosts: dc1 connection: local gather_facts: no
Define or import any necessary variables.
vars: wait_time_after_reboot: 300 netconf_port: 830Create an interactive prompt to prevent users from accidentally executing the module without first understanding the implications.
vars_prompt: - name: "reboot_confirmation" prompt: "This playbook reboots devices. Enter 'yes' to continue" private: noCreate the task that confirms the user’s intent.
tasks: - name: Confirmation check fail: msg="Playbook run confirmation failed" when: reboot_confirmation != "yes"(Optional) Create a task to verify NETCONF connectivity.
- name: Checking NETCONF connectivity wait_for: host: "{{ inventory_hostname }}" port: "{{ netconf_port }}" timeout: 5Create the task to reboot the device after a specified number of minutes and then notify the handlers.
- name: Reboot all Routing Engines on the device running Junos OS juniper.device.system: action: "reboot" in_min: 2 all_re: True register: result notify: - pause_for_reboot - wait_reboot(Optional) Create a task to print the response.
- name: Print response debug: var: resultCreate the handler that pauses after rebooting and the handler that verifies that the device comes back online after rebooting.
The handler names should be the same as those referenced in the reboot task.
handlers: - name: pause_for_reboot pause: seconds: 180 when: result.reboot - name: wait_reboot wait_for: host: "{{ inventory_hostname }}" port: "{{ netconf_port }}" timeout: "{{ wait_time_after_reboot }}" when: result.reboot
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.
---
- name: Reboot devices running Junos OS
hosts: dc1
connection: local
gather_facts: no
vars:
wait_time_after_reboot: 300
netconf_port: 830
vars_prompt:
- name: "reboot_confirmation"
prompt: "This playbook reboots devices. Enter 'yes' to continue"
private: no
tasks:
- name: Confirmation check
fail: msg="Playbook run confirmation failed"
when: reboot_confirmation != "yes"
- name: Checking NETCONF connectivity
wait_for:
host: "{{ inventory_hostname }}"
port: "{{ netconf_port }}"
timeout: 5
- name: Reboot all Routing Engines on the device running Junos OS
juniper.device.system:
action: "reboot"
in_min: 2
all_re: True
register: result
notify:
- pause_for_reboot
- wait_reboot
- name: Print response
debug:
var: result
handlers:
- name: pause_for_reboot
pause:
seconds: 180
when: result.reboot
- name: wait_reboot
wait_for:
host: "{{ inventory_hostname }}"
port: "{{ netconf_port }}"
timeout: "{{ wait_time_after_reboot }}"
when: result.reboot
Executing the Playbook
Procedure
Step-by-Step Procedure
To execute the playbook:
Issue the
ansible-playbookcommand on the control node, and provide the playbook path and any desired options.user@ansible-cn:~/ansible$ ansible-playbook ansible-pb-junos-reboot.yaml This playbook reboots devices. Enter 'yes' to continue: yes PLAY [Reboot devices running Junos OS] *************************************** TASK [Confirmation check] **************************************************** skipping: [dc1a.example.net] TASK [Checking NETCONF connectivity] ***************************************** ok: [dc1a.example.net] TASK [Reboot all Routing Engines on the device running Junos OS] ************* changed: [dc1a.example.net] TASK [Print response] ******************************************************** ok: [dc1a.example.net] => { "result": { "action": "reboot", "all_re": true, "changed": true, "failed": false, "media": false, "msg": "reboot successfully initiated. Response got Shutdown at Fri Dec 11 17:36:50 2020. [pid 11595]", "other_re": false, "reboot": true, "vmhost": false } } RUNNING HANDLER [pause_for_reboot] ******************************************* Pausing for 180 seconds (ctrl+C then 'C' = continue early, ctrl+C then 'A' = abort) ok: [dc1a.example.net] RUNNING HANDLER [wait_reboot] ************************************************ ok: [dc1a.example.net] PLAY RECAP ******************************************************************* dc1a.example.net : ok=5 changed=1 unreachable=0 failed=0 skipped=1 rescued=0 ignored=0
Verification
Verifying the Reboot
Purpose
Verify that the device running Junos OS successfully rebooted.
Action
When you execute the playbook, review the output of
the wait_reboot task for each device.
RUNNING HANDLER [wait_reboot] ************************************************* ok: [dc1a.example.net]
Meaning
The wait_reboot result indicates
whether the control node successfully established a session with the
device after it rebooted. If the result indicates success, the device
is online.