English
Download PDF

Block storage APIs

Contributors ciarm netapp-manini dmp-netapp Download PDF of this page

In block storage systems, the data storage is broken up into individual pieces each with a unique identifier. NetApp Service Engine refers to the block data storage as a block store, and the individual pieces as disks.

A block store belongs to a subtenant and a zone (one block store per zone per subtenant). A block store has networking attributes (for example, IP address or VLAN ID) that are used to access disks through the iSCSI or FC protocols.

By default, block stores are enabled to use the iSCSI protocol but can be configured to use FCP if the underlying storage allows it.

Disaster recovery DP can be enabled on a block store.

Disks are created on block stores. They have many configurable attributes including capacity and associated service level. DP options, such as snapshots and disaster recovery, can be enabled for a disk.

Access to disks is controlled through host groups. Host groups consist of initiator node names; by mapping one or more host groups to a disk, you can define which initiators have access to the disk. For more information on host groups, see Host groups.

This section describes the APIs for:

  • Managing block stores (including creating and deleting block store snapshots and creating block store tags)

  • Managing disks (including creating and deleting disk snapshots and creating disk tags)

  • Managing host groups

Block stores

Use the methods listed in the following table to retrieve, create, modify, and delete block stores.

HTTP Method Path Description

GET

/v2.1/blockstores

Retrieve all block stores.

POST

/v2.1/blockstores

Create a new block store service to host disks (LUNs).

GET

/v2.1/blockstores/{id}

Retrieve a block store by ID.

PUT

/v2.1/blockstores/{id}

Modify a block store identified by ID.

DELETE

/v2.1/blockstores/{id}

Delete a block store identified by ID. All disks must be deleted before a block store can be deleted.

POST

/v2.1/blockstores/{id}/tags

Create tags on the block store identified by ID.

Block store attributes

The following table lists the block store attributes.

Attribute Type Description

id

String

The unique identifier for the block store.

subtenant_id

String

The subtenant ID of the subtenant to which the block store belongs.

zone

String

The zone name.

dr_zone

String

The disaster recovery zone name.
Optionally, specifying a disaster recovery zone name automatically replicates all storage to the disaster recovery zone.

dr_schedule

String

The disaster recovery schedule can be one of (hourly, four-hourly, or daily).

subnet

String

The Classless Inter-Domain Routing (CIDR) notation of a subnet.

vlan_id

String

The VLAN ID.

service_iscsi_enabled

Boolean

Indicates if the iSCSI protocol is available on the block store; always set to true.

service_fcp_enabled

Boolean

Indicates if the FCP is enabled on the block store; disabled by default.

fcp_target_wwpns

Boolean

A list of worldwide port names (WWPNs) assigned to the FC ports; the WWPNs are returned when creating an FC-enabled block store.

Retrieve block stores

Use the method listed in the following table to retrieve all block stores or a subset of block stores. Specifying a tenant_id returns only the block stores belonging to that tenant.

HTTP Method Path Description Path Parameters

GET

/v2.1/blockstores

Retrieve all block stores.

tenant_id: (Optional) The return of block stores belonging to the specified tenant.
offset and limit– see Pagination

Required request body parameters: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "total_records": 9,
    "sort_by": "created",
    "order_by": "desc",
    "offset": 1,
    "limit": 1,
    "records": [
      {
        "id": "5f17b628226194000187f1af",
        "ip_addrs": [
          "10.0.0.2",
          "10.0.0.3"
        ],
        "state": "Operational",
        "region": "au-west1",
        "zone": "au-west1-a",
        "dr_available": true,
        "dr_zone": "au-east1-a",
        "dr_schedule": "hourly",
        "tenant": "MyTenant",
        "tenant_id": "5e7c3af7aab46c00014ce877",
        "subtenant": "test5678",
        "subtenant_id": "5f1652917be47e00014877c0",
        "vlan_id": "4019",
        "subnet": "10.0.0.0/24",
        "tags": [],
        "dr_zones_available": [
          "au-east1-a",
          "au-east2-a",
          "au-east1-b",
          "au-east1-fcp"
        ],
        "created": "2020-07-22T03:44:40.978Z",
        "updated": "2020-07-22T03:44:40.978Z",
        "service_iscsi_enabled": true,
        "service_fcp_enabled": false,
        "fcp_target_wwpns": []
      }
    ]
  }
}

Retrieve block store by ID

Use the method listed in the following table to retrieve a block store by its identifier.

HTTP Method Path Description Parameters

GET

/v2.1/blockstores/{id}

Retrieve a block store by ID.

