|
| 1 | +--- |
| 2 | +title: Azure Blob Storage lifecycle management policy structure |
| 3 | +titleSuffix: Azure Blob Storage |
| 4 | +description: Learn more about the elements of a lifecycle management policy. |
| 5 | +author: normesta |
| 6 | + |
| 7 | +ms.author: normesta |
| 8 | +ms.date: 05/05/2025 |
| 9 | +ms.service: azure-blob-storage |
| 10 | +ms.topic: conceptual |
| 11 | +ms.custom: references_regions, engagement-fy23 |
| 12 | +--- |
| 13 | + |
| 14 | +# Azure Blob Storage lifecycle management policy structure |
| 15 | + |
| 16 | +You can use lifecycle management policies to transition blobs to cost-efficient access tiers based on their use patterns. You can also delete blobs entirely at the end of their lifecycle. A policy can operate on current versions, previous versions and snapshots, but a policy doesn't operate on blobs in system containers such as as the **$logs** or **$web** containers. For general information, see [Azure Blob Storage lifecycle management overview](lifecycle-management-overview.md). |
| 17 | + |
| 18 | +This article describes the elements of a lifecycle management policy. For policy examples, see the following articles: |
| 19 | + |
| 20 | +- [Lifecycle management policies that transition blobs between tiers](lifecycle-management-policy-access-tiers.md) |
| 21 | +- [Lifecycle management policies that deletes blobs](lifecycle-management-policy-delete.md) |
| 22 | + |
| 23 | +> [!TIP] |
| 24 | +> While lifecycle management helps you optimize your costs for a single account, you can use [Azure Storage Actions](../../storage-actions/overview.md) to accomplish multiple data operations at scale across multiple accounts. |
| 25 | +
|
| 26 | +## Rules |
| 27 | + |
| 28 | +A lifecycle management policy is a collection of rules in a JSON document. The following sample JSON shows a complete rule definition: |
| 29 | + |
| 30 | +```json |
| 31 | +{ |
| 32 | + "rules": [ |
| 33 | + { |
| 34 | + "name": "rule1", |
| 35 | + "enabled": true, |
| 36 | + "type": "Lifecycle", |
| 37 | + "definition": {...} |
| 38 | + }, |
| 39 | + { |
| 40 | + "name": "rule2", |
| 41 | + "type": "Lifecycle", |
| 42 | + "definition": {...} |
| 43 | + } |
| 44 | + ] |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +| Parameter name | Parameter type | Notes | |
| 49 | +|----------------|----------------|-------| |
| 50 | +| **rules** | An array of rule objects | At least one rule is required in a policy. You can define up to 100 rules in a policy. | |
| 51 | + |
| 52 | +Each rule within the policy has several parameters, described in the following table: |
| 53 | + |
| 54 | +| Parameter name | Type | Notes | Required | |
| 55 | +|----------------|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|----------| |
| 56 | +| **name** | String | A rule name can include up to 256 alphanumeric characters. The rule name is case-sensitive. It must be unique within a policy. | Yes | |
| 57 | +| **enabled** | Boolean | An optional boolean to allow a rule to be temporarily disabled. The default value is true. | No | |
| 58 | +| **type** | An enum value | The current valid type is `Lifecycle`. | Yes | |
| 59 | +| **definition** | An object that defines the lifecycle rule | Each definition is made up of a filter set and an action set. | Yes | |
| 60 | + |
| 61 | +### Filters |
| 62 | + |
| 63 | +Filters limit actions to a subset of blobs within the storage account. You can use a filter to specify which blobs to include. A filter provides no means to specify which blobs to exclude. If more than one filter is defined, a logical AND is applied to all filters. The following table describes each parameter. |
| 64 | + |
| 65 | +| Filter name | Type | Description | Required | |
| 66 | +|----------------|---------------------------------|--------------------------------------------------------------------------------|----------| |
| 67 | +| **blobTypes** | Array of predefined enum values | The type of blob (either **blockblob** or **appendBlob**) | Yes | |
| 68 | +| **prefixMatch** | Array of strings | These strings are prefixes to be matched. | No | |
| 69 | +| **blobIndexMatch** | An array of dictionary values | These values consist of blob index tag key and value conditions to be matched. | No | |
| 70 | + |
| 71 | +#### Prefix match filter |
| 72 | + |
| 73 | +If you apply the **prefixMatch** filter, then each rule can define up to 10 case-sensitive prefixes. A prefix string must start with a container name. For example, if you want to match all blobs under the path `https://myaccount.blob.core.windows.net/sample-container/blob1/...`, specify the **prefixMatch** as `sample-container/blob1`. |
| 74 | + |
| 75 | +This filter will match all blobs in `sample-container` where the names begin with `blob1`. If you don't define a prefix match, then, the rule applies to all blobs within the storage account. Prefix strings don't support wildcard matching. Characters such as `*` and `?` are treated as string literals. |
| 76 | + |
| 77 | +#### Blob index match filer |
| 78 | + |
| 79 | +If you apply the **blobIndexMatch** filter, then each rule can define up to 10 blob index tag conditions. For example, if you want to match all blobs with `Project = Contoso` under `https://myaccount.blob.core.windows.net/`, then the **blobIndexMatch** filter is `{"name": "Project","op": "==","value": "Contoso"}`. If you don't define a value for the **blobIndexMatch** filter, then the rule applies to all blobs within the storage account. |
| 80 | + |
| 81 | +### Actions |
| 82 | + |
| 83 | +You must define at least one action for each rule. Actions are applied to the filtered blobs when the run condition is met. To learn more about run conditions, see the [Action run conditions](#action-run-conditions) section of this article. The following table describes each action that is available in a policy definition. |
| 84 | + |
| 85 | +| Action | Description | |
| 86 | +|---|---| |
| 87 | +| **TierToCool** | Set a blob to the cool access tier.<br><br>Not supported with append blobs, page blobs, or with blobs in a premium block blob storage account.| |
| 88 | +| **TierToCold** | Set a blob to the cold access tier.<br><br>Not supported with append blobs, page blobs, or with blobs in a premium block blob storage account.| |
| 89 | +| **TierToArchive** | Set a blob to the archive access tier.<br><br>Not supported with append blobs, page blobs, or with blobs in a premium block blob storage account. Also not supported with blobs that use an encryption scope or with blobs in accounts that are configured for Zone-redundant storage (ZRS), geo-zone-redundant storage (GZRS) / read-access geo-zone-redundant storage (RA-GZRS)| |
| 90 | +| **enableAutoTierToHotFromCool** | If a blob is set to the cool tier, this action automatically moves that blob into the hot tier when the blob is accessed.<br>This action is available only when used with the **daysAfterLastAccessTimeGreaterThan** run condition.<br><br>Not supported with previous versions or snapshots. | |
| 91 | +| **Delete** | Deletes a blob.<br><br>Not supported with page blobs or blobs in an immutable container.| |
| 92 | + |
| 93 | +If you define more than one action on the same blob, then lifecycle management applies the least expensive action to the blob. For example, a **delete** action is cheaper than the **tierToArchive** action and the **tierToArchive** action is cheaper than the **tierToCool** action. |
| 94 | + |
| 95 | +#### Delete action in accounts that have a hierarchical namespace |
| 96 | + |
| 97 | +When applied to an account with a hierarchical namespace enabled, a delete action removes empty directories. If the directory isn't empty, then the delete action removes objects that meet the policy conditions within the first lifecycle policy execution cycle. If that action results in an empty directory that also meets the policy conditions, then that directory will be removed within the next execution cycle, and so on. |
| 98 | + |
| 99 | +#### Delete action on blobs that have versions and snapshots |
| 100 | + |
| 101 | +A lifecycle management policy will not delete the current version of a blob until any previous versions or snapshots associated with that blob have been deleted. If blobs in your storage account have previous versions or snapshots, then you must include previous versions and snapshots when you specify a delete action as part of the policy. |
| 102 | + |
| 103 | +### Action run conditions |
| 104 | + |
| 105 | +All run conditions are based on age. If the number of days that have transpired exceeds the number specified for the condition, then the associated action can execute. |
| 106 | + |
| 107 | +Current versions use the last modified time or last access time, previous versions use the version creation time, and blob snapshots use the snapshot creation time to track age. |
| 108 | + |
| 109 | +The following table describes each action run condition. |
| 110 | + |
| 111 | +| Condition name | Type | Description | |
| 112 | +|----------------------------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 113 | +| **daysAfterModificationGreaterThan** | Integer | The age in days after the last modified time blob. Applies to actions on a current version of a blob. | |
| 114 | +| **daysAfterCreationGreaterThan** | Integer | The age in days after the creation time. Applies to actions on the current version of a blob, the previous version of a blob or a blob snapshot. | |
| 115 | +| **daysAfterLastAccessTimeGreaterThan** | Integer | The age in days after the last access time or in some cases, when the date when the policy was enabled. To learn more, see the [Access time tracking](#access-time-tracking) section below. Applies to actions on the current version of a blob when access tracking is enabled. | |
| 116 | +| **daysAfterLastTierChangeGreaterThan** | Integer | The age in days after last blob tier change time. The minimum duration in days that a rehydrated blob is kept in hot, cool or cold tiers before being returned to the archive tier. Applies only to **tierToArchive** actions. | |
| 117 | + |
| 118 | +### Access time tracking |
| 119 | + |
| 120 | +You can enable access time tracking to keep a record of when your blob is last read or written and as a filter to manage tiering and retention of your blob data. |
| 121 | + |
| 122 | +When you enable access time tracking, a blob property called `LastAccessTime` is updated when a blob is read or written. The [Get Blob](/rest/api/storageservices/get-blob) and [Put Blob](/rest/api/storageservices/put-blob) operations are access operations and will update the access time of a blob. However, the [Get Blob Properties](/rest/api/storageservices/get-blob-properties), [Get Blob Metadata](/rest/api/storageservices/get-blob-metadata), and [Get Blob Tags](/rest/api/storageservices/get-blob-tags) aren't access operations. Those operations won't update the access time of a blob. |
| 123 | + |
| 124 | +If you apply the **daysAfterLastAccessTimeGreaterThan** run condition to a policy, then the `LastAccessTime` is used to determine whether that condition is met. |
| 125 | + |
| 126 | +If you apply the **daysAfterLastAccessTimeGreaterThan** run condition to a policy, but you did not enable access time tracking, then the `LastAccessTime` is not used. The date the lifecycle policy was enabled is used instead. In fact, the date that the lifecycle policy was enabled is used in any situation where the `LastAccessTime` property of the blob is a null value. This can happen even if you've enable access time tracking in cases where a blob hasn't been accessed since tracking was enabled. |
| 127 | + |
| 128 | +> [!NOTE] |
| 129 | +> To minimize the effect on read access latency, only the first read of the last 24 hours updates the last access time. Subsequent reads in the same 24-hour period don't update the last access time. If a blob is modified between reads, the last access time is the more recent of the two values. |
| 130 | +
|
| 131 | +To learn how to enable access time tracking, see [Optionally enable access time tracking](lifecycle-management-policy-configure.md#enable-access-time-tracking). |
| 132 | + |
| 133 | +## Next steps |
| 134 | + |
| 135 | +- [Azure Blob Storage lifecycle management overview](lifecycle-management-overview.md). |
| 136 | +- [Configure a lifecycle management policy](lifecycle-management-policy-configure.md) |
| 137 | +- [Access tiers for blob data](access-tiers-overview.md) |
| 138 | +- [Lifecycle management policies that transition blobs between tiers](lifecycle-management-policy-access-tiers.md) |
| 139 | +- [Lifecycle management policies that deletes blobs](lifecycle-management-policy-delete.md) |
| 140 | +- [Lifecycle management policy monitoring](lifecycle-management-policy-monitor.md) |
| 141 | +- [Manage and find data on Azure Blob Storage with blob index](storage-manage-find-blobs.md) |
| 142 | +- [Best practices for using blob access tiers](access-tiers-best-practices.md) |
0 commit comments