diff --git a/docs/content/best-practices/deletion-behaviors.md b/docs/content/best-practices/deletion-behaviors.md index f88ae7da51bb..ded017596929 100644 --- a/docs/content/best-practices/deletion-behaviors.md +++ b/docs/content/best-practices/deletion-behaviors.md @@ -11,10 +11,14 @@ weight: 20 ## Mitigating data loss risk via deletion_protection {#deletion_protection} -Some resources, such as databases, have a significant risk of unrecoverable data loss if the resource is accidentally deleted due to a change to a ForceNew field. For these resources, the best practice is to add a `deletion_protection` field that defaults to `true`, which prevents the resource from being deleted if enabled. Although it is a small breaking change, for users, the benefits of `deletion_protection` defaulting to `true` outweigh the cost. +Some resources, such as databases, have a significant risk of unrecoverable data loss if the resource is accidentally deleted due to a change to a ForceNew field. For these resources, the best practice is to add a `deletion_protection` field that prevents the resource from being deleted if enabled. -APIs also sometimes add `deletion_protection` fields, which will generally default to `false` for backwards-compatibility reasons. Any `deletion_protection` API field added to an existing Terraform resource must match the API default initially. The default may be set to `true` in the next major release. For new Terraform resources, any `deletion_protection` field should default to `true` in Terraform regardless of the API default. When creating the corresponding Terraform field, the name -should match the API field name (i.e. it need not literally be named `deletion_protection` if the API uses something different) and should be the same field type (example: if the API field is an enum, so should the Terraform field). +`deletion_protection` fields generally need to be added with a default of `false` that can be changed to `true` in the next major release, because adding deletion protection is a [major behavioral change]({{< ref "/develop/breaking-changes/breaking-changes/#resource-level-breaking-changes" >}}). Exceptions to this are: + +- The API has a deletion protection field that defaults to enabled on the API side +- The `deletion_protection` field is being added at the same time as the resource + +If the API has a deletion protection field, the corresponding Terraform field name should match the API field's name and type. For example, if the API has an enum field called `what_to_do_on_delete` with values `DELETE` and `PROTECT`, the Terraform field should do the same. A resource can have up to two `deletion_protection` fields (with different names): one that represents a field in the API, and one that is only in Terraform. This could happen because the API added its field after `deletion_protection` already existed in Terraform; it could also happen because a separate field was added in Terraform to make sure that `deletion_protection` is enabled by default. In either case, they should be reconciled into a single field (that defaults to enabled and whose name matches the API field) in the next major release.