Create a cloud target
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 whenprovider_type
is one of the following: SGWS, IBM_COS, AliCloud. -
container
- Data bucket/container name. -
access_key
- Access key ID ifprovider_type
is not Azure_Cloud andauthentication_type
is key. -
secret_password
- Secret access key ifprovider_type
is not Azure_Cloud andauthentication_type
is key. -
azure_account
- Azure account ifprovider_type
is Azure_Cloud. -
azure_private_key
- Azure access key ifprovider_type
is Azure_Cloud. -
cap_url
- Full URL of the request to a CAP server for retrieving temporary credentials ifauthentication_type
is cap. -
snapmirror_use
- Use of the cloud target ifowner
is snapmirror: data, metadata.
Recommended optional properties
-
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
orsvm.uuid
- Name or UUID of SVM ifowner
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 andprovider_type
is not SGWS -
8084 if
ssl_enabled
is false andprovider_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_
Related ONTAP commands
-
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.
|
return_records |
boolean |
query |
False |
The default is false. If set to true, the records are returned.
|
Request Body
Name | Type | Description |
---|---|---|
_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.
|
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.
|
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.
|
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.
|
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- |
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.
|
snapmirror_use |
string |
Use of the cloud target by SnapMirror. |
ssl_enabled |
boolean |
SSL/HTTPS enabled or not |
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 |
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 |
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 |
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 |
||
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 |
||
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 |
||
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.
|
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.
|
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.
|
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.
|
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- |
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.
|
snapmirror_use |
string |