Skip to main content

Create S3 server, users, and buckets configurations

Contributors
PDFs

POST /protocols/s3/services

Introduced In: 9.7

Creates an S3 server, users, and buckets configurations.

Important notes

  • Each SVM can have one S3 server configuration.

  • One or more buckets and users can also be created using this end-point.

  • If creating a user configuration fails, buckets are not created either and already created users are not saved.

  • If creating a bucket configuration fails, all buckets already created are saved with no new buckets created.

Required properties

  • svm.uuid - Existing SVM in which to create an S3 server configuration.

  • enabled - Specifies the state of the server created.

  • comment - Any information related to the server created.

Default property values

  • comment - ""

  • enabled - true

  • vserver object-store-server create

  • vserver object-store-server bucket create

  • vserver object-store-server bucket policy statement create

  • vserver object-store-server bucket policy-statement-condition create

  • vserver object-store-server user create

Learn more

Parameters

Name Type In Required Description

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

self_link

buckets

array[s3_bucket]

This field cannot be specified in a PATCH method.

certificate

certificate

Specifies the certificate that will be used for creating HTTPS connections to the S3 server.

comment

string

Can contain any additional information about the server being created or modified.

default_unix_user

string

Specifies the default UNIX user for NAS Access.

default_win_user

string

Specifies the default Windows user for NAS Access.

enabled

boolean

Specifies whether the S3 server being created or modified should be up or down.

is_http_enabled

boolean

Specifies whether HTTP is enabled on the S3 server being created or modified. By default, HTTP is disabled on the S3 server.

is_https_enabled

boolean

Specifies whether HTTPS is enabled on the S3 server being created or modified. By default, HTTPS is enabled on the S3 server.

max_key_time_to_live

string

Indicates the maximum time period that an S3 user can specify for the 'key_time_to_live' property.

  • Valid format is: 'PnDTnHnMnS|PnW'. For example, P2DT6H3M10S specifies a time period of 2 days, 6 hours, 3 minutes, and 10 seconds.

  • If no value is specified for this property or the value specified is '0' seconds, then a user can specify any valid value.

metric

metric

Performance numbers, such as IOPS latency and throughput, for SVM protocols.

name

string

Specifies the name of the S3 server. A server name can contain 3 to 253 characters using only the following combination of characters':' 0-9, A-Z, a-z, ".", and "-".

port

integer

Specifies the HTTP listener port for the S3 server. By default, HTTP is enabled on port 80. Valid values range from 1 to 65535.

secure_port

integer

Specifies the HTTPS listener port for the S3 server. By default, HTTPS is enabled on port 443. Valid values range from 1 to 65535.

statistics

statistics

These are raw performance numbers, such as IOPS latency and throughput for SVM protocols. These numbers are aggregated across all nodes in the cluster and increase with the uptime of the cluster.

svm

svm

SVM, applies only to SVM-scoped objects.

users

array[s3_user]

