Skip to main content

Create a cloud target

Contributors
PDFs

POST /cloud/targets

Introduced In: 9.6

Creates a cloud target.

Required properties

  • name - Name for the cloud target.

  • owner - Owner of the target: fabricpool, snapmirror.

  • provider_type - Type of cloud provider: AWS_S3, Azure_Cloud, SGWS, IBM_COS, AliCloud, GoogleCloud, ONTAP_S3.

  • server - Fully qualified domain name of the object store server. Required when provider_type is one of the following: SGWS, IBM_COS, AliCloud.

  • container - Data bucket/container name.

  • access_key - Access key ID if provider_type is not Azure_Cloud and authentication_type is key.

  • secret_password - Secret access key if provider_type is not Azure_Cloud and authentication_type is key.

  • azure_account - Azure account if provider_type is Azure_Cloud.

  • azure_private_key - Azure access key if provider_type is Azure_Cloud.

  • cap_url - Full URL of the request to a CAP server for retrieving temporary credentials if authentication_type is cap.

  • snapmirror_use - Use of the cloud target if owner is snapmirror: data, metadata.

  • authentication_type - Authentication used to access the target: key, cap, ec2_iam, gcp_sa, azure_msi.

  • ssl_enabled - SSL/HTTPS enabled or disabled.

  • port - Port number of the object store that ONTAP uses when establishing a connection.

  • ipspace - IPspace to use in order to reach the cloud target.

  • use_http_proxy - Use the HTTP proxy when connecting to the object store server.

  • azure_sas_token - Shared access signature to grant limited access to Azure storage account resources.

  • svm.name or svm.uuid - Name or UUID of SVM if owner is snapmirror.

  • read_latency_warning_threshold - Latency threshold to determine when to issue a warning alert EMS for a GET request.

Default property values

  • authentication_type

  • ec2_iam - if running in Cloud Volumes ONTAP in AWS

  • gcp_sa - if running in Cloud Volumes ONTAP in GCP

  • azure_msi - if running in Cloud Volumes ONTAP in Azure

  • key - in all other cases.

  • server

  • s3.amazonaws.com - if provider_type is AWS_S3

  • blob.core.windows.net - if provider_type is Azure_Cloud

  • storage.googleapis.com - if provider_type is GoogleCloud

  • ssl_enabled - true

  • port

  • 443 if ssl_enabled is true

  • 80 if ssl_enabled is false and provider_type is not SGWS

  • 8084 if ssl_enabled is false and provider_type is SGWS

  • ipspace - Default

  • certificate_validation_enabled - true

  • ignore_warnings - false

  • check_only - false

  • use_http_proxy - false

  • server_side_encryption

  • none - if provider_type is ONTAP_S3

  • sse_s3 - if provider_type is not ONTAP_S3

  • url_style

  • path_style - if provider_type is neither AWS_S3 nor AliCloud

  • virtual_hosted_style - if provider_type is either AWS_S3 or _AliCloud_

  • storage aggregate object-store config create

Parameters

Name Type In Required Description

ignore_warnings

boolean

query

False

Specifies whether or not warning codes should be ignored.

check_only

boolean

query

False

Do not create the target configuration, only check that the POST request succeeds.

return_timeout

integer

query

False

The number of seconds to allow the call to execute before returning. When doing a POST, PATCH, or DELETE operation on a single record, the default is 0 seconds. This means that if an asynchronous operation is started, the server immediately returns HTTP code 202 (Accepted) along with a link to the job. If a non-zero value is specified for POST, PATCH, or DELETE operations, ONTAP waits that length of time to see if the job completes so it can return something other than 202.

  • Default value: 1

  • Max value: 120

  • Min value: 0

return_records

boolean

query

False

The default is false. If set to true, the records are returned.

  • Default value:

Request Body

Name Type Description

_links

_links

access_key

string

Access key ID for AWS_S3 and other S3 compatible provider types.

authentication_type

string

Authentication used to access the target. SnapMirror does not yet support CAP. Required in POST.

azure_account

string

Azure account

azure_private_key

string

Azure access key

azure_sas_token

string

Shared access signature token to access Azure containers and blobs.

cap_url

string

This parameter is available only when auth-type is CAP. It specifies a full URL of the request to a CAP server for retrieving temporary credentials (access-key, secret-pasword, and session token) for accessing the object store.

certificate_validation_enabled

boolean

Is SSL/TLS certificate validation enabled? The default value is true. This can only be modified for SGWS, IBM_COS, and ONTAP_S3 provider types.

  • Introduced in: 9.6

  • x-nullable: true

