Module netapp_ontap.resources.software
Copyright © 2019 NetApp Inc. All rights reserved.
Overview
ONTAP cluster software API retrieves and displays relevant information about the software profile, software packages collection, and software history collection. The API retrieves the information about all software packages present in the cluster, or specific software package.
The POST request provides the ability to download a software package from an HTTP or FTP server. The PATCH request provides the option to upgrade the cluster software version. The client can validate the package before triggering the update by selecting the validate_only
field. Setting the version
field triggers the installation of the package in the cluster. The client can pause, resume, or cancel any ongoing software upgrade by selecting action
. The DELETE request can remove a specific software package present in the cluster.
Examples
Retrieving software profile information
The following example shows how to retrieve software profile information. The client can check the validation results after selecting 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",
"message": [
{
"code": 166,
"message": "Use NFS hard mounts, if possible.",
"arguments": [
"string"
]
}
],
"action": [
{
"code": 166,
"message": "Use NFS hard mounts, if possible.",
"arguments": [
"string"
]
}
]
}
],
"version": "9.5.0",
"pending_version": "9.6.0",
"nodes": [
{
"node": "sti70-vsim-ucs165n",
"version": "9.5.0"
}
],
"metrocluster": {
"progress_summary": "Update paused by user",
"progress_details": "Installing Data ONTAP 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",
"message": "Image update complete",
"action": "",
"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. Setting the version
field triggers the installation of the package. The client 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' to an ongoing upgrade. An upgrade can only be resumed if it is in the paused state.
The client can start the upgrade process at the cluster-level. There are no options available to start the upgrade for a specific node or HA pairs.
1. Validating the package and verifying the validation results
The following example shows how to validate a cluster software package. The client has to validate the package before the software upgrade. The client must set the validate_only
field to true
to start the validation. The client 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 and a message to indicate the progress of the job. When the job is complete and the application has been 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"
}
}
}
The client 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",
"message": "Cluster HA is not configured in the cluster. Storage failover is not enabled on node \"node1\", \"node2\".",
"action": "Check cluster HA configuration. Check storage failover status."
},
{
"update_check": "Manual checks",
"status": "warning",
"message": "Manual validation checks need to be performed. Refer to the Upgrade Advisor Plan or \"Performing manual checks before an automated cluster upgrade\" section in the \"Clustered Data ONTAP Upgrade Express Guide\" 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": "Refer to the Upgrade Advisor Plan or \"Performing manual checks before an automated cluster upgrade\" section in the \"Clustered Data ONTAP Upgrade Express Guide\" for the remaining validation checks that need to be performed before update."
}
],
"nodes": [
{
"node": "node1",
"version": "9.7.0"
},
{
"node": "node2",
"version": "9.7.0"
}
],
"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. The client must validate the package before the software upgrade starts. The client must set the skip_warnings
field to true
in order to skip any validation warnings and start the software package upgrade.
# 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 and a message to indicate the progress of the job. When the job is complete and the application has been 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"
}
}
}
The client 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
.
# 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",
"message": "Manual validation checks need to be performed. Refer to the Upgrade Advisor Plan or \"Performing manual checks before an automated cluster upgrade\" section in the \"Clustered Data ONTAP Upgrade Express Guide\" 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": "Refer to the Upgrade Advisor Plan or \"Performing manual checks before an automated cluster upgrade\" section in the \"Clustered Data ONTAP Upgrade Express Guide\" for the remaining validation checks that need to be performed before update."
}
],
"nodes": [
{
"node": "node1",
"version": "9.7.0"
},
{
"node": "node2",
"version": "9.7.0"
}
],
"pending_version": "9.7.0",
"state": "in_progress",
"elapsed_duration": 63,
"estimated_duration": 5220,
"status_details": [
{
"name": "do-download-job",
"status": "running",
"message": "",
"action": "",
"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",
"message": "",
"action": "",
"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"
}
}
}
3. Pausing/resuming/cancelling the upgrade
The following example shows how to pause
an ongoing cluster software package upgrade. The client must set the action
field to pause
, resume
, or cancel
which pauses, resumes or cancels 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 returns the job UUID, including a HAL link to retrieve details about the job. The job object includes a state and a message to indicate the progress of the job. When the job is complete and the application has been 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"
}
}
}
The client 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",
"message": "Manual validation checks need to be performed. Refer to the Upgrade Advisor Plan or \"Performing manual checks before an automated cluster upgrade\" section in the \"Clustered Data ONTAP Upgrade Express Guide\" 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": "Refer to the Upgrade Advisor Plan or \"Performing manual checks before an automated cluster upgrade\" section in the \"Clustered Data ONTAP Upgrade Express Guide\" for the remaining validation checks that need to be performed before update.",
}
],
"nodes": [
{
"node": "node1",
"version": "9.7.0"
},
{
"node": "node2",
"version": "9.7.0"
}
],
"pending_version": "9.7.0",
"state": "pause_pending",
"elapsed_duration": 103,
"estimated_duration": 5220,
"status_details": [
{
"status": "in-progress",
"message": "Installing Data ONTAP software image.",
"action": "",
"start_time": "2019-01-08T02:54:36+05:30",
"node": {
"name": "node1"
}
},
{
"status": "in-progress",
"message": "Installing Data ONTAP software image.",
"action": "",
"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 package from an HTTP or FTP server. The client provides the url
, username
, and password
to start the download of the software 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://nbsweb.eng.btc.netapp.in/~suvadipd/99/image1.tgz", "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 package returns the job UUID, including a HAL link to retrieve details about the job. The job object includes a state and a message to indicate the progress of the job. When the job is complete and the application has been 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"
}
}
}
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. The client needs to provide the package version that they 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 and a message to indicate the progress of the job. When the job is complete and the application has been 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 |
| ----------- | -------------------------------------------------------- |
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://<mgmt-ip>/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"
}
Classes
class Software (*args, **kwargs)
-
Allows interaction with Software objects on the host
Initialize the instance of the resource.
Any keyword arguments are set on the instance as properties. For example, if the class was named 'MyResource', then this statement would be true:
MyResource(name='foo').name == 'foo'
Args
*args
- Each positional argument represents a parent key as used in the URL of the object. That is, each value will be used to fill in a segment of the URL which refers to some parent object. The order of these arguments must match the order they are specified in the URL, from left to right.
**kwargs
- each entry will have its key set as an attribute name on the instance and its value will be the value of that attribute.
Ancestors
Methods
def download(self, body: typing.Union = None, poll: bool = True, poll_interval: typing.Union = None, poll_timeout: typing.Union = None, **kwargs) -> NetAppResponse
-
Downloads a software package from the server.
Required properties
url
- URL location of the software package
Recommended optional parameters
username
- Username of HTTPS/FTP serverpassword
- Password of HTTPS/FTP server
Related ONTAP commands
cluster image package get
Learn more
Perform a custom action on this resource which is not a simple CRUD action
Args
path
- The action verb for this request. This will be added as a postfix to the instance location of the resource.
body
- The body of the action request. This should be a Resource instance. The connection and URL will be determined based on the values from this object.
poll
- If set to True, the call will not return until the asynchronous job on the host has completed. Has no effect if the host did not return a job response.
poll_interval
- If the operation returns a job, this specifies how often to query the job for updates.
poll_timeout
- If the operation returns a job, this specifies how long to continue monitoring the job's status for completion.
**kwargs
- Any key/value pairs passed will be sent as query parameters to the host.
Returns
A
NetAppResponse
object containing the details of the HTTP response.Raises
NetAppRestError
: If the API call returned a status code >= 400 def get(self, **kwargs) -> NetAppResponse
-
Retrieves the software profile of a cluster.
Related ONTAP commands
cluster image show
cluster image show-update-progress
Learn more
Fetch the details of the object from the host.
Requires the keys to be set (if any). After returning, new or changed properties from the host will be set on the instance.
Returns
A
NetAppResponse
object containing the details of the HTTP response.Raises
NetAppRestError
: If the API call returned a status code >= 400 def patch(self, hydrate: bool = False, poll: bool = True, poll_interval: typing.Union = None, poll_timeout: typing.Union = None, **kwargs) -> NetAppResponse
-
Upgrades the cluster software version. Setting
version
triggers the installation of the package to start. To validate the package for installation but not perform the installation, use thevalidate_only
field on request. Important note: * Setting 'version' triggers the package installation. * To validate the package for installation but not perform the installation, use the validate_only field on the request.Required properties
version
- Software version to be installed on the cluster
Recommended optional parameters
validate_only
- Required to validate a software package before an upgradeskip_warnings
- Used to skip validation warnings when starting a software upgradeaction
- Used to pause, resume, or cancel an ongoing software upgrade
Related ONTAP commands
cluster image validate
cluster image update
cluster image pause-update
cluster image resume-update
cluster image cancel-update
Learn more
Send the difference in the object's state to the host as a modification request.
Calculates the difference in the object's state since the last time we interacted with the host and sends this in the request body.
Args
hydrate
- If set to True, after the response is received from the call, a a GET call will be made to refresh all fields of the object.
poll
- If set to True, the call will not return until the asynchronous job on the host has completed. Has no effect if the host did not return a job response.
poll_interval
- If the operation returns a job, this specifies how often to query the job for updates.
poll_timeout
- If the operation returns a job, this specifies how long to continue monitoring the job's status for completion.
**kwargs
- Any key/value pairs passed will be sent as query parameters to the host.
Returns
A
NetAppResponse
object containing the details of the HTTP response.Raises
NetAppRestError
: If the API call returned a status code >= 400
Inherited members
class SoftwareSchema (only=None, exclude=(), many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None)
-
The fields of the Software object
Ancestors
- netapp_ontap.resource.ResourceSchema
- marshmallow.schema.Schema
- marshmallow.schema.BaseSchema
- marshmallow.base.SchemaABC
Class variables
var action
-
User triggered action to apply to the install operation
Valid choices:
- pause
- cancel
- resume
var elapsed_duration
-
Elapsed time during the upgrade or validation operation
Example: 2140
var estimated_duration
-
Estimated time remaining until completion of the upgrade or validation operation.
Example: 5220
var links
-
The links field of the software.
var metrocluster
-
The metrocluster field of the software.
var nodes
-
List of nodes and active versions.
var opts
var pending_version
-
Version being installed on the system.
Example: ONTAP_X_1
var state
-
Operational state of the upgrade
Valid choices:
- in_progress
- waiting
- paused_by_user
- paused_on_error
- completed
- canceled
- failed
- pause_pending
- cancel_pending
var status_details
-
Display status details.
var update_details
-
Display update procress details.
var validation_results
-
List of validation warnings, errors, and advice.
var version
-
Version of ONTAP installed and currently active on the system. During PATCH, using the 'validate_only' parameter on the request executes pre-checks, but does not perform the full installation.
Example: ONTAP_X