Skip to main content

Cluster software endpoint overview

Contributors
PDFs

Overview

You can use the ONTAP cluster software API to retrieve and display relevant information about a software profile, software packages collection, software history collection, and firmware packages collection. This API retrieves the information about all software packages present in the cluster, or a specific software package, or firmware upgrade status.

You can use the POST request to download a software package/firmware from an HTTP or FTP server. The PATCH request provides the option to upgrade the cluster software version. Select the validate_only field to validate the package before triggering the update. Set the version field to trigger the installation of the package in the cluster. You can pause, resume, or cancel any ongoing software upgrade by selecting action. You can use the DELETE request to remove a specific software package present in the cluster.

Examples

Retrieving software profile information

The following example shows how to retrieve software and firmware profile information. You can check the validation results after selecting the validate_only field. Upgrade progress information is available after an upgrade has started.

# The API:
/api/cluster/software

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/software?return_timeout=15" -H "accept: application/hal+json"

# The response:
{
"validation_results": [
 {
   "update_check": "NFS mounts",
   "status": "warning",
   "issue": {
       "message": "Use NFS hard mounts, if possible.",
     }
   ,
   "action": {
       "message": "Use NFS hard mounts, if possible.",
   }
 }
],
"version": "9.5.0",
"pending_version": "9.6.0",
"nodes": [
  {
    "node": "Node 1",
    "version": "9.5.0",
    "firmware": {
      "cluster_fw_progress": [
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "abc.zip",
          "update_type": "automatic_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "failed",
              "attempts": 3,
              "message": "Cannot open the local staging zip file.",
              "code": 2228325
            },
            {
              "worker_node": {
                "name": "Node 2",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3498"
              },
              "status": "complete",
              "attempts": 3,
              "message": "Success",
              "code": 0
            }
          ]
        },
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "xyz.zip",
          "update_type": "manual_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "failed",
              "attempts": 3,
              "message": "Cannot open the local staging zip file.",
              "code": 2228325
            },
            {
              "worker_node": {
                "name": "Node 2",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3498"
              },
              "status": "complete",
              "attempts": 3,
              "message": "Success",
              "code": 0
            }
          ]
        }
      ],
      "disk": {
        "num_waiting_download": 0,
        "total_completion_estimate": 0,
        "average_duration_per_disk": 120,
        "update_status": "idle"
      },
      "shelf": {
        "update_status": "idle",
        "in_progress_count": 2
      },
      "dqp": {
        "revision": "20200117",
        "version": "3.17",
        "file_name": "qual_devices_v2",
        "record_count": {
          "drive": 680,
          "alias": 200,
          "device": 29,
          "system": 3
        }
      },
      "sp_bmc": {
        "fw_type": "SP",
        "image": " primary",
        "status": "installed",
        "is_current": true,
        "running_version": "1.2.3.4",
        "autoupdate": false,
        "last_update_status": "passed",
        "start_time": "2018-05-21T09:53:04+05:30",
        "percent_done": 100,
        "end_time": "2018-05-21T09:53:04+05:30",
        "in_progress": false
      }
    }
  }
],
"metrocluster": {
  "progress_summary": {
          "message": "Update paused by user"
   },
  "progress_details": {
          "message": "Installing software image on cluster \"sti70-vsim-ucs165n_siteA\"."
   },
  "clusters": [
    {
      "name": "sti70-vsim-ucs165n_siteA",
      "uuid": "720f046c-4b13-11e9-9c34-005056ac5626",
      "estimated_duration": 3480,
      "elapsed_duration": 0,
      "state": "waiting"
    },
  ]
},
"state": "in_progress",
"start_time": "2018-05-21T09:53:04+05:30",
"end_time": "2018-05-21T11:53:04+05:30",
"estimated_time": 5220,
"elapsed_time": 2140,
"update_details": [
  {
    "phase": "Data ONTAP updates",
    "state": "in_progress",
    "estimated_duration": 4620,
    "elapsed_duration": 29,
    "node": {
      "name": "sti70-vsim-ucs165n"
    }
  }
],
"status_details": [
  {
    "name": "do-download-job",
    "state": "completed",
    "issue": {
            "message": "Image update complete",
            "code": 0
     },
    "start_time": "2018-05-21T09:53:04+05:30",
    "end_time": "2018-05-21T11:53:04+05:30",
    "node": {
      "name": "sti70-vsim-ucs165n"
    }
  }
],
"_links": {
  "self": {
    "href": "/api/cluster/software/"
  }
}
}

