# Get started with Object Storage

Create a bucket, create an access key for it, upload and list a file with the AWS CLI, and delete everything again, in about ten minutes.

Replace _example-uploads_ with a bucket name of your own: names are shared by everyone on the
platform, so start it with your company or project.

## Prerequisites

- Permission for `s3:CreateBucket`, `s3:GetBucket`, `s3:PutObject`, `s3:ListObjects`,
  `s3:ListBucketVersions`, `s3:DeleteObjectVersion` and `s3:DeleteBucket`, and
  `iam:CreateUser`, `iam:CreatePolicy`, `iam:AttachUserPolicy`, `iam:CreateAccessKey`,
  `iam:DeleteUser` and `iam:DeletePolicy`.
- The AWS CLI on your computer. For the CLI steps, the dcloud CLI, signed in.

## Step 1: Create a bucket

**Console**
1. Open **Object Storage**, then choose **Create bucket**.
2. For **Name**, enter example-uploads.
3. Choose **Create**.

The bucket's page opens. Its **Address** is `https://example-uploads.s3.<domain>`.

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

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

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

The bucket is in `de1a` (Falkenstein), private, and encrypted with the platform key.

## Step 2: Create an access key for the bucket

The key gets a service account of its own, `example-uploads-access`, whose policy
`s3-read-write-example-uploads` allows this bucket only.

**Console**
1. On the bucket's page, choose the **Access** tab, then **Create access key**. The sheet opens
   with **Service account** set to **A new service account** and **Access to this bucket** set to
   **Read and write**.
2. Choose **Create access key**.
3. Under **Connect a tool**, on the **AWS CLI** tab, copy the lines under **Set up a profile** and
   run them in a terminal. They set up the profile `dcloud` with the key, region `de1` and the
   endpoint. This is the only time the secret is shown.

**CLI**
```sh
dcloud s3 buckets create-access-key example-uploads --description "getting started"
```

Set up a profile with the key's `accessKeyId` and `secretKey` (see
[Use the AWS CLI](use-the-aws-cli.md)).

**API**
```http
POST /s3/api/buckets/example-uploads/access-keys
{ "access": "readwrite", "description": "getting started" }
```

Set up a profile with the key's `accessKeyId` and `secretKey` (see
[Use the AWS CLI](use-the-aws-cli.md)).

**Terraform**
Declare a service account, its policy, the policy attachment and the key, as in
[Give access to one bucket](limit-a-key-to-one-bucket.md).

S3 may take up to 30 seconds to see the new policy.

## Step 3: Upload and list a file

```sh
echo hello > hello.txt
aws --profile dcloud s3 cp ./hello.txt s3://example-uploads/hello.txt
aws --profile dcloud s3 ls s3://example-uploads/
```

The listing shows `hello.txt`. In the console, the bucket's **Objects** tab shows it too.

## Clean up

You pay for what the bucket stores until you delete it.

**Console**
1. On the bucket's page, in the **⋯** menu, choose **Empty bucket**, enter the bucket's name and
   confirm.
2. When the banner says the bucket is emptied, choose **Delete bucket** in the **⋯** menu, enter the
   bucket's name and choose **Delete bucket**.
3. Open **Identity** → **Users**, choose `example-uploads-access`, then **Danger zone** →
   **Delete IAM user**, type its name and confirm. Its key stops working with it.
4. Open the policy `s3-read-write-example-uploads`, choose **Danger zone** → **Delete policy**,
   type its name and confirm.

**CLI**
```sh
dcloud s3 bucket-objects empty example-uploads
dcloud s3 bucket-objects empty-status example-uploads
```

Emptying runs in the background: repeat `empty-status` until its `status` is `done`, then delete
the bucket. Before that, the delete is refused with `409` (the bucket is not empty).

```sh
dcloud s3 buckets delete example-uploads
```

Then `dcloud iam users delete` with the service account's id (`account.id` in the key's answer),
and `dcloud iam policies delete` with the policy's id (`policy.id`).

**API**
```http
POST /s3/api/buckets/example-uploads/empty
```

When `GET /s3/api/buckets/example-uploads/empty` says `done`, call
`DELETE /s3/api/buckets/example-uploads`, then `DELETE /iam/api/users/<account id>` and
`DELETE /iam/api/policies/<policy id>`.

**Terraform**
`terraform destroy` removes the key, the service account, its policy and the bucket; empty the bucket first, since a bucket that
holds objects is not deleted.

## Next steps

- [Upload and download objects](upload-and-download-objects.md)
- [Make objects public](make-objects-public.md)
- [Turn on versioning](turn-on-versioning.md)