id (string): The unique identifier of the block store.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "total_records": 76,
    "sort_by": "created",
    "order_by": "desc",
    "offset": 1,
    "limit": 1,
    "records": [
      {
        "id": "5f348a2b28a18f0001751e40",
        "ip_addrs": [
          "10.2.2.2",
          "10.2.2.3"
        ],
        "state": "Operational",
        "region": "au-east1",
        "zone": "au-east1-fcp",
        "dr_available": false,
        "dr_zone": "",
        "dr_schedule": "",
        "tenant": "AppleInc",
        "tenant_id": "5e3b9e64f24dd2a020b28029",
        "subtenant": "test345",
        "subtenant_id": "5f1453ff7be47e00014868e4",
        "vlan_id": "1020",
        "subnet": "10.2.2.5/24",
        "tags": [],
        "dr_zones_available": [
          "au-east1-a",
          "au-east2-a",
          "au-west1-a",
          "au-east1-b"
        ],
        "created": "2020-08-13T00:32:43.336Z",
        "updated": "2020-08-13T00:32:43.336Z",
        "service_iscsi_enabled": true,
        "service_fcp_enabled": true,
        "fcp_target_wwpns": [
          "20:51:00:a0:98:5c:0d:da",
          "20:52:00:a0:98:5c:0d:da",
          "20:53:00:a0:98:5c:0d:da",
          "20:54:00:a0:98:5c:0d:da"
        ]
      }
    ]
  }
}

Create block stores

Use the method listed in the following table to create a new block store instance to host disks (LUNs). Block stores always have the iSCSI service enabled. Optionally, you can enable the FCP service if the infrastructure allows it.

HTTP Method Path Description Parameters

POST

/v2.1/blockstores

Create a block store.

None

Required request body attributes: tenant_id, subtenant_id, zone, subnet, vlan_id

Set service_fcp_enabled to true to enable FCP (only possible if the underlying infrastructure allows it).

Optionally, specify a disaster recovery zone name (dr_zone) to allow replication of all storage to the disaster recovery zone.

Request body example:

{
  "service_fcp_enabled": false,
  "subtenant_id": "5e7c3af8aab46c00014ce878",
  "zone": "au-east1-a",
  "dr_zone": "",
  "dr_schedule": "hourly",
  "subnet": "10.0.0.0/24",
  "vlan_id": "2257",
  "tags": {
    "keyA": "Value A",
    "keyB": "Value B"
  }
}

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f34a1da28a18f0001751fa8",
        "action": "create",
        "job_summary": "Create request is successfully submitted.",
        "created": "2020-08-13T02:13:46.701170043Z",
        "updated": "2020-08-13T02:13:46.701170043Z",
        "object_id": "5f34a1da28a18f0001751fa7",
        "type": "blockstore",
        "object_name": "5e7c3af8aab46c00014ce878_au-east1-a",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ee183fec41b7b000198b50f",
        "job_tasks": null
      }
    ]
  }
}

Modify block store by ID

Use the method listed in the following table to modify the block store identified by ID. You can:

Enable disaster recovery on a block store.

You cannot disable disaster recovery on a block store it is has previously been enabled.

  • Modify the disaster recovery schedule.

HTTP Method Path Description Parameters

PUT

/v2.1/blockstores/{id}

Modify the block store by ID.

id (string): The unique identifier of the block store.

Required request body attributes: none

Request body example:

{
  "dr_zone": "",
  "dr_schedule": "hourly",
  "tags": {
    "keyC": "Value C"
  }
}

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f34a52f28a18f0001751fd7",
        "action": "update",
        "job_summary": "Update request is successfully submitted.",
        "created": "2020-08-13T02:27:59.052573375Z",
        "updated": "2020-08-13T02:27:59.052573375Z",
        "object_id": "5f34a1da28a18f0001751fa7",
        "type": "blockstore",
        "object_name": "5e7c3af8aab46c00014ce878_au-east1-a",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ee183fec41b7b000198b50f",
        "job_tasks": null
      }
    ]
  }
}

Delete a block store

Use the method listed in the following table to delete the block store by ID.

Before you attempt to delete the block store, make sure that any disks that might have been on the block store have been deleted.

HTTP Method Path Description Parameters

DELETE

/v2.1/blockstores/{id}

Delete the block store by ID.

id (string): The unique identifier of the block store.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f34a66628a18f0001751ff6",
        "action": "delete",
        "job_summary": "Delete request is successfully submitted.",
        "created": "2020-08-13T02:33:10.004482872Z",
        "updated": "2020-08-13T02:33:10.004482872Z",
        "object_id": "5f34a1da28a18f0001751fa7",
        "type": "blockstore",
        "object_name": "5e7c3af8aab46c00014ce878_au-east1-a",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ee183fec41b7b000198b50f",
        "job_tasks": null
      }
    ]
  }

Create tags on a block store

Use the method listed in the following table to create tags on a block store.

HTTP Method Path Description Parameters

POST

/v2.1/blockstores/{id}/tags

Create tags on the block store by ID.

Tags

Required request body attributes: tags as key-value pairs

Request body example:

{
  "keyA": "Value A",
  "keyB": "Value B",
  "keyC": "Value C"
}

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 3 records.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 3,
    "records": [
      {
        "key": "keyA",
        "value": "Value A"
      },
      {
        "key": "keyB",
        "value": "Value B"
      },
      {
        "key": "keyC",
        "value": "Value C"
      }
    ]
  }
}

Disks

Use the methods listed in the following table to retrieve, create, modify, and delete disks.

HTTP Method Path Description

GET

/v2.1/disks

Retrieve all disks.

POST

/v2.1/disks

Creates a new disk.

GET

/v2.1/disks/{id}

Retrieve disk by ID.

PUT

/v2.1/disks/{id}

Modify disk.

DELETE

/v2.1/disks/{id}

Delete disk.

POST

