Creating a bucket

You use the HTTP PUT method to create a bucket. To create a bucket, you must be an authenticated user. Additionally, your user account must be configured to let you create buckets.

When you create a bucket, you specify a name for it. The specified name must be at least three characters long and at most 63 characters long. The name can contain only alphanumeric characters and hyphens (-) but cannot start or end with a hyphen.

You can specify an ACL for a bucket in the same request as you use to create the bucket. To do this, you need to use ACL headers. You cannot use an ACL request body when creating a bucket.

If the ACL you specify in a request to create a bucket is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not create the bucket.

When you create a bucket, you become the bucket owner. You also get browse, read, read ACL, write, write ACL, and delete data access permissions for the bucket. If search is enabled for the bucket, you also get search permission.

NoteYou cannot use Active Directory authentication with S3 compatible requests to create a bucket.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to create a bucket has either of these formats:

  • With the bucket name included in the hostname:
    PUT / HTTP/1.1
  • With the bucket name following the hostname:
    PUT /bucket-name HTTP/1.1

Required headers

  • Authorization

    Specifies user credentials or requests anonymous access.

NoteYou cannot create a bucket as an anonymous user.
  • Content-Length

    Specifies the size, in bytes, of the request body. For a request to create a bucket, the value of this header must be 0 (zero).

  • Date

    Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.

    The date and time must always be specified using Greenwich Mean Time (GMT).

    To specify the date and time, use this format:

    DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    In this format:

    • DDD

      The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).

    • dd

      The two-digit day of the month.

    • MMM

      The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).

    • yyyy

      The four-digit year.

    • HH

      The hour on a 24-hour clock.

    • mm

      The number of minutes.

    • ss

      The number of seconds.

    For example:

    Thu, 23 Mar 2017 14:27:05 +0000

    All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

  • Host

    Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

    For a tenant, use this format:

    tenant-name.hcp-domain-name

    For a bucket, use this format:

    bucket-name.tenant-name.hcp-domain-name

Optional headers

  • x-amz-acl

    Adds a canned ACL to the bucket.

    This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.

  • x-amz-date

    Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

    For the valid values for this header, see the description of the Date header above.

  • x-amz-grant-full-control

    Grants full control over the bucket to one or more specified grantees.

    If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.

  • x-amz-grant-read

    Grants the browse and read data access permissions for the bucket to one or more specified grantees.

    If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.

  • x-amz-grant-read-acp

    Grants the read ACL data access permission for the bucket to one or more specified grantees.

    If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.

  • x-amz-grant-write

    Grants the write and delete data access permissions for the bucket to one or more specified grantees.

    If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.

  • x-amz-grant-write-acp

    Grants the write ACL data access permission for the bucket to one or more specified grantees.

    If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.

Response headers

The list below describes the headers returned in response to a successful request to create a bucket.

  • Content-length

    Specifies the size, in bytes, of the response body. In response to a successful request to store an object, the value of this header is always 0 (zero).

  • Date

    The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:

    DDD dd MMM yyyy HH:mm:ss GMT

    For example:

    Fri, 18 Sep 2020 14:27:05 GMT

  • Location

    Specifies the name of the bucket created by the request.

Return codes

The table below describes HTTP status codes that can be returned in response to a request to create a bucket.

CodeMeaningDescription
200OK

One of these:

  • The bucket was successfully created.
  • A bucket with the specified name already exists and is owned by you.
400Bad Request

Possible reasons include:

  • The specified bucket name is invalid.
  • An ACL grant header specifies an invalid grantee.
  • You already own the maximum number buckets allowed per user.
  • The tenant does not have enough space for another bucket.
  • The tenant already has the maximum number of buckets it’s allowed to have.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to create buckets.
  • The tenant does not currently support use of the S3 compatible API for creating buckets.
409ConflictA bucket with the specified name already exists and either is owned by a user other than you or has no owner.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

501Not ImplementedThe request includes the x-amz-acl header with an invalid value.
503Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Creating a bucket

Here’s a sample PUT request that creates a bucket named finance in the context of the tenant named europe.

Request with s3curl command line

./s3curl.pl --id=lgreen --createBucket -- -k "https://finance.europe.hcp.example.com"

Request headers

PUT / HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:1RXSNMipYpv4IOpfNS9Odi1UBWM=
Content-Length: 0

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Location: /finance
Content-Length: 0

Example: Creating a bucket with an ACL

Here’s a sample PUT request that creates a bucket named human-resources and adds an ACL to the bucket. The ACL grants read permission to all users and write permission to the users with usernames mwhite and pdgrey.

Request with s3curl command line

./s3curl.pl --id=lgreen --createBucket -- -k
     "https://human-resources.europe.hcp.example.com"
     -H "x-amz-grant-read: emailAddress=all_users"
     -H "x-amz-grant-write: emailAddress=mwhite, emailAddress=pdgrey"

Request headers

PUT / HTTP/1.1
Host: human-resources.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:0WCfi79j2QtCczA6TGutnJWNRm4=
x-amz-grant-read: emailAddress=all_users
x-amz-grant-write: emailAddress=mwhite, emailAddress=pdgrey
Content-Length: 0

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
Location: /human-resources
Content-Length: 0