> For the complete documentation index, see [llms.txt](https://docs.impossiblecloud.com/impossible-cloud-help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.impossiblecloud.com/impossible-cloud-help/impossible-cloud-storage-guide/buckets-and-objects/object-lifecycle-management.md).

# Object Lifecycle Management

## What object lifecycle management does

An object lifecycle configuration lets a bucket clean up after itself. Instead of running your own deletion jobs, you attach a set of rules to the bucket, and a background process applies them continuously: objects that reach a given age are expired, old versions are removed, and multipart uploads that were never completed are aborted.

We follow the Amazon S3 implementation - see [Managing your storage lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) in the AWS documentation - so the AWS CLI, the AWS SDKs and any S3-compatible tool can set a configuration without modification. Impossible Cloud offers a single storage class, so lifecycle management covers **expiration** actions only - there are no storage class transitions.

Object lifecycle management is available for all accounts in all regions. Lifecycle configurations are currently managed through the S3 API only - the Storage Console does not offer them yet.

{% hint style="warning" %}
**Lifecycle rules permanently delete data.** Once an object or version has been removed by a rule, it cannot be recovered. Test a new configuration on a bucket with non-critical data before applying it to production buckets.
{% endhint %}

## Supported operations

All three calls go to the regional [S3 endpoint](https://docs.impossiblecloud.com/impossible-cloud-help/impossible-cloud-storage-guide/storage-console-urls-and-api-endpoints.md) of the bucket.

| Operation                         | AWS CLI command                                | IAM action                     |
| --------------------------------- | ---------------------------------------------- | ------------------------------ |
| `PutBucketLifecycleConfiguration` | `aws s3api put-bucket-lifecycle-configuration` | `s3:PutLifecycleConfiguration` |
| `GetBucketLifecycleConfiguration` | `aws s3api get-bucket-lifecycle-configuration` | `s3:GetLifecycleConfiguration` |
| `DeleteBucketLifecycle`           | `aws s3api delete-bucket-lifecycle`            | `s3:PutLifecycleConfiguration` |

A `PUT` replaces the whole configuration - there is no call that adds or edits a single rule. Read the current configuration, change it, and write the complete set back.

{% hint style="info" %}
`PutBucketLifecycleConfiguration` requires a payload checksum (`Content-MD5` or an `x-amz-checksum-*` header). Current AWS CLI and SDK versions add one for you; if you build the request by hand, you have to send it yourself.
{% endhint %}

## Anatomy of a rule

A configuration holds one or more rules, and each rule has three parts:

* **A status** - `Enabled` or `Disabled`. A disabled rule is stored but has no effect.
* **A filter** - which objects the rule applies to. The `Filter` element is required; an empty filter selects every object in the bucket.
* **One or more actions** - what happens to the objects the filter selects.

An optional `ID` names the rule (up to 255 characters, unique within the configuration).

### Actions

A rule can carry several actions at once, but each action takes its own parameters:

| Action                           | Parameter                   | Requirement          | What it does                                                                                                               |
| -------------------------------- | --------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Expiration`                     | `Days`                      | Exactly one required | Expires the object once it is this many days old.                                                                          |
|                                  | `Date`                      |                      | Expires the object from this date onwards.                                                                                 |
|                                  | `ExpiredObjectDeleteMarker` |                      | Removes delete markers that have no object versions left behind them.                                                      |
| `NoncurrentVersionExpiration`    | `NoncurrentDays`            | Required             | Permanently deletes object versions that have been noncurrent for this many days.                                          |
|                                  | `NewerNoncurrentVersions`   | Optional             | Keeps this many newer noncurrent versions of the same key, whatever their age.                                             |
| `AbortIncompleteMultipartUpload` | `DaysAfterInitiation`       | Required             | Aborts multipart uploads that were started this many days ago and never completed, and removes the parts already uploaded. |

What `Expiration` means depends on whether the bucket is versioned:

* **Unversioned bucket** - the object is permanently deleted.
* **Versioned bucket** - the current version is hidden behind a delete marker, exactly as a `DELETE` without a version ID would. The data itself is only freed by `NoncurrentVersionExpiration`, so a versioned bucket usually needs both actions to actually reduce stored capacity.

### Filters

| Filter                  | Selects objects…                                  |
| ----------------------- | ------------------------------------------------- |
| `Prefix`                | whose key starts with the given prefix.           |
| `Tag`                   | that carry the given tag key and value.           |
| `ObjectSizeGreaterThan` | larger than the given number of bytes.            |
| `ObjectSizeLessThan`    | smaller than the given number of bytes.           |
| `And`                   | matching **all** of the filters nested inside it. |

The rules for combining them follow Amazon S3:

* A `Filter` contains **exactly one** of `Prefix`, `Tag`, `ObjectSizeGreaterThan`, `ObjectSizeLessThan` or `And` - or nothing at all, which selects every object.
* To combine two or more criteria, nest them in `And`. `And` needs at least two of them, and nothing may sit next to `And` inside the same `Filter`.
* `AbortIncompleteMultipartUpload` cannot be combined with a tag or object size filter: an upload in progress has neither final tags nor a final size. Only a prefix filter applies to it.
* `ExpiredObjectDeleteMarker` cannot be combined with a tag filter, because a delete marker carries no tags.

### Not supported

| Element                                                      | Response                                                                                                 |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `Transition`, `NoncurrentVersionTransition`                  | `501 NotImplemented`. Impossible Cloud has a single storage class, so there is nothing to transition to. |
| `Prefix` directly on the rule (the deprecated pre-2018 form) | `400 MalformedXML`. Use `Filter` with a `Prefix` inside it.                                              |

## Setting a lifecycle configuration

The following configuration expires log files after 90 days, keeps at most three noncurrent versions of any object for 30 days, and cleans up multipart uploads that stalled more than 7 days ago.

{% code title="lifecycle.json" %}

```json
{
  "Rules": [
    {
      "ID": "expire-logs-after-90-days",
      "Status": "Enabled",
      "Filter": { "Prefix": "logs/" },
      "Expiration": { "Days": 90 }
    },
    {
      "ID": "trim-old-versions",
      "Status": "Enabled",
      "Filter": {},
      "NoncurrentVersionExpiration": {
        "NoncurrentDays": 30,
        "NewerNoncurrentVersions": 3
      }
    },
    {
      "ID": "abort-stalled-uploads",
      "Status": "Enabled",
      "Filter": {},
      "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 }
    }
  ]
}
```

{% endcode %}

Apply it, read it back, and remove it again:

```bash
aws s3api put-bucket-lifecycle-configuration \
  --profile impossiblecloud \
  --endpoint-url https://eu-central-2.storage.impossibleapi.net \
  --bucket my-bucket \
  --lifecycle-configuration file://lifecycle.json

aws s3api get-bucket-lifecycle-configuration \
  --profile impossiblecloud \
  --endpoint-url https://eu-central-2.storage.impossibleapi.net \
  --bucket my-bucket

aws s3api delete-bucket-lifecycle \
  --profile impossiblecloud \
  --endpoint-url https://eu-central-2.storage.impossibleapi.net \
  --bucket my-bucket
```

A successful `PUT` returns `200 OK` with an empty body, and `delete-bucket-lifecycle` returns `204 No Content`. Reading a bucket that has no configuration returns `404 NoSuchLifecycleConfiguration`.

Combining several criteria uses `And`, for example "objects under `tmp/` that are larger than 100 MB and tagged `stage=scratch`":

```json
{
  "ID": "expire-large-scratch-files",
  "Status": "Enabled",
  "Filter": {
    "And": {
      "Prefix": "tmp/",
      "ObjectSizeGreaterThan": 104857600,
      "Tags": [{ "Key": "stage", "Value": "scratch" }]
    }
  },
  "Expiration": { "Days": 7 }
}
```

## How and when rules are applied

A lifecycle configuration takes effect as soon as it is stored, but the objects it selects are not removed at that moment. A background process walks through the buckets of the region continuously and applies the rules it finds there.

**Age is counted to the next midnight UTC.** An object with `Expiration.Days: 30` uploaded at 14:00 UTC on 1 March becomes due at 00:00 UTC on 1 April - the creation time is moved forward by the number of days and then rounded up to midnight UTC. `Date` works the same way and must itself be midnight UTC. `NoncurrentDays` is counted from the moment a version became noncurrent, that is when the version replacing it was written, and `DaysAfterInitiation` from the start of the multipart upload.

**Removal happens after that, not exactly on it.** Once an object is due, it is removed on one of the next passes over its bucket. How long that takes depends on how many objects the bucket holds. Plan for expiration to be *eventual* - an object is never removed early, but it may be removed some time after it became due.

{% hint style="warning" %}
**Storage usage is counted until the data is actually removed.** An object that is due for expiration still counts towards your stored capacity until the background process has deleted it. On a versioned bucket, `Expiration` alone never reduces usage at all - it only adds a delete marker, and the versions behind it are freed by `NoncurrentVersionExpiration`.
{% endhint %}

Other behaviour worth knowing:

* **Object Lock is honoured.** A version under a retention period or a legal hold is not removed by a lifecycle rule. It stays in place, and it is picked up on a later pass once the lock has gone. See [Using object lock](https://docs.impossiblecloud.com/impossible-cloud-help/impossible-cloud-storage-guide/buckets-and-objects/versioning-and-object-lock/using-object-lock.md).
* **Overlapping rules: the shortest one wins.** When several rules select the same object, the earliest expiration decides.
* **A disabled rule does nothing** - including undoing what an enabled rule did. Deleting the configuration stops any further action, but nothing that has already been removed comes back.
* **Expiration also clears expired delete markers.** A rule with `Expiration.Days` or `Expiration.Date` removes the delete markers it selects that have no versions left behind them, the same cleanup that `ExpiredObjectDeleteMarker` performs on its own.

## Validation limits

Requests that break one of these are rejected, and nothing is stored - a `PUT` is all or nothing.

| Element                                                                               | Constraint                                                      |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Rule `ID`                                                                             | At most 255 characters, and unique within the configuration.    |
| Rule `Status`                                                                         | `Enabled` or `Disabled`.                                        |
| Actions per rule                                                                      | At least one.                                                   |
| `Expiration.Days`, `NoncurrentDays`, `NewerNoncurrentVersions`, `DaysAfterInitiation` | Positive integers.                                              |
| `Expiration.Date`                                                                     | ISO 8601, at midnight UTC (for example `2026-06-01T00:00:00Z`). |
| `ObjectSizeGreaterThan`                                                               | Between 0 and 1099511627776000 bytes.                           |
| `ObjectSizeLessThan`                                                                  | Between 1 and 1099511627776000 bytes.                           |
| Tag key                                                                               | 1 to 128 characters, unique within the filter.                  |
| Tag value                                                                             | Up to 256 characters.                                           |

## Errors

| Error                          | HTTP | Cause                                                                                                                                                                                  |
| ------------------------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NotImplemented`               | 501  | The configuration uses a transition action.                                                                                                                                            |
| `NoSuchLifecycleConfiguration` | 404  | The bucket has no lifecycle configuration.                                                                                                                                             |
| `MalformedXML`                 | 400  | The configuration does not match the schema - a missing `Filter`, several filters outside an `And`, both `Days` and `Date` on one `Expiration`, or the deprecated rule-level `Prefix`. |
| `InvalidArgument`              | 400  | A value is out of range, such as a non-positive `Days` or a `Date` that is not at midnight UTC. The response names the argument.                                                       |
| `InvalidRequest`               | 400  | A combination that is not allowed, such as `AbortIncompleteMultipartUpload` with a tag filter, or a rule with no action.                                                               |
| `AccessDenied`                 | 403  | The caller is missing `s3:PutLifecycleConfiguration` or `s3:GetLifecycleConfiguration`.                                                                                                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.impossiblecloud.com/impossible-cloud-help/impossible-cloud-storage-guide/buckets-and-objects/object-lifecycle-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