This field cannot be specified in a PATCH method.
Example request 
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "buckets": [
    {
      "aggregates": [
        {
          "_links": {
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "name": "aggr1",
          "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
        }
      ],
      "audit_event_selector": {
        "access": "string",
        "permission": "string"
      },
      "comment": "S3 bucket.",
      "constituents_per_aggregate": 4,
      "lifecycle_management": {
        "rules": [
          {
            "_links": {
              "self": {
                "href": "/api/resourcelink"
              }
            },
            "abort_incomplete_multipart_upload": {
              "_links": {
                "self": {
                  "href": "/api/resourcelink"
                }
              }
            },
            "bucket_name": "bucket1",
            "expiration": {
              "_links": {
                "self": {
                  "href": "/api/resourcelink"
                }
              },
              "object_age_days": 100,
              "object_expiry_date": "2039-09-22 20:00:00 -0400"
            },
            "name": "string",
            "non_current_version_expiration": {
              "_links": {
                "self": {
                  "href": "/api/resourcelink"
                }
              }
            },
            "object_filter": {
              "_links": {
                "self": {
                  "href": "/api/resourcelink"
                }
              },
              "prefix": "/logs",
              "size_greater_than": 10240,
              "size_less_than": 10485760,
              "tags": [
                "project1=projA",
                "project2=projB"
              ]
            },
            "svm": {
              "_links": {
                "self": {
                  "href": "/api/resourcelink"
                }
              },
              "name": "svm1",
              "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
            },
            "uuid": "414b29a1-3b26-11e9-bd58-0050568ea055"
          }
        ]
      },
      "logical_used_size": 0,
      "name": "bucket1",
      "nas_path": "/",
      "policy": {
        "statements": [
          {
            "actions": [
              "GetObject",
              "PutObject",
              "DeleteObject",
              "ListBucket"
            ],
            "conditions": [
              {
                "delimiters": [
                  "/"
                ],
                "max_keys": [
                  1000
                ],
                "operator": "ip_address",
                "prefixes": [
                  "pref"
                ],
                "source_ips": [
                  "1.1.1.1",
                  "1.2.2.0/24"
                ],
                "usernames": [
                  "user1"
                ]
              }
            ],
            "effect": "allow",
            "principals": [
              "user1",
              "group/grp1",
              "nasgroup/group1"
            ],
            "resources": [
              "bucket1",
              "bucket1/*"
            ],
            "sid": "FullAccessToUser1"
          }
        ]
      },
      "qos_policy": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "max_throughput_iops": 10000,
        "max_throughput_mbps": 500,
        "min_throughput_iops": 2000,
        "min_throughput_mbps": 500,
        "name": "performance",
        "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
      },
      "retention": {
        "default_period": "P10Y",
        "mode": "governance"
      },
      "role": "string",
      "size": 1677721600,
      "storage_service_level": "value",
      "svm": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "svm1",
        "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
      },
      "type": "s3",
      "uuid": "414b29a1-3b26-11e9-bd58-0050568ea055",
      "versioning_state": "enabled",
      "volume": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "volume1",
        "uuid": "028baa66-41bd-11e9-81d5-00a0986138f7"
      }
    }
  ],
  "certificate": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "string",
    "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
  },
  "comment": "S3 server",
  "default_unix_user": "string",
  "default_win_user": "string",
  "max_key_time_to_live": "PT6H3M",
  "metric": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "duration": "PT15S",
    "iops": {
      "read": 200,
      "total": 1000,
      "write": 100
    },
    "latency": {
      "read": 200,
      "total": 1000,
      "write": 100
    },
    "status": "ok",
    "throughput": {
      "read": 200,
      "total": 1000,
      "write": 100
    },
    "timestamp": "2017-01-25 06:20:13 -0500"
  },
  "name": "Server-1",
  "port": 80,
  "secure_port": 443,
  "statistics": {
    "iops_raw": {
      "read": 200,
      "total": 1000,
      "write": 100
    },
    "latency_raw": {
      "read": 200,
      "total": 1000,
      "write": 100
    },
    "status": "ok",
    "throughput_raw": {
      "read": 200,
      "total": 1000,
      "write": 100
    },
    "timestamp": "2017-01-25 06:20:13 -0500"
  },
  "svm": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "users": [
    {
      "access_key": "HJAKU28M3SXTE2UXUACV",
      "comment": "S3 user",
      "key_expiry_time": "2023-12-31 19:00:00 -0500",
      "key_id": 1,
      "key_time_to_live": "PT6H3M",
      "keys": [
        {
          "access_key": "HJAKU28M3SXTE2UXUACV",
          "expiry_time": "2023-12-31 19:00:00 -0500",
          "id": 1,
          "time_to_live": "PT6H3M"
        }
      ],
      "name": "user-1",
      "svm": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "svm1",
        "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
      }
    }
  ]
}

Response

Status: 201, Created
Name Type Description

num_records

integer

Number of Records

records