Upgrading the software version

The following example shows how to upgrade cluster software. Set the version field to trigger the installation of the package. You can select the validate_only field to validate the package before the installation starts. Setting skip_warning as true ignores the validation warning before the installation starts. Setting the action field performs a pause, resume, or cancel' operation on an ongoing upgrade. An upgrade can only be resumed if it is in the paused state. Setting stabilize_minutes allows each node a specified amount of time to stabilize after a reboot; the default is 8 minutes. If show_validation_details` is set to "true", all validation details will be shown in the output.

You can start the upgrade process at the cluster level. There are no options available to start the upgrade for a specific node or HA pair.

1. Validating the package and verifying the validation results

The following example shows how to validate a cluster software package. You must validate the package before the software upgrade. Set the validate_only field to true to start the validation. You can check for validation results in the GET /cluster/software endpoint.

# The API:
/api/cluster/software

# The call:
curl -X PATCH "https://<mgmt_ip>/api/cluster/software?validate_only=true" -H "accept: application/json" -H "Content-Type: application/hal+json" -d '{ "version": "9.5.0"}'

# The response:
{
"job": {
  "uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
  "_links": {
    "self": {
      "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
    }
  }
}
}

The call to validate the software cluster version returns the job UUID, including a HAL link to retrieve details about the job. The job object includes a state field and a message to indicate the progress of the job. When the job is complete and the application is fully created, the message indicates success and the state field of the job is set to success.

# The API:
/api/cluster/jobs/{uuid}

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc" -H "accept: application/hal+json"

# The response:
{
"uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
"description": "PATCH /api/cluster/software",
"state": "success",
"message": "success",
"code": 0,
"_links": {
  "self": {
    "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
  }
}
}

You can check for validation results in the GET /cluster/software endpoint. The following example shows how to check the validation warnings and errors after setting the validate_only field to true.

# The API:
/api/cluster/software

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/software" -H "accept: application/hal+json"

# The response:
{
"version": "9.7.0",
"validation_results": [
  {
    "update_check": "High Availability status",
    "status": "error",
    "issue": {
      "message": "Cluster HA is not configured in the cluster. Storage failover is not enabled on node \"node1\", \"node2\".",
    },
    "action": {
      "message": "Check cluster HA configuration. Check storage failover status."
    }
  },
  {
    "update_check": "Manual checks",
    "status": "warning",
    "issue" : {
      "message": "Manual validation checks need to be performed. Refer to the Upgrade Advisor Plan or the \"What should I verify before I upgrade with or without Upgrade Advisor\" section in the \"Upgrade ONTAP\" documentation for the remaining validation checks that need to be performed before update. Failing to do so can result in an update failure or an I/O disruption."
    },
    "action": {
      "message": "Refer to the Upgrade Advisor Plan or the \"What should I verify before I upgrade with or without Upgrade Advisor\" section in the \"Upgrade ONTAP\" documentation for the remaining validation checks that need to be performed before update."
    }
  }
],
"nodes": [
  {
    "node": "sti70-vsim-ucs165n",
    "version": "9.5.0",
    "firmware": {
      "cluster_fw_progress": [
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "abc.zip",
          "update_type": "automatic_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3498"
              },
              "status": "failed",
              "attempts": 3,
              "message": "Cannot open the local staging zip file.",
              "code": 2228325
            },
            {
              "worker_node": {
                "name": "Node 2",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3498"
              },
              "status": "complete",
              "attempts": 3,
              "message": "Success",
              "code": 0
            }
          ]
        },
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "xyz.zip",
          "update_type": "automatic_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3498"
              },
              "status": "failed",
              "attempts": 3,
              "message": "Cannot open the local staging zip file.",
              "code": 2228325
            },
            {
              "worker_node": {
                "name": "Node 2",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3498"
              },
              "status": "complete",
              "attempts": 3,
              "message": "Success",
              "code": 0
            }
          ]
        }
      ],
      "disk": {
        "num_waiting_download": 0,
        "total_completion_estimate": 0,
        "average_duration_per_disk": 120,
        "update_status": "idle"
      },
      "shelf": {
        "update_status": "idle",
        "in_progress_count": 2
      },
      "dqp": {
        "revision": "20200117",
        "version": "3.17",
        "file_name": "qual_devices_v2",
        "record_count": {
          "drive": 680,
          "alias": 200,
          "device": 29,
          "system": 3
        }
      },
      "sp_bmc": {
        "fw_type": "SP",
        "image": " primary",
        "status": "installed",
        "is_current": true,
        "running_version": "1.2.3.4",
        "autoupdate": false,
        "last_update_status": "passed",
        "start_time": "2018-05-21T09:53:04+05:30",
        "percent_done": 100,
        "end_time": "2018-05-21T09:53:04+05:30",
        "in_progress": false
      }
    }
  }
],
"state": "failed",
"elapsed_duration": 56,
"estimated_duration": 600,
"_links": {
  "self": {
    "href": "/api/cluster/software"
  }
}
}