/v2.1/disks/{id}/snapshot/{name}

Create snapshot.

DELETE

/v2.1/disks/{id}/snapshot/{name}

Delete snapshot.

POST

/v2.1/disks/{id}/tags

Create tags.

Disk attributes

The following table lists the disk attributes.

Attribute Type Description

id

string

The ID of the disk.

subtenant_id

String

Subtenant ID of the subtenant to which the block store belongs.

zone

String

Zone name.

name

String

Disk name.

disk_path

String

Disk path.

protocol

String

Storage protocol for block device access.
Options: iSCSI, FCP.

os_type

String

Host operating system type: one of Windows, Linux, Solaris, or VMware.

hostgroup_mappings

Array

Array of host group names mapped or to be mapped to the disk. When mapping host groups to disks, the host group type (iSCSI or FC) must match the disk protocol.
For example:

"hostgroup_mappings": [
    "ExistingHG", "myhg1"
  ]

hostgroups

Used to define new host groups when creating or modifying disks. For more information on host groups, see Host groups.

Example:
"hostgroups": [
    {
      "name": "NewHG",
      "initiators": [
        {
          "alias": "ServerDE",
          "initiator": "iqn.1988-03.com.myname:abc18"
        },
        {
          "alias": "ServerHK",
          "initiator": "iqn.1988-03.com.myname:abc20"
        }
      ]
    }
  ]

service_level

String

Service level name: Standard, Premium, or Extreme.

size_gb

Integer

The size of the share or disk.

snapshot_policy

String

The snapshot policy. If enabled, create snapshots automatically according to the schedules.
For example:

"snapshot_policy": {
    "enabled": true,
    "hourly_schedule": {
      "minute": 10,
      "snapshots_to_keep": 24
    },
    "daily_schedule": {
      "hour": "4",
      "minute": 10,
      "snapshots_to_keep": 7
    },
    "weekly_schedule": {
      "day_of_week": 5,
      "hour": 23,
      "minute": 10,
      "snapshots_to_keep": 52
    },
    "monthly_schedule": {
      "day_of_month": 15,
      "hour": 23,
      "minute": 10,
      "snapshots_to_keep": 12
    }
  }

backup_policy

String

Backup policy for the disk. Must be enabled to allow backups. When enabled, backups occur around 0:00 UTC. The backup policy defines the number of backups of each type retained.
For example:

"backup_policy": {
    "enabled": false,
    "backup_zone": "au-west1-a",
    "daily_backups_to_keep": 7,
    "weekly_backups_to_keep": 4,
    "monthly_backups_to_keep": 12,
    "adhoc_backups_to_keep": 10
  }

dr_enabled

Boolean

Enable disaster recovery replication to a different zone.

clone_from_disk_id

String

Disk ID.

clone_from_snapshot_name

String

Snapshot name.

Retrieve all disks

Use the method listed in the following table to retrieve all disks or a subset of all disks. Specifying a tenant_id returns only the disks belonging to that tenant.

HTTP Method Path Description Parameters

GET

/v2.1/disks

Retrieve all disks.

tenant_id: (Optional) The return of disks belonging to the specified tenant.
offset and limit (see Pagination)

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "total_records": 26,
    "sort_by": "created",
    "order_by": "desc",
    "offset": 0,
    "limit": 1,
    "records": [
      {
        "id": "5f3f2f9661485800017102d6",
        "blockstore_id": "5f3ccfbbf84c3f000191d9ab",
        "name": "BlueDisk5",
        "disk_path": "pathtobluedisk5",
        "protocol": "iscsi",
        "os_type": "windows",
        "hostgroup_mappings": [
          {
            "id": "5f3e12c86148580001710265",
            "name": "ExistingHG",
            "initiators": [
              {
                "alias": "ServerEX",
                "initiator": "iqn.1988-03.com.myname:abc12"
              },
              {
                "alias": "ServerHY",
                "initiator": "iqn.1988-03.com.myname:abc14"
              }
            ]
          },
          {
            "id": "5f3f174861485800017102c3",
            "name": "NewHG",
            "initiators": [
              {
                "alias": "ServerDE",
                "initiator": "iqn.1988-03.com.myname:abc18"
              },
              {
                "alias": "ServerHK",
                "initiator": "iqn.1988-03.com.myname:abc20"
              }
            ]
          }
        ],
        "service_level": "standard",
        "size_gb": 20,
        "state": "Operational",
        "ip_addrs": null,
        "snapshots": [],
        "snapshot_policy": {
          "enabled": false,
          "hourly_schedule": {
            "job_schedule_name": "hourly-0-min-past-hour",
            "snapshots_to_keep": 0,
            "minute": 0
          },
          "daily_schedule": {
            "job_schedule_name": "daily-0-min-past-",
            "hour": "0",
            "minute": 0,
            "snapshots_to_keep": 0
          },
          "weekly_schedule": {
            "job_schedule_name": "weekly-on-sunday-0-min-past-12am",
            "hour": 0,
            "minute": 0,
            "day_of_week": 0,
            "snapshots_to_keep": 0
          },
          "monthly_schedule": {
            "job_schedule_name": "monthly-on-day-1-0-min-past-12am",
            "hour": 0,
            "minute": 0,
            "day_of_month": 1,
            "snapshots_to_keep": 0
          }
        },
        "backup_policy": {
          "enabled": false,
          "backup_zone": "",
          "daily_backups_to_keep": 0,
          "weekly_backups_to_keep": 0,
          "monthly_backups_to_keep": 0,
          "adhoc_backups_to_keep": 0
        },
        "region": "NewZealand",
        "zone": "dev-nz-aff-97-cl1",
        "tenant": "Ferrier",
        "tenant_id": "5f335bf8a3cedf00018d442e",
        "subtenant": "MySubtenant",
        "subtenant_id": "5f3c54fcf84c3f000191d852",
        "tags": [],
        "dr_available": false,
        "dr_enabled": false,
        "dr_zone": "",
        "backups": [],
        ],
        "created": "2020-08-21T02:21:10.307Z",
        "updated": "2020-08-21T02:42:20.316Z"
      }
    ]
  }
}