array[records]
Example response 
{
  "num_records": 1,
  "records": [
    {
      "_links": {
        "next": {
          "href": "/api/resourcelink"
        },
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "job": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "uuid": "string"
      },
      "users": [
        {
          "_links": {
            "next": {
              "href": "/api/resourcelink"
            },
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "access_key": "HJAKU28M3SXTE2UXUACV",
          "key_expiry_time": "2023-12-31 19:00:00 -0500",
          "name": "user-1",
          "secret_key": "BcA_HX6If458llhnx3n1TCO3mg4roCXG0ddYf_cJ"
        }
      ],
      "warning": {
        "message": "string"
      }
    }
  ]
}

Headers

Name Description Type

Location

Useful for tracking the resource location

string

Error

Status: Default

ONTAP Error Response Codes

Error Code Description

2621706

The specified "{svm.uuid}" and "{svm.name}" refer to different SVMs.

92405789

The specified object server name contains invalid characters or not a fully qualified domain name. Valid characters for an object store server name are 0-9, A-Z, a-z, ".", and "-".

92405790

Object store server names must have between 3 and 253 characters.

92405839

Creating an object store server requires an effective cluster version of data ONTAP 9.7.0 or later. Upgrade all the nodes to 9.7.0 or later and try the operation again.

92405853

Failed to create the object store server because Cloud Volumes ONTAP does not support object store servers.

92405863

An error occurs when creating an S3 user or bucket. The reason for failure is detailed in the error message. Follow the error codes specified for the user or bucket endpoints to see details for the failure.

92405863

Failed to create bucket "{bucket name}". Reason: "Failed to create bucket "{bucket name}" for SVM "{svm.name}". Reason: Bucket name "{bucket name}" contains invalid characters. Valid characters for a bucket name are 0-9, a-z, ".", and "-". ". Resolve all the issues and retry the operation.

92405863

Failed to create bucket "{bucket name}". Reason: "Failed to create bucket "{bucket name}" for SVM "{svm.name}". Reason: Invalid QoS policy group specified "{qos policy}". The specified QoS policy group has a min-throughput value set, and the workload being assigned resides on a platform that does not support min-throughput or the cluster is in a mixed version state and the effective cluster version of ONTAP does not support min-throughput on this platform. Resolve all the issues and retry the operation.

92405863

Failed to create bucket "{bucket name}". Reason: "User(s) "{user name(s)}" specified in the principal list do not exist for SVM "{svm.name}". Use the "object-store-server user create" command to create a user.". Resolve all the issues and retry the operation.

92405863

Failed to create user "{user name}". Reason: "SVM "Cluster" is not a data SVM. Specify a data SVM.". Resolve all the issues and retry the operation.

92405884

An object store server can only be created on a data SVM. An object store server can also be created on a system SVM on a mixed platform cluster.

92405903

Failed to configure HTTPS on an object store server for SVM "{svm.name}". Reason: {Reason of failure}.

92405900

Certificate not found for SVM "{svm.name}".

92406044

Failed to set default UNIX user for SVM "{svm.name}". Reason: UNIX user can only be created on a Data SVM.

92406196

The specified value for the "key_time_to_live" field cannot be greater than the maximum limit specified for the "max_key_time_to_live" field in the object store server.

92406197

Object store user "user-2" must have a non-zero value for the "key_time_to_live" field because the maximum limit specified for the "max_key_time_to_live" field in the object store server is not zero.
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
Name Type Description

self

href

_links

Name Type Description

self

href

aggregates

Aggregate

Name Type Description

_links

_links

name

string

uuid

string

audit_event_selector

Audit event selector allows you to specify access and permission types to audit.

Name Type Description

access

string

Specifies read and write access types.

permission

string

Specifies allow and deny permission types.

encryption

Name Type Description

enabled

boolean

Specifies whether encryption is enabled on the bucket. By default, encryption is disabled on a bucket. This field cannot be specified in a POST method.

abort_incomplete_multipart_upload

Specifies a way to perform abort_incomplete_multipart_upload action on filtered objects within a bucket. It cannot be specified with tags.

Name Type Description

_links

_links

after_initiation_days

integer

Number of days of initiation after which uploads can be aborted.

expiration

Specifies a way to perform expiration action on filtered objects within a bucket.

Name Type Description

_links

_links

expired_object_delete_marker

boolean

Cleanup object delete markers.

object_age_days

integer

Number of days since creation after which objects can be deleted. This cannot be used along with object_expiry_date.

object_expiry_date

string

Specific date from when objects can expire. This cannot be used with object_age_days.

non_current_version_expiration

Specifies a way to perform non_current_version_expiration action on filtered objects within a bucket.

Name Type Description

_links

_links

new_non_current_versions

integer

Number of latest non-current versions to be retained.

non_current_days

integer

Number of days after which non-current versions can be deleted.

object_filter

Specifies a way to filter objects within a bucket.

Name Type Description

_links

_links

prefix

string

A prefix that is matched against object-names within a bucket.

size_greater_than

integer

Size of the object greater than specified for which the corresponding lifecycle rule is to be applied.

size_less_than

integer

Size of the object smaller than specified for which the corresponding lifecycle rule is to be applied.

tags

array[string]

An array of key-value paired tags of the form or <tag=value>.

svm

Specifies the name of the SVM where this bucket exists.

Name Type Description

_links

_links

name

string