cluster

cluster

container

string

Data bucket/container name. For FabricLink, a wildcard character "*" can also be specified to indicate that all the buckets in an SVM can use the same target information. However, for containers other than ONTAP, an exact name should be specified.

  • example: bucket1

  • Introduced in: 9.6

  • readCreate: 1

  • x-nullable: true

ipspace

ipspace

IPspace to use in order to reach the cloud target.

name

string

Cloud target name

owner

string

Owner of the target. Allowed values are FabricPool, SnapMirror or S3_SnapMirror. A target can be used by only one feature.

port

integer

Port number of the object store that ONTAP uses when establishing a connection. Required in POST.

  • Introduced in: 9.6

  • x-nullable: true

provider_type

string

Type of cloud provider. Allowed values depend on owner type. For FabricPool, AliCloud, AWS_S3, Azure_Cloud, GoogleCloud, IBM_COS, SGWS, and ONTAP_S3 are allowed. For SnapMirror, the valid values are AWS_S3 or SGWS. For FabricLink, AWS_S3, SGWS, S3_Compatible, S3EMU, LOOPBACK and ONTAP_S3 are allowed.

  • Introduced in: 9.6

  • readCreate: 1

  • x-nullable: true

read_latency_warning_threshold

integer

The warning threshold for read latency that is used to determine when an alert ems for a read operation from an object store should be issued.

scope

string

If the cloud target is owned by a data SVM, then the scope is set to svm. Otherwise it will be set to cluster.

secret_password

string

Secret access key for AWS_S3 and other S3 compatible provider types.

server

string

Fully qualified domain name of the object store server. Required on POST. For Amazon S3, server name must be an AWS regional endpoint in the format s3.amazonaws.com or s3-.amazonaws.com, for example, s3-us-west-2.amazonaws.com. The region of the server and the bucket must match. For Azure, if the server is a "blob.core.windows.net" or a "blob.core.usgovcloudapi.net", then a value of azure-account followed by a period is added in front of the server.

server_side_encryption

string

Encryption of data at rest by the object store server for AWS_S3 and other S3 compatible provider types. This is an advanced property. In most cases it is best not to change default value of "sse_s3" for object store servers which support SSE-S3 encryption. The encryption is in addition to any encryption done by ONTAP at a volume or at an aggregate level. Note that changing this option does not change encryption of data which already exist in the object store.

  • enum: ["none", "sse_s3"]

  • Introduced in: 9.7

  • x-nullable: true

snapmirror_use

string

Use of the cloud target by SnapMirror.

ssl_enabled

boolean

SSL/HTTPS enabled or not

svm

svm

This field is only applicable when used for SnapMirror and FabricLink. For POST and PATCH, SVM information is required for SnapMirror and FabricLink targets and not allowed for FabricPool targets.

url_style

string

URL style used to access S3 bucket.

use_http_proxy

boolean

Use HTTP proxy when connecting to the object store.

used

integer

The amount of cloud space used by all the aggregates attached to the target, in bytes. This field is only populated for FabricPool targets. The value is recalculated once every 5 minutes.

uuid

string

Cloud target UUID
Example request 
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "access_key": "string",
  "authentication_type": "string",
  "azure_account": "string",
  "azure_private_key": "string",
  "azure_sas_token": "string",
  "cap_url": "https://123.45.67.89:1234/CAP/api/v1/credentials?agency=myagency&mission=mymission&role=myrole",
  "cluster": {
    "name": "string",
    "uuid": "string"
  },
  "container": "bucket1",
  "ipspace": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "Default",
    "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
  },
  "name": "string",
  "owner": "string",
  "provider_type": "string",
  "scope": "string",
  "secret_password": "string",
  "server": "string",
  "server_side_encryption": "string",
  "snapmirror_use": "string",
  "svm": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "url_style": "string",
  "used": 0,
  "uuid": "string"
}

Response

Status: 202, Accepted
Name Type Description

job

job_link
Example response 
{
  "job": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "uuid": "string"
  }
}

Headers

Name Description Type

Location

Useful for tracking the resource location

string

Response

Status: 201, Created

Error

Status: Default

ONTAP Error Response Codes

Error Code Description

786436

VLDB is not running.

786908

Capability check failed.

787015

"encryption-key-id" is not expected when encrypt is false.

787016

An object store configuration with the same combination of server and container name already exists.

787020

Failed to check whether the FabricPool capability exists.

787021

The FabricPool capability is not enabled.

787030

Object store configuration creation is not supported in this cluster.

787036