2. Updating the cluster

The following example shows how to initiate a cluster software upgrade. You must validate the package before the software upgrade starts. Set the skip_warnings field to true to skip validation warnings and start the software package upgrade. You can specify the stabilize_minutes value between 1 to 60 minutes. Setting stabilize_minutes allows each node a specified amount of time to stabilize after a reboot; the default is 8 minutes. If the value of show_validation_details is set to "true", then all validation details will be shown in the output.

# The API:
/api/cluster/software

# The call:
curl -X PATCH "https://<mgmt_ip>/api/cluster/software?skip_warnings=true" -H "accept: application/json" -H "Content-Type: application/hal+json" -d '{ "version": "9.5.0"}'

# The response:
{
"job": {
  "uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
  "_links": {
    "self": {
      "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
    }
  }
}
}

The call to update the software cluster version returns the job UUID, including a HAL link to retrieve details about the job. The job object includes a state field and a message to indicate the progress of the job. When the job is complete and the application is fully created, the message indicates success and the state field of the job is set to success.

# The API:
/api/cluster/jobs/{uuid}

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc" -H "accept: application/hal+json"

# The response:
{
"uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
"description": "PATCH /api/cluster/software",
"state": "success",
"message": "success",
"code": 0,
"_links": {
  "self": {
    "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
  }
}
}

You can check the update progress information in the GET /cluster/software endpoint. The following example shows how to check the progress of an update after setting the skip_warnings field to true. Each node's object also includes information about the firmware update status on the node.

# The API:
/api/cluster/software

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/software" -H "accept: application/hal+json"

