npm package: @itentialopensource/cisco-nxos-upgrade-iag
Description: Default artifact description
Author: Itential Artifacts
Latest version: 0.0.16-2023.1.0

<!-- This is a comment in md (Markdown) format, it will not be visible to the end user -->

<!-- Update the below line with your pre-built name -->
# Cisco Nexus Software Upgrade - IAG

<!-- Leave TOC intact unless you've added or removed headers -->
## Table of Contents

* [Deprecation Notice](#deprecation-notice)
* [Overview](#overview)
* [Installation Prerequisites](#installation-prerequisites)
* [Requirements](#requirements)
* [Features](#features)
* [Future Enhancements](#future-enhancements)
* [How to Install](#how-to-install)
* [How to Run](#how-to-run)
* [Command Template Results](#command-template-results)


## _Deprecation Notice_

This prebuilt has been marked for deprecation on May 17th, 2023 with the scheduled removal date as May 17th, 2024. The replacement for this pre-built is the [Cisco NX-OS Upgrade](https://gitlab.com/itentialopensource/pre-built-automations/cisco-nx-os-upgrade/-/tree/master) pre-built.

## Overview

<!-- Write a few sentences about the pre-built and explain the use case(s) -->
<!-- Ex.: The Migration Wizard enables IAP users to conveniently move their automation use cases between different IAP environments -->
<!-- (e.g. from Dev to Pre-Production or from Lab to Production). -->
This pre-built contains the Cisco NXOS Software Upgrade, designed to upgrade firmware on Cisco Nexus 5/7/9k Devices.  You will need to provide device hostname from Ansible, firmware filename (should be already located on the device) and mode of operation (Verbose or Zero-Touch). If you are attempting to upgrade a Nexus 5k device, you will also need to provide the kickstart binary file, which should also already be located on the device.

This solution consists of the following:
* Operations Manager (use case entry point) (**Cisco NX-OS Upgrade - IAG**)
* Main Workflow (**Cisco NX-OS Upgrade - IAG**)
* Workflow (**Device-Connection-Health-Check**)
* Workflow (**Command Template Runner**)
* JSON Form (**Cisco NX-OS Upgrade**)
* TextFSM Template (**Cisco NX-OS Upgrade**)
* Command Template (**Cisco NX-OS Upgrade - Pre Checks**)
* Command Template (**Cisco NX-OS Upgrade - Post Checks**)
* Transformation (**cisco-nxos-upgrade-ID**)
* Transformation (**cisco-nxos-upgrade-Variables**)
* Transformation (**incrementNumber**)


<!-- Workflow(s) Image Placeholder - TO BE ADDED DIRECTLY TO GitLab -->
<!-- REPLACE COMMENT BELOW WITH IMAGE OF YOUR MAIN WORKFLOW -->
<table><tr><td>
  <img src="./images/main.png" alt="workflow" width="800px">
</td></tr></table>
<!-- REPLACE COMMENT ABOVE WITH IMAGE OF YOUR MAIN WORKFLOW -->

<!-- ADD ESTIMATED RUN TIME HERE -->
<!-- e.g. Estimated Run Time: 34 min. -->
_Estimated Run Time_: 20-25 minutes

## Installation Prerequisites

Users must satisfy the following pre-requisites:

<!-- Include any other required apps or adapters in this list -->
<!-- Ex.: EC2 Adapter -->
* Itential Automation Platform (IAP)
  * `^2023.1`
* Itential Automation Gateway (IAG)
  * `^3.227.0+2023.1.15`

## Requirements

This pre-built requires the following:

<!-- Unordered list highlighting the requirements of the pre-built -->
<!-- EXAMPLE -->
<!-- * cisco ios device -->
<!-- * Ansible or NSO (with F5 NED) * -->
* Cisco NX Device - with the new firmware binary already downloaded and integrity-verified

## Features

The main benefits and features of the pre-built are outlined below.

<!-- Unordered list highlighting the most exciting features of the pre-built -->
<!-- EXAMPLE -->
<!-- * Automatically checks for device type -->
<!-- * Displays dry-run to user (asking for confirmation) prior to pushing config to the device -->
<!-- * Verifies downloaded file integrity (using md5), will try to download again if failed -->
  * NXOS Upgrade Artifact follows Cisco Documentation for ordering and procedure
  * 2 modes of operation: Zero-Touch (for happy path), and Verbose
  * Allow rollback changes in verbose mode
  * Configuration snapshot via IAP configuration manager pre-change and post-change
  * Configuration snapshot is directly to the device pre-change and post-change so backups are easily accessible
  * Sufficient Error Handling to allow for retrying in almost every failure case, or proper mitigation if necessary

## Future Enhancements

<!-- OPTIONAL - Mention if the pre-built will be enhanced with additional features on the road map -->
<!-- Ex.: This pre-built would support Cisco XR and F5 devices -->
* Add better functionality to differentiate between devices that are on IAG versus devices that are on NSO

## How to Install

To install the pre-built:

* Verify you are running a supported version of the Itential Automation Platform (IAP) as listed above in the [Requirements](#requirements) section in order to install the pre-built. 
* The pre-built can be installed from within Admin Essentials app. Simply search for the name of your desired pre-built and click the install button (as shown below).

<!-- REPLACE BELOW WITH IMAGE OF YOUR PUBLISHED pre-built -->
<table><tr><td>
  <img src="./images/install.png" alt="install" width="600px">
</td></tr></table>
<!-- REPLACE ABOVE WITH IMAGE OF YOUR PUBLISHED pre-built -->

<!-- OPTIONAL - Explain if external components are required outside of IAP -->
<!-- Ex.: The Ansible roles required for this pre-built can be found in the repository located at https://gitlab.com/itentialopensource/pre-built-automations/hello-world -->

## How to Run

* Navigate to Operations Manager and select the "Cisco NX-OS Upgrade - IAG" automation.
* Select the manual trigger and fill in the JSON form with the NX device, desired binary upgrade package, and mode of operation.
* Navigate to active job to monitor progress.

## Command Template Results**
If zero-touch is disabled, you will be presented with command template results for pre-checks and post-checks and response from the NXOS upgrade on the device. See the images below for reference.

**Pre-Checks and Post-Checks**

Pre-check template results for Cisco NX Upgrade.
<table>
<tr><td>
  <img src="./images/precheck.png" alt="template-results for pre-checks" width="600px">
</td></tr>
</table>
Post-check template results for Cisco NX Upgrade.
<table>
<tr><td>
  <img src="./images/postcheck.png" alt="template-results for post-checks" width="600px">
</td></tr>
</table>

<!-- Explain the main entrypoint(s) for this pre-built: Automation Catalog item, Workflow, Postman, etc. -->