# Set lifecycle rules

Delete objects, old versions and unfinished multipart uploads by age, applied once a day.

A lifecycle rule deletes what is past its age: current objects after _N_ days, old versions _N_
days after they stopped being current, and multipart uploads left unfinished. What is past its age
is deleted, not moved. Object storage applies the rules once a day. Replace _example-uploads_ with
your bucket's name.

## Prerequisites

- Permission for `s3:PutLifecycleConfiguration` on the bucket (to set and to remove rules).
- In the console, also `s3:GetBucket` on the bucket to open it (without it the bucket's page says
  "Access denied").
- For a bucket on a storage cluster created without object lock: the bucket is still empty when
  you first set rules (see [Storage locations](storage-locations.md#own-storage)).

## Add a rule

**Console**
1. Open the bucket, then choose **Versioning & lifecycle**.
2. Under **Lifecycle rules**, choose **Add rule**.
3. (Optional) For **Name**, enter a name; `rule-1` is filled in.
4. (Optional) For **Prefix**, enter the prefix the rule applies to, for example `tmp/`. Empty
   applies to every object.
5. Fill in at least one of **Delete objects after (days)**, **Delete old versions after (days)**
   and **Abort unfinished uploads after (days)**, or select **Remove delete markers that no longer
   hide any version** (not together with **Delete objects after (days)**).
6. Choose **Add rule**.

The rule is saved at once and listed under **Lifecycle rules**. **Edit**, **Disable** and
**Delete** in a rule's menu also save at once.

**CLI**
```sh
dcloud s3 bucket-lifecycle set example-uploads \
  --rules '{"id":"tmp","prefix":"tmp/","expirationDays":7}' \
  --rules '{"id":"old","noncurrentVersionExpirationDays":30}'
```

**API**
```http
PUT /s3/api/buckets/example-uploads/lifecycle
{ "rules": [{ "id": "tmp", "prefix": "tmp/", "expirationDays": 7 }, { "id": "old", "noncurrentVersionExpirationDays": 30 }] }
```

**Terraform**
```hcl
resource "dcloud_bucket_lifecycle" "uploads" {
  bucket = dcloud_bucket.uploads.id
  rules = jsonencode([
    {
      id                                 = "tmp"
      prefix                             = "tmp/"
      expirationDays                     = 7
      abortIncompleteMultipartUploadDays = 1
    },
  ])
}
```

A `set` replaces every rule of the bucket. Over S3, `aws s3api put-bucket-lifecycle-configuration`
works too.

## Rule fields

| Field                                | Meaning                                                             |
| ------------------------------------ | ------------------------------------------------------------------- |
| `id`                                 | Required, unique in the bucket, 1–255 characters                    |
| `prefix`                             | The keys it applies to; `""` (every object) by default              |
| `enabled`                            | `true` by default                                                   |
| `expirationDays`                     | Delete current objects this many days after they were written       |
| `noncurrentVersionExpirationDays`    | Delete old versions this many days after they stopped being current |
| `abortIncompleteMultipartUploadDays` | Abort multipart uploads left unfinished this many days              |
| `expiredObjectDeleteMarker`          | Remove delete markers that no longer hide any version               |

Days are whole numbers from 1 to 36500. A bucket holds up to 1000 rules.

## Remove every rule

In the console, delete each rule. With the CLI, `dcloud s3 bucket-lifecycle delete example-uploads`;
with the API, `DELETE /s3/api/buckets/example-uploads/lifecycle`; in Terraform, destroy the
`dcloud_bucket_lifecycle`.

## If it is refused

- 400 `rules.0: A lifecycle rule needs at least one action` (the number is the rule's position,
  from 0).
- 400 `rules.0: expirationDays and expiredObjectDeleteMarker cannot be in the same rule`.
- 400 `rules: Each rule needs its own id`.
- 409 `example-uploads shares a storage pool with other buckets, so versioning, lifecycle rules and other store settings need a bucket of its own: …`: set rules on an empty bucket.
- 404 `Not found` for a bucket the platform manages.

An old-version rule has nothing to act on while versioning is off; the console then shows "Old-version rules have nothing to act on."

## Related

- [Turn on versioning](turn-on-versioning.md)
- `s3.bucket-lifecycle.set` · `dcloud s3 bucket-lifecycle set` · `dcloud_bucket_lifecycle`