# The response:
{
"version": "9.7.0",
"validation_results": [
  {
    "update_check": "Manual checks",
    "status": "warning",
    "issue" : {
      "message": "Manual validation checks need to be performed. Refer to the Upgrade Advisor Plan or the \"What should I verify before I upgrade with or without Upgrade Advisor\" section in the \"Upgrade ONTAP\" documentation for the remaining validation checks that need to be performed before update. Failing to do so can result in an update failure or an I/O disruption."
    },
    "action": {
      "message": "Refer to the Upgrade Advisor Plan or the \"What should I verify before I upgrade with or without Upgrade Advisor\" section in the \"Upgrade ONTAP\" documentation for the remaining validation checks that need to be performed before update."
    }
  }
],
"nodes": [
  {
    "node": "sti70-vsim-ucs165n",
    "version": "9.5.0",
    "firmware": {
      "cluster_fw_progress": [
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "abc.zip",
          "update_type": "automated_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 3",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "failed",
              "attempts": 3,
              "message": "Cannot open the local staging zip file.",
              "code": 2228325
            },
            {
              "worker_node": {
                "name": "Node 4",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3498"
              },
              "status": "complete",
              "attempts": 3,
              "message": "Success",
              "code": 0
            }
          ]
        },
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "xyz.zip",
          "update_type": "automated_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "failed",
              "attempts": 3,
              "message": "Cannot open the local staging zip file.",
              "code": 2228325
            },
            {
              "worker_node": {
                "name": "Node 2",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "complete",
              "attempts": 3,
              "message": "Success",
              "code": 0
            }
          ]
        }
      ],
      "disk": {
        "num_waiting_download": 0,
        "total_completion_estimate": 0,
        "average_duration_per_disk": 120,
        "update_status": "idle"
      },
      "shelf": {
        "update_status": "idle",
        "in_progress_count": 2
      },
      "dqp": {
        "revision": "20200117",
        "version": "3.17",
        "file_name": "qual_devices_v2",
        "record_count": {
          "drive": 680,
          "alias": 200,
          "device": 29,
          "system": 3
        }
      },
      "sp_bmc": {
        "fw_type": "SP",
        "image": " primary",
        "status": "installed",
        "is_current": true,
        "running_version": "1.2.3.4",
        "autoupdate": false,
        "last_update_status": "passed",
        "start_time": "2018-05-21T09:53:04+05:30",
        "percent_done": 100,
        "end_time": "2018-05-21T09:53:04+05:30",
        "in_progress": false
      }
    }
  }
],
"pending_version": "9.7.0",
"state": "in_progress",
"elapsed_duration": 63,
"estimated_duration": 5220,
"status_details": [
  {
    "name": "do-download-job",
    "status": "running",
    "issue": {
            "message": "Installing software image.",
            "code": 10551400
     },
    "start_time": "2019-01-14T23:12:14+05:30",
    "end_time": "2019-01-14T23:12:14+05:30",
    "node": {
      "name": "node1"
    }
  },
  {
    "name": "do-download-job",
    "status": "running",
    "issue": {
            "message": "Installing software image.",
            "code": 10551400
    },
    "start_time": "2019-01-14T23:12:14+05:30",
    "end_time": "2019-01-14T23:12:14+05:30",
    "node": {
      "name": "node2"
    }
  }
],
"update_details": [
  {
    "phase": "Data ONTAP updates",
    "status": "in-progress",
    "estimated_duration": 4620,
    "elapsed_duration": 10,
    "node": {
      "name": "node1"
    }
  },
  {
    "phase": "Data ONTAP updates",
    "status": "in-progress",
    "estimated_duration": 4620,
    "elapsed_duration": 10,
    "node": {
      "name": "node2"
    }
  }
],
"_links": {
  "self": {
    "href": "/api/cluster/software"
  }
}
}

In the case of a post update check failure, the details are available under the heading "post_update_checks" in the GET /cluster/software endpoint. The following example shows how to check the progress of an update after a post update check has failed. Each node's object also includes information about the firmware update status on the node.

# The API:
/api/cluster/software

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/software" -H "accept: application/hal+json"