Server name is invalid. A valid server name must be a fully qualified domain name.

787037

Cannot verify availability of the object store.

787038

Object store provider type requires a FabricPool license.

787039

Failed to retrieve FabricPool capacity license information.

787044

Cannot create object store configuration as the number of object stores in the cluster has reached maximum allowed limit.

787054

An object store configuration with the same combination of server, azure account and container name already exists.

787064

Object store server provider type does not match object store provider type. Use the provider type that matches the server.

787065

Certificate validation must be enabled for the object store provider.

787066

Certificate validation cannot be specified when the "-is-ssl-enabled" parameter is false.

787068

Disabling certificate validation requires an effective cluster version of ONTAP 9.4.0 or later.

787071

Object store configuration creation requires an effective cluster version of ONTAP 9.4.0 or later.

787082

Creating an object store configuration requires an effective cluster version of ONTAP 9.5.0 or later.

787089

The object store provider supports the virtual hosted-style, and the specified "-server" contains the container name. The container specified in the "-server" parameter must be the same as the name of the container specified in the "-container" parameter.

787133

Could not retrieve temporary credentials from the CAP server.

787134

Could not retrieve temporary credentials from the CAP server due to an unexpected response.

787136

Specifying "CAP" as the "-auth-type" requires an effective cluster version of ONTAP 9.5.0 or later.

787148

The clock on node is behind by more than the maximum of 5 minutes.

787149

The clock on node is ahead by more than the maximum of 5 minutes.

787158

An object store configuration with the same combination of server and container name already exists.

787159

An object store configuration with the same name already exists.

787179

One or more clusters in this MetroCluster configuration do not have an effective cluster version of ONTAP 9.7.0 or later.

787184

Using HTTP proxies with FabricPool requires an effective cluster version of ONTAP 9.7.0 or later.

787185

There is no HTTP proxy for IPspace. Refer to the "vserver http-proxy" man page for details.

787188

Object store configuration belongs to another cluster and cannot be modified from the local cluster, unless the cluster is in switchover mode.

787189

Object store configuration name must not have the "-mc" suffix when the configuration is created for a local cluster. To create an object store configuration which belongs to another cluster, the cluster must be in switchover mode and "-cluster" must be specified.

787209

Object store is not accessible from the partner cluster in a MetroCluster configuration.

787216

Cannot perform object store configuration operations on a cluster that is waiting for switchback.

787222

Object store connectivity check failed on partner cluster in MetroCluster configuration. Wait a few minutes, and try the operation again.

787223

Specifying "GCP_SA" as the "-auth-type" requires an effective cluster version of ONTAP 9.7.0 or later.

787227

Specifying "Azure_MSI" as the "-auth-type" requires an effective cluster version of ONTAP 9.7 or later.

787228

SSL is required for this configuration.

787229

Cannot perform operation as URL style is not supported with object store provider type.

787233

The hash key for enabling this FabricPool feature is not present on the cluster.

787234

The hash key provided for the node to enable this FabricPool feature is not valid.

787254

The parameter is not supported on this system.

787257

The parameter "-encryption-context" is only applicable for AWS object store provider.

787262

The "create-container" option is applicable only for an SGWS or ONTAP_S3 object store provider.

787301

ONTAP S3 Bucket is of type NAS and is not supported as a target for FabricPool.

787302

Cannot use HTTP port with "-is-ssl-enabled" set to true.

787303

Cannot use HTTPS port with "-is-ssl-enabled" set to false.

45940761

Hostname cannot be resolved. Check the spelling of the hostname and check the system DNS availability using the "vserver services name-service dns check" command.

45940778

Bucket already exists.

139591795

Object store configuration for S3 SnapMirror representing ONTAP S3 object store provider only supports \"*\" as the container name.

139591796

Object store configuration name for S3 SnapMirror representing ONTAP S3 object store provider must be of the format \"vserver::\\\".

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

Name Type Description

error