Retrieve disk by ID

Use the method listed in the following table to retrieve a disk by ID.

HTTP Method Path Description Parameters

GET

/v2.1/disks/{id}

Retrieve a disk by ID.

id (string): The unique identifier of the disk.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f3cd4daf84c3f000191d9d7",
        "blockstore_id": "5f3ccfbbf84c3f000191d9ab",
        "name": "MyDisk30",
        "disk_path": "pathtomydisk30",
        "protocol": "fcp",
        "os_type": "linux",
        "hostgroup_mappings": [
          {
            "id": "5f3cd4daf84c3f000191d9d8",
            "name": "MyNewHG",
            "initiators": [
              {
                "alias": "ServerA",
                "initiator": "20:7f:00:a0:98:5c:0d:da"
              }
            ]
          }
        ],
        "service_level": "premium",
        "size_gb": 10,
        "state": "Operational",
        "ip_addrs": null,
        "snapshots": [],
        "snapshot_policy": {
          "enabled": false,
          "hourly_schedule": {
            "job_schedule_name": "hourly-10-min-past-hour",
            "snapshots_to_keep": 24,
            "minute": 10
          },
          "daily_schedule": {
            "job_schedule_name": "daily-10-min-past-4am",
            "hour": "4",
            "minute": 10,
            "snapshots_to_keep": 7
          },
          "weekly_schedule": {
            "job_schedule_name": "weekly-on-friday-10-min-past-11pm",
            "hour": 23,
            "minute": 10,
            "day_of_week": 5,
            "snapshots_to_keep": 52
          },
          "monthly_schedule": {
            "job_schedule_name": "monthly-on-day-15-10-min-past-11pm",
            "hour": 23,
            "minute": 10,
            "day_of_month": 15,
            "snapshots_to_keep": 12
          }
        },
        "backup_policy": {
          "enabled": false,
          "backup_zone": "",
          "daily_backups_to_keep": 0,
          "weekly_backups_to_keep": 0,
          "monthly_backups_to_keep": 0,
          "adhoc_backups_to_keep": 0
        },
        "region": "NewZealand",
        "zone": "dev-nz-aff-97-cl1",
        "tenant": "Ferrier",
        "tenant_id": "5f335bf8a3cedf00018d442e",
        "subtenant": "MySubtenant",
        "subtenant_id": "5f3c54fcf84c3f000191d852",
        "tags": [],
        "dr_available": false,
        "dr_enabled": false,
        "dr_zone": "",
        "backups": [],
        "backup_zones_available": [
          "dev-cl1-97-zone1",
          "dev-aus-bri-97-cl1",
          "dev-nz-per-96-cl1"
        ],
        "created": "2020-08-19T07:29:30.693Z",
        "updated": "2020-08-19T07:29:30.693Z"
      }

Create disks

Use the method listed in the following table to create a new disk.

HTTP Method Path Description Parameters

POST

/v2.1/disks

Create a new disk.

None

Required request body attributes: subtenant_id, zone, name, disk_path, protocol, os_type, hostgroup_mappings, service_level, size_gb

Request body (example 1):

This example creates a new disk that uses the FC protocol. The disk is created without snapshots, backups or disaster recover DP enabled.

A new host group is created as part of the process and mapped to the disk. It is created under the same block store and have the same os_type, protocol, and tenancy as the disk being created. The new host group:

  • Is defined in the host groups block and has a name and one initiator. Because this is an FC host group and an alias, the initiator consists of a WWPN.