# The response:
{
"version": "9.7.0",
"validation_results": [
  {
    "update_check": "Manual checks",
    "status": "warning",
    "issue" : {
      "message": "Manual validation checks need to be performed. Refer to the Upgrade Advisor Plan or the \"What should I verify before I upgrade with or without Upgrade Advisor\" section in the \"Upgrade ONTAP\" documentation for the remaining validation checks that need to be performed before update. Failing to do so can result in an update failure or an I/O disruption."
    },
    "action": {
      "message": "Refer to the Upgrade Advisor Plan or the \"What should I verify before I upgrade with or without Upgrade Advisor\" section in the \"Upgrade ONTAP\" documentation for the remaining validation checks that need to be performed before update."
    }
  }
],
"nodes": [
  {
    "node": "sti70-vsim-ucs165n",
    "version": "9.5.0",
    "firmware": {
      "cluster_fw_progress": [
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "abc.zip",
          "update_type": "automated_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "working",
              "attempts": 3,
              "message": "<message catalog text>",
              "code": 3
            },
            {
              "worker_node": {
                "name": "Node 2",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "completed",
              "attempts": 3,
              "message": "Error message",
              "code": 0
            }
          ]
        },
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "xyz.zip",
          "update_type": "automated_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "completed",
              "attempts": 1,
              "message": "Error message",
              "code": 0
            },
            {
              "worker_node": {
                "name": "Node 2",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "completed",
              "attempts": "3",
              "message": "Error message",
              "code": 0
            }
          ]
        }
      ],
      "disk": {
        "num_waiting_download": 0,
        "total_completion_estimate": 0,
        "average_duration_per_disk": 120,
        "update_status": "idle"
      },
      "shelf": {
        "update_status": "idle",
        "in_progress_count": 2
      },
      "dqp": {
        "revision": "20200117",
        "version": "3.17",
        "file_name": "qual_devices_v2",
        "record_count": {
          "drive": 680,
          "alias": 200,
          "device": 29,
          "system": 3
        }
      },
      "sp_bmc": {
        "fw_type": "SP",
        "image": " primary",
        "status": "installed",
        "is_current": "true",
        "running_version": "1.2.3.4",
        "autoupdate": "false",
        "last_update_status": "passed",
        "start_time": "2018-05-21T09:53:04+05:30",
        "percent_done": 100,
        "end_time": "2018-05-21T09:53:04+05:30",
        "in_progress": "yes"
      }
    }
  }
],
"pending_version": "9.7.0",
"state": "in_progress",
"elapsed_duration": 63,
"estimated_duration": 5220,
"status_details": [
  {
    "name": "do-download-job",
    "status": "completed",
    "issue": {
            "message": "Image update complete.",
            "code": 0
     },
    "start_time": "2019-01-14T23:12:14+05:30",
    "end_time": "2019-01-14T23:12:14+05:30",
    "node": {
      "name": "node1"
    }
  },
  {
    "name": "do-download-job",
    "status": "completed",
    "issue": {
            "message": "Image update complete.",
            "code": 0
    },
    "start_time": "2019-01-14T23:12:14+05:30",
    "end_time": "2019-01-14T23:12:14+05:30",
    "node": {
      "name": "node2"
    }
  }
],
"update_details": [
  {
    "phase": "Data ONTAP updates",
    "status": "completed",
    "estimated_duration": 4620,
    "elapsed_duration": 3120,
    "node": {
      "name": "node1"
    }
  },
  {
    "phase": "Data ONTAP updates",
    "status": "completed",
    "estimated_duration": 4620,
    "elapsed_duration": 3210,
    "node": {
      "name": "node2"
    }
  },
  {
    "phase": "Post-update checks",
    "status": "paused_on_error",
    "estimated_duration": 600,
    "elapsed_duration": 10,
    "node": {
      "name": "node2"
    }
  }
],
"post_update_checks": [
  {
    "update_check": "Aggregate Health Status",
    "status": "error",
    "issue": {
      "message": "Not all aggregates are online"
    },
    "action": {
      "message": "Ensure all aggregates are online."
    }
  },
  {
    "update_check": "HA Health Status",
    "status": "error",
    "issue": {
      "message": "Storage failover is not enabled on nodes of the cluster."
    },
    "action": {
      "message": "Ensure storage failover is enabled on all nodes of the cluster."
    }
  }
],
"_links": {
  "self": {
    "href": "/api/cluster/software"
  }
}
}

3. Pausing, resuming or canceling an upgrade

The following example shows how to pause an ongoing cluster software package upgrade. Set the action field to pause, resume, or cancel to pause, resume or cancel the upgrade respectively. Not all update operations support these actions. An update can only be resumed if it is in the paused state.

# The API:
/api/cluster/software

# The call:
curl -X PATCH "https://<mgmt_ip>/api/cluster/software?action=pause" -H "accept: application/json" -H "Content-Type: application/hal+json" -d '{ "version": "9.5.0"}'

# The response:
{
"job": {
  "uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
  "_links": {
    "self": {
      "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
    }
  }
}
}

The call to update the software cluster version and/or firmware version returns the job UUID, including a HAL link to retrieve details about the job. The job object includes a state field and a message to indicate the progress of the job. When the job is complete and the application is fully created, the message indicates success and the state field of the job is set to success.

# The API:
/api/cluster/jobs/{uuid}

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc" -H "accept: application/hal+json"

# The response:
{
"uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
"description": "PATCH /api/cluster/software",
"state": "success",
"message": "success",
"code": 0,
"_links": {
  "self": {
    "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
  }
}
}

You can check the progress of the upgrade in the GET /cluster/software endpoint. The following example shows how to check the progress of the pause upgrade state after setting the action field to pause.

# The API:
/api/cluster/software

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/software" -H "accept: application/hal+json"

