# Create a bucket

Create a bucket in the zone of your choice, encrypted with the platform key or a KMS key of yours, optionally with object lock.

Replace _example-uploads_ with a bucket name of your own. Bucket names are shared by everyone on
the platform, because each name is also a hostname: start it with your company or project.

**Important:**
The name, the zone and object lock are fixed once the bucket exists. To change one, create a new
bucket and copy the objects.

## Prerequisites

- Permission for `s3:CreateBucket` on the bucket.
- To encrypt with a KMS key of yours: `kms:Encrypt` on that key, and the key enabled.
- To create the bucket in Helsinki (`fi1a`): an administrator has turned on **Allow EU locations
  outside Germany** under **Settings** → **Data location**.

## Create the bucket

**Console**
1. Open **Object Storage**, then choose **Create bucket**.
2. For **Name**, enter example-uploads.
3. (Optional) Under **Zone**, choose the zone the objects are stored in. The form starts on
   `de1a (Falkenstein)`. The zone is not offered when your organization keeps its buckets on
   storage of its own.
4. (Optional) For **Encryption key**, choose a key under **Customer managed keys** instead of
   **Platform-managed key (default)**.
5. (Optional) Select **Object lock**.
6. Choose **Create**.

The bucket's page opens.

**CLI**
```sh
dcloud s3 buckets create --name example-uploads --zone de1b
```

**API**
```http
POST /s3/api/buckets
{ "name": "example-uploads", "zone": "de1b" }
```

**Terraform**
```hcl
resource "dcloud_bucket" "uploads" {
  name = "example-uploads"
  zone = "de1b"
}
```

To encrypt with a KMS key, add an `dcloud_bucket_encryption` (see
[Change the encryption key](change-the-encryption-key.md)).

## Options

| Option      | Default          | Values                                                                                                         |
| ----------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| Zone        | `de1a`           | `de1a` (Falkenstein), `de1b` (Nuremberg); `fi1a` (Helsinki, Finland) when your organization allows it          |
| Encryption  | the platform key | a KMS key of your organization (`kmsKeyId`)                                                                    |
| Object lock | off              | on: objects can be locked against deletion until a date; turns versioning on for good, chosen only at creation |

See [Storage locations](storage-locations.md) for what a zone means and for buckets on your
organization's own storage.

## Result

The bucket exists at once, empty, with **Block public access** on and encryption on. It answers
at `https://example-uploads.s3.<domain>` and `https://s3.<domain>/example-uploads`; the bucket's
**Address** shows the first. The create answers `201` with the bucket. You pay for what you store
in it from now on (see [What is Object Storage?](what-is.md#pricing)).

A bucket in `fi1a` carries the badge **outside Germany · Finland** in the bucket list.

## If the create is refused

- 400 with the rule the name breaks: `A bucket name is at least 3 characters`,
  `A bucket name is at most 63 characters`, `Dots are not allowed — a bucket name is also a hostname. Use hyphens instead`,
  `Use lowercase letters, digits and hyphens; start and end with a letter or digit`,
  `Two hyphens in a row are not allowed`, `A bucket name cannot start with “xn-”`,
  `That name is reserved`, `Names starting with “rds-” are reserved for database backups`, or
  `Names starting with “kfk-” are reserved for Kafka tiered storage`. Reserved names include
  platform names such as `admin`, `api`, `console`, `s3` and `www` and common words such as
  `backups`, `data`, `dev`, `prod`, `test` and `uploads`.
- 400 `Not a zone with object storage`.
- 400 `This organization's buckets live on its own object store (…); zones do not apply`: leave
  out the zone.
- 400 `KMS key not found`, `That KMS key is not an encryption key`, or `That KMS key is disabled`
  (or another status).
- 403 `Region fi1 (Helsinki, Finland) is outside Germany: an administrator has to allow EU locations outside Germany first (Settings → Data location)`.
- 409 `The bucket name “example-uploads” is already taken. Bucket names are shared by everyone on the platform. Try a more specific one, such as one starting with your company name.`
- 409 `Quota exceeded: Buckets (s3.buckets) — …`: see [Quotas](quotas.md).
- 409 `The platform has reached its object storage bucket limit. Ask support to raise it.`
- 502 `The bucket could not be created. Try again in a moment.`
- 503 with `Retry-After: 60` when your organization's own object store cannot be reached.

## Related

- [Buckets and objects](buckets-and-objects.md)
- [Create an access key](create-an-access-key.md)
- [Delete a bucket](delete-a-bucket.md)
- `s3.buckets.create` · `dcloud s3 buckets create` · `dcloud_bucket`