"hostgroups":
[    {      "name": "MyNewHG",       "initiators": [        {          "alias": "ServerA",           "initiator": "20:7f:00:a0:98:5c:0d:da"        }      ]    }  ]
Is mapped to the disk through `hostgroup_mappings`:   "hostgroup_mappings": [    "MyNewHG"  ]
{
  "subtenant_id": "5f3c54fcf84c3f000191d852",
  "zone": "dev-nz-aff-97-cl1",
  "name": "MyDisk30",
  "disk_path": "pathtomydisk30",
  "protocol": "fcp",
  "os_type": "linux",
  "hostgroup_mappings": [
    "MyNewHG"
  ],
  "hostgroups": [
    {
      "name": "MyNewHG",
      "initiators": [
        {
          "alias": "ServerA",
          "initiator": "20:7f:00:a0:98:5c:0d:da"
        }
      ]
    }
  ],
  "service_level": "premium",
  "size_gb": 10,
  "snapshot_policy": {
    "enabled": false,
    "hourly_schedule": {
      "minute": 10,
      "snapshots_to_keep": 24
    },
    "daily_schedule": {
      "hour": "4",
      "minute": 10,
      "snapshots_to_keep": 7
    },
    "weekly_schedule": {
      "day_of_week": 5,
      "hour": 23,
      "minute": 10,
      "snapshots_to_keep": 52
    },
    "monthly_schedule": {
      "day_of_month": 15,
      "hour": 23,
      "minute": 10,
      "snapshots_to_keep": 12
    }
  },
  "backup_policy": {
    "enabled": false,
    "backup_zone": "au-west1-a",
    "daily_backups_to_keep": 7,
    "weekly_backups_to_keep": 4,
    "monthly_backups_to_keep": 12,
    "adhoc_backups_to_keep": 10
  },
  "dr_enabled": false
}

Response body (example 1):

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f3cd4daf84c3f000191d9d9",
        "action": "create",
        "job_summary": "Create request is successfully submitted.",
        "created": "2020-08-19T07:29:30.734720333Z",
        "updated": "2020-08-19T07:29:30.734720333Z",
        "object_id": "5f3cd4daf84c3f000191d9d7",
        "type": "disk",
        "object_name": "MyDisk30",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5f39e418ebdbd30001583a4e",
        "job_tasks": null
      }
    ]
  }
}

Request body (example 2):

This example creates a new disk from a snapshot of an existing disk. The disk protocol is iSCSI and is mapped to an existing (iSCSI) host group. If the host group mapping is not specified, the cloned disk inherits the host group mapping from the snapshot.

{
  "subtenant_id": "5f3c54fcf84c3f000191d852",
  "zone": "dev-nz-aff-97-cl1",
  "name": "MyClonedDisk",
  "disk_path": "pathtoMyClonedDisk",
  "protocol": "iscsi",
  "os_type": "windows",
  "hostgroup_mappings": [
    "ExistingHG"
  ],
  "service_level": "standard",
  "size_gb": 10,
 "clone_from_disk_id": "5f3f0ada61485800017102b7",
  "clone_from_snapshot_name": "BD4Snapshot"
}

Response body (example 2):

{
  "status": {
    "user_message": "Hostgroup 'ExistingHG' with ID '5f3e12c86148580001710265' is in an 'Operational' state.",
    "verbose_message": "Hostgroup 'ExistingHG' with ID '5f3e12c86148580001710265' is in an 'Operational' state.",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f3f66c7dafa0a00013cf072",
        "action": "create",
        "job_summary": "Create request is successfully submitted.",
        "created": "2020-08-21T06:16:39.154323458Z",
        "updated": "2020-08-21T06:16:39.154323458Z",
        "object_id": "5f3f66c7dafa0a00013cf071",
        "type": "disk",
        "object_name": "MyClonedDisk",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5f39d6efebdbd30001583a49",
        "job_tasks": null
      }
    ]
  }
}

Modify disk by ID

Use the method listed in the following table to modify the disk details by ID. You can modify the disk name, service level, size, host group mapping, snapshot policy, and backup policy. If the disk exists on a block store that is disaster-recovery enabled, you can enable disaster recovery. You cannot disable disaster recovery.

You cannot modify the protocol (iSCSI or FCP) in use for the disk.

You can also create a new host group, populate it with initiators and map it to the disk. For more information on host groups, see Host groups.

HTTP Method Path Description Parameters

PUT

/v2.1/disks/{id}

Modify the disk by ID.

id (string): The unique identifier of the disk.

Required request body attributes: none

Request body (example 1):

In this example, the request modifies the name and size of the disk and disables the snapshot policy.

  "name": "BlueDisk4NewName",
  "service_level": "standard",
  "size_gb": 40,
  "snapshot_policy": {
    "enabled": false,
    "hourly_schedule": {
      "minute": 10,
      "snapshots_to_keep": 24
    },
    "daily_schedule": {
      "hour": "4",
      "minute": 10,
      "snapshots_to_keep": 7
    },
    "weekly_schedule": {
      "day_of_week": 5,
      "hour": 23,
      "minute": 10,
      "snapshots_to_keep": 52
    },
    "monthly_schedule": {
      "day_of_month": 15,
      "hour": 23,
      "minute": 10,
      "snapshots_to_keep": 12
    }
  }
}

Response body (example 1):

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f3f11aa61485800017102bd",
        "action": "update",
        "job_summary": "Update request is successfully submitted",
        "created": "2020-08-21T00:13:30.675663871Z",
        "updated": "2020-08-21T00:13:30.675663871Z",
        "object_id": "5f3f0ada61485800017102b7",
        "type": "disk",
        "object_name": "BlueDisk4",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5f39d6efebdbd30001583a49",
        "job_tasks": null
      }
    ]
  }
}

Request body (example 2):

In this example, the request maps the disk to two host groups: ExistingHG and NewHG. NewHG is a new (iSCSI) host group that is defined as part of this request with two initiators with aliases ServerDE and Server HK.