# The response:
{
"version": "9.7.0",
"validation_results": [
  {
    "update_check": "Manual checks",
    "status": "warning",
    "issue" : {
      "message": "Manual validation checks need to be performed. Refer to the Upgrade Advisor Plan or the \"What should I verify before I upgrade with or without Upgrade Advisor\" section in the \"Upgrade ONTAP\" documentation for the remaining validation checks that need to be performed before update. Failing to do so can result in an update failure or an I/O disruption."
    },
    "action": {
      "message": "Refer to the Upgrade Advisor Plan or the \"What should I verify before I upgrade with or without Upgrade Advisor\" section in the \"Upgrade ONTAP\" documentation for the remaining validation checks that need to be performed before update."
    }
  }
],
"nodes": [
  {
    "node": "sti70-vsim-ucs165n",
    "version": "9.5.0",
    "firmware": {
      "cluster_fw_progress": [
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "abc.zip",
          "update_type": "automated_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "failed",
              "attempts": 3,
              "message": "Cannot open the local staging zip file.",
              "code": 2228325
            },
            {
              "status": "complete",
              "attempts": 3,
              "message": "Success",
              "code": 0
            }
          ]
        },
        {
          "job": {
            "uuid": "5a21663c-a9a0-11ea-af9a-005056bb44d7",
            "_links": {
              "self": {
                "href": "/api/cluster/jobs/5a21663c-a9a0-11ea-af9a-005056bb44d7"
              }
            }
          },
          "zip_file_name": "xyz.zip",
          "update_type": "automated_update",
          "update_state": [
            {
              "worker_node": {
                "name": "Node 1",
                "uuid": "fcd40f70-f531-11eb-b235-005056bb3497"
              },
              "status": "failed",
              "attempts": 3,
              "message": "Cannot open the local staging zip file.",
              "code": 2228325
            },
            {
              "status": "complete",
              "attempts": 3,
              "message": "Success",
              "code": 0
            }
          ]
        }
      ],
      "disk": {
        "num_waiting_download": 0,
        "total_completion_estimate": 0,
        "average_duration_per_disk": 120,
        "update_status": "idle"
      },
      "shelf": {
        "update_status": "idle",
        "in_progress_count": 2
      },
      "dqp": {
        "revision": "20200117",
        "version": "3.17",
        "file_name": "qual_devices_v2",
        "record_count": {
          "drive": 680,
          "alias": 200,
          "device": 29,
          "system": 3
        }
      },
      "sp_bmc": {
        "fw_type": "SP",
        "image": " primary",
        "status": "installed",
        "is_current": true,
        "running_version": "1.2.3.4",
        "autoupdate": false,
        "last_update_status": "passed",
        "start_time": "2018-05-21T09:53:04+05:30",
        "percent_done": 100,
        "end_time": "2018-05-21T09:53:04+05:30",
        "in_progress": false
      }
    }
  }
],
"pending_version": "9.7.0",
"state": "pause_pending",
"elapsed_duration": 103,
"estimated_duration": 5220,
"status_details": [
  {
    "status": "in-progress",
    "issue": {
            "message": "Installing software image.",
            "code": 10551400
     },
    "start_time": "2019-01-08T02:54:36+05:30",
    "node": {
      "name": "node1"
    }
  },
  {
    "status": "in-progress",
    "issue": {
            "message": "Installing software image.",
            "code": 10551400
     },
    "start_time": "2019-01-08T02:54:36+05:30",
    "node": {
      "name": "node2"
    }
  }
],
"update_details": [
  {
    "phase": "Pre-update checks",
    "status": "completed",
    "estimated_duration": 600,
    "elapsed_duration": 54,
    "node": {
      "name": "node1"
    }
  },
  {
    "phase": "Data ONTAP updates",
    "status": "pause-pending",
    "estimated_duration": 4620,
    "elapsed_duration": 49,
    "node": {
      "name": "node2"
    }
  },
  {
    "phase": "Data ONTAP updates",
    "status": "pause-pending",
    "estimated_duration": 4620,
    "elapsed_duration": 49
  }
],
"_links": {
  "self": {
    "href": "/api/cluster/software"
  }
}
}

Downloading the software package

The following example shows how to download the software/firmware package from an HTTP or FTP server. Provide the url, username, and password, if required, to start the download of the package to the cluster.

# The API:
/api/cluster/software/download

