Skip to main content
A newer release of this product is available.

Create S3 server, users, and buckets configurations

Contributors
PDFs

POST /protocols/s3/services

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 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.

Request Body

Name Type Description

_links

self_link

buckets

array[s3_bucket]

comment

string

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

enabled

boolean

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

name

string

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

svm

svm

users

array[s3_user]
Example request 
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "buckets": [
    {
      "aggregates": [
        {
          "_links": {
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "name": "aggr1",
          "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
        }
      ],
      "comment": "S3 bucket.",
      "constituents_per_aggregate": 4,
      "logical_used_size": 0,
      "name": "bucket-1",
      "size": 1677721600,
      "svm": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "svm1",
        "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
      },
      "uuid": "414b29a1-3b26-11e9-bd58-0050568ea055",
      "volume": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "volume1",
        "uuid": "028baa66-41bd-11e9-81d5-00a0986138f7"
      }
    }
  ],
  "comment": "S3 server",
  "name": "Server-1",
  "svm": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "users": [
    {
      "access_key": "Pz3SB54G2B_6dsXQPrA5HrTPcf478qoAW6_Xx6qyqZ948AgZ_7YfCf_9nO87YoZmskxx3cq41U2JAH2M3_fs321B4rkzS3a_oC5_8u7D8j_45N8OsBCBPWGD_1d_ccfq",
      "comment": "S3 user",
      "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 
{
  "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": "Pz3SB54G2B_6dsXQPrA5HrTPcf478qoAW6_Xx6qyqZ948AgZ_7YfCf_9nO87YoZmskxx3cq41U2JAH2M3_fs321B4rkzS3a_oC5_8u7D8j_45N8OsBCBPWGD_1d_ccfq",
          "name": "user-1",
          "secret_key": "A20_tDhC_cux2C2BmtL45bXB_a_Q65c_96FsAcOdo14Az8V31jBKDTc0uCL62Bh559gPB8s9rrn0868QrF38_1dsV2u1_9H2tSf3qQ5xp9NT259C6z_GiZQ883Qn63X1"
        }
      ]
    }
  ]
}

Error

Status: Default

ONTAP Error Response Codes

Error Code Description

2621706

The specified SVM UUID is incorrect for the specified SVM name.

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 1 and 15 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.

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.
Name Type Description

error

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

encryption

Name Type Description

enabled

boolean

Specifies whether encryption is enabled on the bucket. By default, encryption is disabled on a bucket.

svm

Name Type Description

_links

_links

name

string

The name of the SVM.

uuid

string

The unique identifier of the SVM.

volume

Specifies the FlexGroup volume name and UUID where the bucket is hosted.

Name Type Description

_links

_links

name

string

The name of the volume.

uuid

string

Unique identifier for the volume. This corresponds to the instance-uuid that is exposed in the CLI and ONTAPI. It does not change due to a volume move.

  • example: 028baa66-41bd-11e9-81d5-00a0986138f7

s3_bucket

A bucket is a container of objects. Each bucket defines an object namespace. S3 requests specify objects using a bucket-name and object-name pair. An object resides within a bucket.

Name Type Description

aggregates

array[aggregates]

A list of aggregates for FlexGroup volume constituents where the bucket is hosted. If this option is not specified, the bucket is auto-provisioned as a FlexGroup volume.

comment

string

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

constituents_per_aggregate

integer

Specifies the number of constituents or FlexVol volumes per aggregate. A FlexGroup volume consisting of all such constituents across all specified aggregates is created. This option is used along with the aggregates option and cannot be used independently.

encryption

encryption

logical_used_size

integer

Specifies the bucket logical used size up to this point.

name

string

Specifies the name of the bucket. Bucket name is a string that can only contain the following combination of ASCII-range alphanumeric characters 0-9, a-z, ".", and "-".

size

integer

Specifies the bucket size in bytes; ranges from 80MB to 64TB.

svm

svm

uuid

string

Specifies the unique identifier of the bucket.

volume

volume

Specifies the FlexGroup volume name and UUID where the bucket is hosted.

s3_user

This is a container of S3 users.

Name Type Description

access_key

string

Specifies the access key for the user.

comment

string

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

name

string

Specifies the name of the user. A user name length can range from 1 to 64 characters and can only contain the following combination of characters 0-9, A-Z, a-z, "_", "+", "=", ",", ".","@", and "-".

svm

svm

s3_service

Specifies the S3 server configuration.

Name Type Description

_links

self_link

buckets

array[s3_bucket]

comment

string

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

enabled

boolean

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

name

string

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

svm

svm

users

array[s3_user]
Name Type Description

next

href

self

href
Name Type Description

_links

_links

uuid

string

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

s3_service_user_post_response

Name Type Description

_links

collection_links

access_key

string

Specifies the access key for the user.

name

string

The name of the user.

secret_key

string

Specifies the secret key for the user.

records

Name Type Description

_links

collection_links

job

job_link

users

array[s3_service_user_post_response]

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

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.