{
  "name": "BlueDisk4",
  "hostgroup_mappings": [
    "ExistingHG", "NewHG"
  ],
  "hostgroups": [
    {
      "name": "NewHG",
      "initiators": [
        {
          "alias": "ServerDE",
          "initiator": "iqn.1988-03.com.myname:abc18"
        },
        {
          "alias": "ServerHK",
          "initiator": "iqn.1988-03.com.myname:abc20"
        }
      ]
    }
  ]
}

Response body (example 2):

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f3f174861485800017102c4",
        "action": "update",
        "job_summary": "Update request is successfully submitted",
        "created": "2020-08-21T00:37:28.783778539Z",
        "updated": "2020-08-21T00:37:28.783778539Z",
        "object_id": "5f3f0ada61485800017102b7",
        "type": "disk",
        "object_name": "BlueDisk4NewName",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5f39d6efebdbd30001583a49",
        "job_tasks": null
      }
    ]
  }
}

Delete a disk

Use the method listed the following table to delete a disk.

HTTP Method Path Description Parameters

DELETE

`/v2.1/disks/{id}

Delete the disk by ID.

id (string): The unique identifier of the disk.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f3f49ef61485800017102f9",
        "action": "delete",
        "job_summary": "Delete request is successfully submitted",
        "created": "2020-08-21T04:13:35.365998668Z",
        "updated": "2020-08-21T04:13:35.365998668Z",
        "object_id": "5f3e24326148580001710282",
        "type": "disk",
        "object_name": "DiskToBeDeleted",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5f39d6efebdbd30001583a49",
        "job_tasks": null
      }
    ]
  }
}

Create tags on a disk

Use the method listed in the following table to create tags on a disk.

HTTP Method Path Description Parameters

POST

/v2.1/disks/{id}/tags

Create tags on the disk identified by ID.

id (string): The unique identifier of the disk.

Required request body attributes: tags of key value pair attributes

Request body example:

{
  "key8": "Value 8",
  "key9": "Value 9"
}

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 2 records.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 2,
    "records": [
      {
        "key": "key8",
        "value": "Value 8"
      },
      {
        "key": "key9",
        "value": "Value 9"
      }
    ]
  }
}

Create a snapshot of a disk

Use the method listed in the following table to create a snapshot of a disk.

HTTP Method Path Description Parameters

POST

/v2.1/disks/{id}/snapshot/{name}

Create a snapshot of the named disk.

id (string): The ID of the disk of which to create the snapshot.
name (string): The name of the snapshot.

  • Required request body attributes: none

  • Optional attributes: snapmirror_label (string)

This is the label applied to the snapshot and can be one of: hourly, daily, weekly, or monthly.

Request body example:

{
  "snapmirror_label": "hourly"
}

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5ed5d91d2c356a0001a736f9",
        "action": "create",
        "job_summary": "Snapshot creation request on Ontap Disk is successfully submitted",
        "created": "2020-06-02T04:44:13.171615393Z",
        "updated": "2020-06-02T04:44:13.171615393Z",
        "object_id": "5ed5ce262c356a0001a736bc",
        "object_type": "ontap_disks",
        "object_name": "MyNewDiskstring",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ec626c0f038943eb46b0af1",
        "job_tasks": null
      }
    ]
  }
}

Delete the snapshot of a disk

Use the method listed in the following table to delete the snapshot of a disk.

HTTP Method Path Description Parameters

DELETE

/v2.1/disks/{id}/snapshot/{name}

Delete the snapshot with the name {name} of the disk identified by ID.

  • id (string): The ID of the disk.

  • name (string): The name of the snapshot.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5ed5dbf12c356a0001a73720",
        "action": "delete",
        "job_summary": "Delete Snapshot request is successfully submitted",
        "created": "2020-06-02T04:56:17.642297535Z",
        "updated": "2020-06-02T04:56:17.642297535Z",
        "object_id": "5ed5ce262c356a0001a736bc",
        "object_type": "ontap_disks",
        "object_name": "MySnapshot1",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ec626c0f038943eb46b0af1",
        "job_tasks": null
      }
    ]
  }
}

Host groups

Access control to disks is managed with host groups. Host groups are groups of initiator node names; by mapping one or more host groups to a disk, you can define which initiators have access to the disk.

Host groups are protocol specific. They can be either:

  • FC protocol host groups: these consist of initiators that are FC WWPNs; for example, 20:56:00:a0:98:5c:0d:da.

  • iSCSI protocol host groups: these consist of initiators that are iSCSI qualified names (IQNs); for example, iqn.1998-01.com.vmware:esx2).Each initiator in a host group is associated with an alias. The alias allows a simple way to identify the initiator (for example, esxserver1).

Empty host groups (without any initiators) can be created and mapped to the disks as placeholders; these must be fully defined to allow access to the disks.

Host groups are mapped to disks when a disk is created or modified. For more information, see Create Disks or Modify Disk by ID. It is possible to create and populate new host groups as part of these processes.

Use the methods listed the following table to perform the following tasks:

  • Retrieve, create, modify, and delete host groups

  • Add, remove, or modify initiators in a host group

HTTP Method Path Description

GET

/v2.1/hostgroups

Retrieve all host groups.

POST

/v2.1/hostgroups

Creates a new host group

GET

/v2.1/hostgroups/{id}

Retrieve a host group by ID

DELETE

/v2.1/hostgroups/{id}

Deleted a host group by ID.

POST

/v2.1/hostgroup/{id}/tags

Create tags on a host group.

GET

/v2.1/hostgroups/{id}/initiators

Retrieve the initiators in a host group.

POST

/v2.1/hostgroups/{id}/initiators

Add an initiator to a host group.

GET

/v2.1/hostgroups/{id}/initiators/{alias}

Retrieve an initiator from a host group by the initiator’s alias.

PATCH

/v2.2/hostgroups/{id}/initiators/{alias}`