# The call:
curl -X POST "https://<mgmt-ip>/api/cluster/software/download?return_timeout=0" -H "accept: application/json" -H "Content-Type: application/hal+json" -d '{ "url": "http://server/package", "username": "admin", "password": "*********"}'

# The response:
{
"job": {
  "uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
  "_links": {
    "self": {
      "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
    }
  }
}
}

The call to download the software/firmware package returns the job UUID, including a HAL link to retrieve details about the job. The job object includes a state field and a message to indicate the progress of the job. When the job is complete and the application is fully created, the message indicates success and the job state field is set to success.

# The API:
/api/cluster/jobs/{uuid}

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc" -H "accept: application/hal+json"

# The response:
{
"uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
"description": "POST /api/cluster/software/download",
"state": "success",
"message": "success",
"code": 0,
"_links": {
  "self": {
    "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
  }
}
}

Checking the progress of the software package being downloaded from an HTTP or FTP server

The following example shows how to retrieve the progress status of the software package being downloaded from a HTTP or FTP server.

# The API:
/api/cluster/software/download

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/software/download" -H "accept: application/hal+json"

# The response:
{
"state": "running",
"message": "Package download in progress",
"code": 10551382,
"_links": {
  "self": {
    "href": "/api/cluster/software/download"
  }
}
}

HTTPS error codes

The following is a list of possible error codes that can be returned during a package download operation.

ONTAP Error Response Codes

Error Code Description

2228324

Failed to access the remote zip file on node.

2228325

Cannot open local staging ZIP file

2228326

File copy to local staging failed.

2228327

Firmware file already exists.

2228328

Firmware update of node failed.

2228329

Attempt to start worker on node failed

2228330

Uploaded firmware file is not present.

2228331

Copy of file from webserver failed.

2228428

Firmware update completed with errors

2228429

Firmware update completed.

10551327

Package image with the same name already exists.

10551357

Cannot perform an update when a previous update is still in progress.

10551381

Package download failed.

10551382

Package download is still running.

10551384

Package download has not started.

10551496

Failed to download package.

10551797

Internal error. Failed to check if file upload is enabled. Contact technical support for assistance.

10551859

Failed to set primary and secondary nodes to store new image.

Also see the table of common errors in the Response body overview section of this documentation.

Uploading a software/firmware package

The following example shows how to upload a software package.

# The API:
/api/cluster/software/upload

# The call:
curl -ku username:password -F "file=@image.tgz" -X POST "https://<mgmt-ip>/api/cluster/software/upload?return_timeout=0"

# The response:
{
"job": {
"uuid": "12db53fd-8326-11ea-91eb-005056bb16e5",
"_links": {
    "self": {
    "href": "/api/cluster/jobs/12db53fd-8326-11ea-91eb-005056bb16e5"
    }
 }
}
}

HTTPS error codes

The following is a list of possible error codes that can be returned during a package upload operation.

ONTAP Error Response Codes

Error Code Description

2228324

Failed to access the remote zip file on node.

2228325

Cannot open local staging ZIP file

2228326

File copy to local staging failed.

2228327

Firmware file already exists.

2228328

Firmware update of node failed.

2228329

Attempt to start worker on node failed

2228330

Uploaded firmware file is not present.

2228331

Copy of file from webserver failed.

2228428

Firmware update completed with errors

2228429

Firmware update completed.

10551395

Validation checks failed with warnings.

10551797

Internal error. Failed to check if file upload is enabled.

10551798

File upload is disabled. Enable file upload by setting "ApacheUploadEnabled 1" in the web services configuration file or contact technical support for assistance.

10551800

Internal error. Access permissions restrict file upload. This is likely due to a bad web jail setup. Contact technical support for assistance.

10551801

Internal error. A read/write error occurred when uploading this file. Contact technical support for assistance

10551802

An invalid argument was supplied to create a file handle. Try uploading the file again or contact technical support for assistance.

10551803

An unknown error occurred. Retry file upload operation again or contact technical support for assistance.

10551804

Internal error. There is not sufficient space in the file upload directory to upload this file. Contact technical support for assistance.

10551805

Internal error in JAIL setup. Contact technical support for assistance.

10551806

Internal error. Failed to write to file in the webjail directory. Contact technical support for assistance.