returned_error
Example error 
{
  "error": {
    "arguments": [
      {
        "code": "string",
        "message": "string"
      }
    ],
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name Type Description

href

string

_links

Name Type Description

self

href

cluster

Name Type Description

name

string

The name of the cluster that owns the cloud target. For POST, this accepts the name of the peer cluster only if the cluster is in switchover state.

uuid

string

The UUID of the cluster that owns the cloud target. For POST, this accepts the UUID of the peer cluster only if the cluster is in switchover state.

ipspace

IPspace to use in order to reach the cloud target.

Name Type Description

_links

_links

name

string

IPspace name

uuid

string

IPspace UUID

svm

This field is only applicable when used for SnapMirror and FabricLink. For POST and PATCH, SVM information is required for SnapMirror and FabricLink targets and not allowed for FabricPool targets.

Name Type Description

_links

_links

name

string

The name of the SVM. This field cannot be specified in a PATCH method.

uuid

string

The unique identifier of the SVM. This field cannot be specified in a PATCH method.

cloud_target

Name Type Description

_links

_links

access_key

string

Access key ID for AWS_S3 and other S3 compatible provider types.

authentication_type

string

Authentication used to access the target. SnapMirror does not yet support CAP. Required in POST.

azure_account

string

Azure account

azure_private_key

string

Azure access key

azure_sas_token

string

Shared access signature token to access Azure containers and blobs.

cap_url

string

This parameter is available only when auth-type is CAP. It specifies a full URL of the request to a CAP server for retrieving temporary credentials (access-key, secret-pasword, and session token) for accessing the object store.

certificate_validation_enabled

boolean

Is SSL/TLS certificate validation enabled? The default value is true. This can only be modified for SGWS, IBM_COS, and ONTAP_S3 provider types.

  • Introduced in: 9.6

  • x-nullable: true

cluster

cluster

container

string

Data bucket/container name. For FabricLink, a wildcard character "*" can also be specified to indicate that all the buckets in an SVM can use the same target information. However, for containers other than ONTAP, an exact name should be specified.

  • example: bucket1

  • Introduced in: 9.6

  • readCreate: 1

  • x-nullable: true

ipspace

ipspace

IPspace to use in order to reach the cloud target.

name

string

Cloud target name

owner

string

Owner of the target. Allowed values are FabricPool, SnapMirror or S3_SnapMirror. A target can be used by only one feature.

port

integer

Port number of the object store that ONTAP uses when establishing a connection. Required in POST.

  • Introduced in: 9.6

  • x-nullable: true

provider_type

string

Type of cloud provider. Allowed values depend on owner type. For FabricPool, AliCloud, AWS_S3, Azure_Cloud, GoogleCloud, IBM_COS, SGWS, and ONTAP_S3 are allowed. For SnapMirror, the valid values are AWS_S3 or SGWS. For FabricLink, AWS_S3, SGWS, S3_Compatible, S3EMU, LOOPBACK and ONTAP_S3 are allowed.

  • Introduced in: 9.6

  • readCreate: 1

  • x-nullable: true

read_latency_warning_threshold

integer

The warning threshold for read latency that is used to determine when an alert ems for a read operation from an object store should be issued.

scope

string

If the cloud target is owned by a data SVM, then the scope is set to svm. Otherwise it will be set to cluster.

secret_password

string

Secret access key for AWS_S3 and other S3 compatible provider types.

server

string

Fully qualified domain name of the object store server. Required on POST. For Amazon S3, server name must be an AWS regional endpoint in the format s3.amazonaws.com or s3-.amazonaws.com, for example, s3-us-west-2.amazonaws.com. The region of the server and the bucket must match. For Azure, if the server is a "blob.core.windows.net" or a "blob.core.usgovcloudapi.net", then a value of azure-account followed by a period is added in front of the server.

server_side_encryption

string

Encryption of data at rest by the object store server for AWS_S3 and other S3 compatible provider types. This is an advanced property. In most cases it is best not to change default value of "sse_s3" for object store servers which support SSE-S3 encryption. The encryption is in addition to any encryption done by ONTAP at a volume or at an aggregate level. Note that changing this option does not change encryption of data which already exist in the object store.

  • enum: ["none", "sse_s3"]

  • Introduced in: 9.7

  • x-nullable: true

snapmirror_use

string

Use of the cloud target by SnapMirror.

ssl_enabled

boolean

SSL/HTTPS enabled or not

svm

svm

This field is only applicable when used for SnapMirror and FabricLink. For POST and PATCH, SVM information is required for SnapMirror and FabricLink targets and not allowed for FabricPool targets.

url_style

string

URL style used to access S3 bucket.

use_http_proxy

boolean

Use HTTP proxy when connecting to the object store.

used

integer

The amount of cloud space used by all the aggregates attached to the target, in bytes. This field is only populated for FabricPool targets. The value is recalculated once every 5 minutes.

uuid

string

Cloud target UUID
Name Type Description

_links

_links

uuid

string

The UUID of the asynchronous job that is triggered by a POST, PATCH, or DELETE operation.

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

returned_error

Name Type Description

arguments

array[error_arguments]

Message arguments

code

string

Error code

message

string

Error message

target

string

The target parameter that caused the error.