Skip to content

Commit

Permalink
update documentation to reflect default behavior between prefix and f…
Browse files Browse the repository at this point in the history 
…ilter in rule block; add more examples in upgrade guide
  • Loading branch information
@anGie44
anGie44 committed Feb 17, 2022
1 parent f24f5ff commit 481687f
Show file tree
Hide file tree
Showing 2 changed files with 201 additions and 2 deletions.
199 changes: 199 additions & 0 deletions website/docs/guides/version-4-upgrade.html.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -467,6 +467,199 @@ your Terraform state and will henceforth be managed by Terraform.

Switch your Terraform configuration to the [`aws_s3_bucket_lifecycle_configuration` resource](/docs/providers/aws/r/s3_bucket_lifecycle_configuration.html) instead.

#### For Lifecycle Rules with no `prefix` previously configured

For example, given this previous configuration:

```terraform
resource "aws_s3_bucket" "example" {
bucket = "my-example-bucket"
lifecycle_rule {
id = "Keep previous version 30 days, then in Glacier another 60"
enabled = true
noncurrent_version_transition {
days = 30
storage_class = "GLACIER"
}
noncurrent_version_expiration {
days = 90
}
}
lifecycle_rule {
id = "Delete old incomplete multi-part uploads"
enabled = true
abort_incomplete_multipart_upload_days = 7
}
}
```

It will receive the following error after upgrading:

```
│ Error: Value for unconfigurable attribute
│
│ with aws_s3_bucket.example,
│ on main.tf line 1, in resource "aws_s3_bucket" "example":
│ 1: resource "aws_s3_bucket" "example" {
│
│ Can't configure a value for "lifecycle_rule": its value will be decided automatically based on the result of applying this configuration.
```

Since the `lifecycle_rule` argument changed to read-only, the recommendation is to update the configuration to use the `aws_s3_bucket_lifecycle_configuration`
resource and remove any references to `lifecycle_rule` and its nested arguments in the `aws_s3_bucket` resource.

~> **Note:** When configuring the `rule.filter` configuration block in the new `aws_s3_bucket_lifecycle_configuration` resource, it is recommended to use the AWS CLI s3api [get-bucket-lifecycle-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/get-bucket-lifecycle-configuration.html)
to fetch the source bucket's lifecycle configuration and determine if the `Filter` is configured as `"Filter" : {}` or `"Filter" : { "Prefix": "" }`.
If the former is returned, `rule.filter` should be configured as `filter {}`. If the latter is returned, `rule.filter` should be configured as follows.

```terraform
resource "aws_s3_bucket" "example" {
# ... other configuration ...
}
resource "aws_s3_bucket_lifecycle_configuration" "example" {
bucket = aws_s3_bucket.example.id
rule {
id = "Keep previous version 30 days, then in Glacier another 60"
status = "Enabled"
filter {
prefix = ""
}
noncurrent_version_transition {
noncurrent_days = 30
storage_class = "GLACIER"
}
noncurrent_version_expiration {
noncurrent_days = 90
}
}
rule {
id = "Delete old incomplete multi-part uploads"
status = "Enabled"
filter {
prefix = ""
}
abort_incomplete_multipart_upload {
days_after_initiation = 7
}
}
}
```

It is then recommended running `terraform import` on each new resource to prevent data loss, e.g.

```shell
$ terraform import aws_s3_bucket_lifecycle_configuration.example example
aws_s3_bucket_lifecycle_configuration.example: Importing from ID "example"...
aws_s3_bucket_lifecycle_configuration.example: Import prepared!
Prepared aws_s3_bucket_lifecycle_configuration for import
aws_s3_bucket_lifecycle_configuration.example: Refreshing state... [id=example]

Import successful!

The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.
```

#### For Lifecycle Rules with `prefix` previously configured as an empty string

For example, given this configuration:

```terraform
resource "aws_s3_bucket" "example" {
bucket = "my-example-bucket"
lifecycle_rule {
id = "log-expiration"
enabled = true
prefix = ""
transition {
days = 30
storage_class = "STANDARD_IA"
}
transition {
days = 180
storage_class = "GLACIER"
}
}
}
```

It will receive the following error after upgrading:

```
│ Error: Value for unconfigurable attribute
│
│ with aws_s3_bucket.example,
│ on main.tf line 1, in resource "aws_s3_bucket" "example":
│ 1: resource "aws_s3_bucket" "example" {
│
│ Can't configure a value for "lifecycle_rule": its value will be decided automatically based on the result of applying this configuration.
```

Since the `lifecycle_rule` argument changed to read-only, the recommendation is to update the configuration to use the `aws_s3_bucket_lifecycle_configuration`
resource and remove any references to `lifecycle_rule` and its nested arguments in the `aws_s3_bucket` resource:

```terraform
resource "aws_s3_bucket" "example" {
# ... other configuration ...
}
resource "aws_s3_bucket_lifecycle_configuration" "example" {
bucket = aws_s3_bucket.example.id
rule {
id = "log-expiration"
status = "Enabled"
filter {
prefix = ""
}
transition {
days = 30
storage_class = "STANDARD_IA"
}
transition {
days = 180
storage_class = "GLACIER"
}
}
}
```

It is then recommended running `terraform import` on each new resource to prevent data loss, e.g.

```shell
$ terraform import aws_s3_bucket_lifecycle_configuration.example example
aws_s3_bucket_lifecycle_configuration.example: Importing from ID "example"...
aws_s3_bucket_lifecycle_configuration.example: Import prepared!
Prepared aws_s3_bucket_lifecycle_configuration for import
aws_s3_bucket_lifecycle_configuration.example: Refreshing state... [id=example]

Import successful!

The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.
```

#### For Lifecycle Rules with a `prefix`


For example, given this previous configuration:

```terraform
Expand All @@ -476,18 +669,22 @@ resource "aws_s3_bucket" "example" {
id = "log"
enabled = true
prefix = "log/"
tags = {
rule = "log"
autoclean = "true"
}
transition {
days = 30
storage_class = "STANDARD_IA"
}
transition {
days = 60
storage_class = "GLACIER"
}
expiration {
days = 90
}
Expand All @@ -497,6 +694,7 @@ resource "aws_s3_bucket" "example" {
id = "tmp"
prefix = "tmp/"
enabled = true
expiration {
date = "2022-12-31"
}
Expand Down Expand Up @@ -534,6 +732,7 @@ resource "aws_s3_bucket_lifecycle_configuration" "example" {
filter {
and {
prefix = "log/"
tags = {
rule = "log"
autoclean = "true"
Expand Down
4 changes: 2 additions & 2 deletions website/docs/r/s3_bucket_lifecycle_configuration.html.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,11 +151,11 @@ The `rule` configuration block supports the following arguments:

* `abort_incomplete_multipart_upload` - (Optional) Configuration block that specifies the days since the initiation of an incomplete multipart upload that Amazon S3 will wait before permanently removing all parts of the upload [documented below](#abort_incomplete_multipart_upload).
* `expiration` - (Optional) Configuration block that specifies the expiration for the lifecycle of the object in the form of date, days and, whether the object has a delete marker [documented below](#expiration).
* `filter` - (Optional) Configuration block used to identify objects that a Lifecycle Rule applies to [documented below](#filter).
* `filter` - (Optional) Configuration block used to identify objects that a Lifecycle Rule applies to [documented below](#filter). If not specified, the `rule` will default to using `prefix`.
* `id` - (Required) Unique identifier for the rule. The value cannot be longer than 255 characters.
* `noncurrent_version_expiration` - (Optional) Configuration block that specifies when noncurrent object versions expire [documented below](#noncurrent_version_expiration).
* `noncurrent_version_transition` - (Optional) Set of configuration blocks that specify the transition rule for the lifecycle rule that describes when noncurrent objects transition to a specific storage class [documented below](#noncurrent_version_transition).
* `prefix` - (Optional) **DEPRECATED** Use `filter` instead. This has been deprecated by Amazon S3. Prefix identifying one or more objects to which the rule applies.
* `prefix` - (Optional) **DEPRECATED** Use `filter` instead. This has been deprecated by Amazon S3. Prefix identifying one or more objects to which the rule applies. Defaults to an empty string (`""`) if `filter` is not specified.
* `status` - (Required) Whether the rule is currently being applied. Valid values: `Enabled` or `Disabled`.
* `transition` - (Optional) Set of configuration blocks that specify when an Amazon S3 object transitions to a specified storage class [documented below](#transition).

Expand Down

0 comments on commit 481687f

Please sign in to comment.