Modify the initiator matching the specified alias in a host group

DELETE

/v2.1/hostgroup/{id}/initiators/{alias }

Delete a single initiator from a host group

Host group attributes

The following table lists the host group attributes.

Attribute Type Description

id

String

The subtenant ID of the subtenant to which the block store belongs.

name

String

The host group name.

subtenant

String

The name of the subtenant to which the host group belongs.

subtenant_id

String

The ID of the subtenant to which the host group belongs.

blockstore_id

String

The ID of the block store to which the host group belongs.

zone`

String

The zone name.

protocol

String

The protocol for host group. Options: iSCSI, FCP.

os_type

String

Host operating system type: one of Windows, Linux, or VMware.

initiators

–

The initiators and their aliases that are defined for the host group.
For host groups of type iSCSI, the initiators are iSCSI Qualified Names (IQNs).
For host groups of type FCP, the initiators are FC WWPNs.
Each initiator has an alias to simplify identification of the initiator.
For example:

},
{
   "alias" : "esxserver1",
   "initiator": "iqn.1998-01.com.vmware:esx1"
},
{
   "alias" : "esxserver2",
   "initiator": "iqn.1998-01.com.vmware:esx2"
}

tags

–

Key-value pairs.

Retrieve host groups

Use the method listed in the following table to retrieve all host groups or a subset of all host groups. Specifying a tenant_id will return only the host groups belonging to that tenant.

HTTP Method Path Description Parameters

GET

/v2.1/hostgroups

Retrieve all host groups.

tenant_id: (Optional) The return the host groups belonging to the specified tenant.
offset and limit (see Pagination)

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "total_records": 3,
    "sort_by": "created",
    "order_by": "desc",
    "offset": 1,
    "limit": 1,
    "records": [
      {
        "id": "5f34ab8c28a18f0001752031",
        "name": "MyHostGroupA",
        "protocol": "iscsi",
        "os_type": "linux",
        "initiators": [
          {
            "alias": "myserverA",
            "initiator": "iqn.1987-05.com.redhat:rhel7"
          }
        ],
        "state": "Operational",
        "tenant": "MyTenant",
        "tenant_id": "5e7c3af7aab46c00014ce877",
        "subtenant": "MySubtenant",
        "subtenant_id": "5e7c3af8aab46c00014ce878",
        "blockstore_id": "5f34a6fd28a18f0001751fff",
        "region": "au-east1",
        "zone": "au-east1-a",
        "disks": [
          {
            "id": "5f43254d07179f000185c7fd",
            "name": "MyDisk",
            "state": "Operational"
          }
        ],
        "tags": [
          {
            "key": "keyA",
            "value": "Value A"
          },
          {
            "key": "keyB",
            "value": "Value B"
          }
        ],
        "created": "2020-08-13T02:55:08.879Z",
        "updated": "2020-08-13T02:55:08.879Z"
      }
    ]
  }
}

Retrieve host group by ID

Use the method listed in the following table to retrieve a host group by ID.

HTTP Method Path Description Parameters

GET

/v2.1/hostgroups

Retrieve a host group by ID.

id: (string): The unique identifier of the host group.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f34aaf728a18f0001752025",
        "name": "MyHostGroupA",
        "protocol": "iscsi",
        "os_type": "linux",
        "initiators": [
          {
            "alias": "myserverA",
            "initiator": "iqn.1987-05.com.redhat:rhel7"
          }
        ],
        "state": "Operational",
        "tenant": "MyTenant",
        "tenant_id": "5e7c3af7aab46c00014ce877",
        "subtenant": "MySubtenant",
        "subtenant_id": "5e7c3af8aab46c00014ce878",
        "blockstore_id": "5f34a6fd28a18f0001751fff",
        "region": "au-east1",
        "zone": "au-east1-a",
        "disks": [
          {
            "id": "5f43254d07179f000185c7fd",
            "name": "MyDisk",
            "state": "Operational"
          }
        ],
        "tags": [
          {
            "key": "keyA",
            "value": "Value A"
          },
          {
            "key": "keyB",
            "value": "Value B"
          }
        ],
        "created": "2020-08-13T02:52:39.768Z",
        "updated": "2020-08-13T02:52:39.768Z"
      }
    ]
  }
}

Delete a host group by ID

Use the method listed in the following table to delete a host group.

HTTP Method Path Description Parameters

DELETE

/v2.1/hostgroups/{id}

Delete the host group identified by ID.

id (string): The unique identifier of the host group.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f34ab6128a18f000175202c",
        "action": "delete",
        "job_summary": "Delete request is successfully submitted",
        "created": "2020-08-13T02:54:25.26950383Z",
        "updated": "2020-08-13T02:54:25.26950383Z",
        "object_id": "5f34aaf728a18f0001752025",
        "type": "hostgroup",
        "object_name": "MyHostGroupA",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ee183fec41b7b000198b50f",
        "job_tasks": null
      }
    ]
  }
}

Create tags on a host group

Use the method listed in the following table to create tags on a host group.

HTTP Method Path Description Parameters

POST

/v2.1/hostgroups/{id}/tags

Create tags on the host group identified by ID.

id (string): The unique identifier of the host group.

Required request body attributes: tags as key-value pairs.

Request body example:

{
  "keyA": "Value A",
  "keyZ": "Value Z"
}

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 2 records.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 2,
    "records": [
      {
        "key": "keyZ",
        "value": "Value Z"
      },
      {
        "key": "keyA",
        "value": "Value A"
      }
    ]
  }
}

Retrieve the initiators in a host group

Use the method listed in the following table to retrieve the initiators in the host group identified by ID.

HTTP Method Path Description Parameters

GET

/v2.1/hostgroups/{id}/initiators

Retrieve the initiators in the host group identified by ID.

id: (string): The unique identifier of the host group.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "alias": "myserverA",
        "initiator": "iqn.1987-05.com.redhat:rhel7"
      }
    ]
  }
}

Add an initiator to a host group

Use the method listed in the following table to retrieve the initiators in a host group.

When adding initiators to a host group, the initiator must match the host group protocol: use IQNs for host groups with the iSCSI protocol, and WWPNs for host groups with the FC protocol.

HTTP Method Path Description Parameters

POST

/v2.1/hostgroups/{id}/initiators

Create an initiator in the host group identified by ID.

id: (string). The unique identifier of the host group.

Required request body attributes: alias, initiator

Request body example:

{
  "alias": "myserverB",
  "initiator": "20:58:00:a0:98:5c:0d:da"
}

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f34b2ab7d648c000178ea9d",
        "action": "update",
        "job_summary": "Create request is successfully submitted",
        "created": "2020-08-13T03:25:31.501807376Z",
        "updated": "2020-08-13T03:25:31.501807376Z",
        "object_id": "5f34ad3728a18f000175204b",
        "type": "hostgroup",
        "object_name": "MyHostGroupB",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ee183fec41b7b000198b50f",
        "job_tasks": null
      }
    ]
  }
}

Retrieve an initiator by alias from within a host group

Use the method listed in the following table to retrieve the initiator matching the provided alias from within the host group identified by ID.

HTTP Method Path Description Parameters

GET

/v2.1/hostgroups/{id}/initiators

Create an initiator in the host group identified by ID.

id: (string): The unique identifier of the host group.
alias (string): The alias of the initiator.

Required request body attributes: none

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Returned 1 record.",
    "verbose_message": "",
    "code": 200
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "initiator": "20:58:00:a0:98:5c:0d:da"
      }
    ]
  }

Modify an initiator in a host group

Use the method listed in the following table to retrieve the initiator matching the provided alias from within the host group identified by ID.

HTTP Method Path Description Parameters

PATCH

/v2.1/hostgroups/{id}/initiators/{alias}

Modify the initiator specified by the alias in the host group identified by ID.

id: (string): The unique identifier of the host group.
alias (string): The alias of the initiator.

Required request body attributes: none

Request body example:

{
  "initiator": "20:59:00:a0:98:5c:0d:da"
}

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f34b4b77d648c000178eac2",
        "action": "update",
        "job_summary": "Update request is successfully submitted",
        "created": "2020-08-13T03:34:15.569114799Z",
        "updated": "2020-08-13T03:34:15.569114799Z",
        "object_id": "5f34ad3728a18f000175204b",
        "type": "hostgroup",
        "object_name": "MyHostGroupB",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ee183fec41b7b000198b50f",
        "job_tasks": null
      }
    ]
  }
}

Remove an initiator from a host group

Use the method listed in the following table to remove an initiator from the host group identified by ID.

Removing an initiator from a host group affects all disks to which the host group is mapped.

HTTP Method Path Description Parameters

DELETE

/v2.1/hostgroups/{id}/initiators/{alias}

Remove the initiator specified by the alias from the host group identified by ID.

id: (string): The unique identifier of the host group.
alias (string): The alias of the initiator.

Required request body attributes: none.

Request body example:

none

Response body example:

{
  "status": {
    "user_message": "Okay. Accepted for processing.",
    "verbose_message": "",
    "code": 202
  },
  "result": {
    "returned_records": 1,
    "records": [
      {
        "id": "5f34b6037d648c000178eac7",
        "action": "update",
        "job_summary": "Delete request is successfully submitted",
        "created": "2020-08-13T03:39:47.821098353Z",
        "updated": "2020-08-13T03:39:47.821098353Z",
        "object_id": "5f34ad3728a18f000175204b",
        "type": "hostgroup",
        "object_name": "MyHostGroupB",
        "status": "pending",
        "status_detail": "",
        "last_error": "",
        "user_id": "5ee183fec41b7b000198b50f",
        "job_tasks": null
      }
    ]
  }
}
CONTRIBUTE
Edit on GitHub Request doc changes Contributor's Guide