10551807

The request must only contain a single file. More than one file per request is not supported.

10551808

The request must be of type multipart/form-data.

Also see the table of common errors in the Response body overview section of this documentation.

Retrieving cluster software packages information

The following example shows how to retrieve the ONTAP software packages in a cluster.

# The API:
/api/cluster/software/packages

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/software/packages?return_records=true&return_timeout=15" -H "accept: application/hal+json"

# The response:
{
"records": [
  {
    "version": "9.7.0",
    "_links": {
      "self": {
        "href": "/api/cluster/software/packages/9.7.0"
      }
    }
  },
  {
    "version": "9.5.0",
    "_links": {
      "self": {
        "href": "/api/cluster/software/packages/9.5.0"
      }
    }
  }
],
"num_records": 2,
"_links": {
  "self": {
    "href": "/api/cluster/software/packages"
  }
}
}

The following example shows how to retrieve the details of a given cluster software package.

# The API:
/api/cluster/software/packages/{version}

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/software/packages/9.7.0" -H "accept: application/hal+json"

# The response:
{
"version": "9.7.0",
"create_time": "2018-05-21T10:06:59+05:30",
"_links": {
  "self": {
    "href": "/api/cluster/software/packages/9.7.0"
  }
}
}

Deleting a cluster software package

The following example shows how to delete a package from the cluster. You need to provide the package version that you want to delete. The software package delete creates a job to perform the delete operation.

# The API:
/api/cluster/software/packages/{version}

# The call:
curl -X DELETE "https://<mgmt-ip>/api/cluster/software/packages/9.6.0" -H "accept: application/hal+json"

# The response:
{
"job": {
  "uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
  "_links": {
    "self": {
      "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
    }
  }
}
}

The call to delete the package returns the job UUID, including a HAL link to retrieve details about the job. The job object includes a state field and a message to indicate the progress of the job. When the job is complete and the application is fully created, the message indicates success and the job state field is set to success.

# The API:
/api/cluster/jobs/{uuid}

# The call:
curl -X GET "https://<mgmt-ip>/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc" -H "accept: application/hal+json"

# The response:
{
"uuid": "f587d316-5feb-11e8-b0e0-005056956dfc",
"description": "DELETE /api/cluster/software/packages/9.6.0",
"state": "success",
"message": "success",
"code": 0,
"_links": {
  "self": {
    "href": "/api/cluster/jobs/f587d316-5feb-11e8-b0e0-005056956dfc"
  }
}
}

HTTPS error codes

The following is a list of possible error codes that can be returned during a package delete operation.

ONTAP Error Response codes

| -------- | -------------------------------------- | | Error codes | Description | | -------- | -------------------------------------- | | 10551315 | Package store is empty | | 10551322 | Error in retrieving package cleanup status | | 10551323 | Error in cleaning up package information on a node | | 10551324 | Error in cleaning up package information on both nodes | | 10551325 | Package does not exist on the system | | 10551326 | Error in deleting older package cleanup tasks | | 10551346 | Package delete failed since a validation is in progress | | 10551347 | Package delete failed since an update is in progress | | 10551367 | A package synchronization is in progress | | 10551388 | Package delete operation timed out | | 10551566 | Validation is not completed on the MetroCluster partner | | | cluster | | 10551567 | Package version is not available in the package |

| | repository on the MetroCluster partner cluster | | -------- | -------------------------------------- |

'''


### Retrieving software installation history information
The following example shows how to:
 - retrieve the software package installation history information.
 - display specific node level software installation history information.
 - provide all the attributes by default in response when the self referential link is not present.

The API:

/api/cluster/software/history

The call:

curl -X GET "https:///api/cluster/software/history" -H "accept: application/hal+json"

The response:

{ "node": { "uuid": "58cd3a2b-af63-11e8-8b0d-0050568e7279", "name": "sti70-vsim-ucs165n", "_links": { "self": { "href": "/api/cluster/nodes/58cd3a2b-af63-11e8-8b0d-0050568e7279" } } }, "start_time": "2018-09-03T16:18:46+05:30", "state": "successful", "from_version": "9.4.0", "to_version": "9.5.0", "end_time": "2018-05-21T10:14:51+05:30" }

'''