Skip to content

Commit 598a1c9

Browse files
Rose-NortheyRose-Northey
authored
add migration guide for deprecating retention_policy block (#108)
add migration guide for replacing `tentacle_retention_policy` and `release_retention_policy` with `tentacle_retention_with_strategy` and `release_retention_with_strategy`
1 parent 0cedc69 commit 598a1c9

File tree

2 files changed

+216
-0
lines changed

2 files changed

+216
-0
lines changed

‎docs/guides/migration-guide-v1.3.12.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
page_title: 'Migrating to v1.3.12'
3+
subcategory: 'Upgrades & Migrations'
4+
---
5+
6+
# v1.3.12 Migration Guide
7+
8+
In this release, we've announced a deprecation that will require action from some customers, depending on their configuration
9+
10+
## Deprecated - lifecycle `retention_policy` blocks
11+
12+
In this release, we announced the deprecation the following lifecycle resource and datasource blocks:
13+
14+
- `octopusdeploy_lifecycles.release_retention_policy`
15+
- `octopusdeploy_lifecycles.tentacle_retention_policy`
16+
- `octopusdeploy_lifecycles.phase.release_retention_policy`
17+
- `octopusdeploy_lifecycles.phase.tentacle_retention_policy`
18+
19+
in favour of the following lifecycle resource blocks:
20+
21+
- `octopusdeploy_lifecycles.release_retention_with_strategy`
22+
- `octopusdeploy_lifecycles.tentacle_retention_with_strategy`
23+
- `octopusdeploy_lifecycles.phase.release_retention_with_strategy`
24+
- `octopusdeploy_lifecycles.phase.tentacle_retention_with_strategy`
25+
26+
**In addition to this**, the fallback retention policy for lifecycles without explicit retention was previously set to "30" "Days". After switching to `retention_with_strategy`, the fallback retention will be "Default". Any phases without explicit retention will still inherit retention from their lifecycle.
27+
28+
### Rationale
29+
30+
In octopus 2025.3 and higher, a customizable default retention setting can be added at the space level and applied to desired lifecycles and phases within that space. The new `retention_with_strategy` blocks support this feature. This feature enables retention of many lifecycles to be changed on mass or more easily initiated at the user’s desired retention.
31+
32+
Lifecycles will now be initially set to the Space Default retention setting (the space default retention setting is initially set to "Keep forever”).
33+
34+
### Impact
35+
36+
This change affects all customers using lifecycles.
37+
38+
Lifecycle resources using `retention_policy` retention settings:
39+
40+
- users will need to change their HCL to use the new `retention_with_strategy` block
41+
42+
Lifecycles resources **without** explicit retention settings:
43+
44+
- if users don't want these lifecycles to have the space default retention, they will need to update their HCL to have explicit retention settings
45+
46+
Lifecycles data source use:
47+
48+
- viewing `retention_policy` settings is potentially inaccurate as it will not show when the space default retention is used
49+
- users will need to update their hcl to access the `retention_with_strategy` blocks instead
50+
51+
### Timeline
52+
53+
Migration will be required no earlier than 21 Oct 2026
54+
55+
| Date | What we'll do | What you need to do |
56+
| ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
57+
| 21 APR 2026 | **Enactment**: Soft-delete the deprecated block (Major release) | Migrate your Terraform config, or use the escape-hatch, before upgrading |
58+
| 21 OCT 2026 | **Completion**: Remove the deprecated block entirely (Patch release) | Migrate your Terraform config before upgrading |
59+
60+
### How to migrate
61+
62+
Please ensure you are working from a clean slate and have no pending changes to your Terraform config, by running a `terraform plan`. If you have outstanding changes, please resolve them before proceeding with this guide.
63+
64+
-> This migration substitutes equivalent resources. This is non-destructive as long as you complete the migration in one go.
65+
66+
1. Within your lifecycle resources, replace all `retention_policy` blocks with `retention_with_strategy` blocks and equivalent retention settings
67+
68+
- e.g. when setting keep forever for the release retention use:
69+
70+
release_retention_with_strategy = {
71+
strategy = “Forever”
72+
}
73+
74+
2. Review all lifecycles without explicit release or tentacle retention blocks and set explicit retention where needed. Note that phases without explicit retention will still inherit from the lifecycle so may not need changes.
75+
All lifecycles without explicit release or tentacle retention blocks are currently being initialised with a retention of “30 days”. If the same behaviour is required after migration, please explicitly set the retention strategy as follows:
76+
77+
release_retention_with_strategy = {
78+
strategy = “Count”
79+
quantity_to_keep = 30
80+
unit = “Days”
81+
}
82+
83+
Or
84+
85+
tentacle_retention_with_strategy = {
86+
strategy = “Count”
87+
quantity_to_keep = 30
88+
unit = “Days”
89+
}
90+
91+
3. If your configuration includes data "octopusdeploy_lifecycles" to view retention properties, only view the `release_retention_with_strategy` and `tentacle_retention_with_strategy` blocks. This will enable you to see when blocks use the space default retention. E.g:
92+
93+
data.octopusdeploy_lifecycles.exampleData.lifecycles[0].release_retention_with_strategy[0]
94+
95+
4. Run `terraform plan`
96+
5. When satisfied, run `terraform apply` to complete the migration
97+
98+
### Escape hatch
99+
100+
We expect customers to migrate their configs in the 6 months between Announcement and Enactment of a deprecation. However, we know that this isn't always possible, so we have a further 6 months grace period.
101+
102+
If you're caught out during this period and need a bit more time to migrate, you can use this escape hatch to revert the soft-deletion from the Enactment stage.
103+
104+
| Environment Variable | Required Value |
105+
| ---------------------------------- | ------------------------------------------- |
106+
| `TF_OCTOPUS_DEPRECATION_REVERSALS` | `octopusdeploy_lifecycles.retention_policy` |
107+
108+
This escape hatch will be removed and migration will be required during the [Completion phase](#Timeline)

‎templates/guides/migration-guide-v1.3.12.md.tmpl‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
page_title: 'Migrating to v1.3.12'
3+
subcategory: 'Upgrades & Migrations'
4+
---
5+
6+
# v1.3.12 Migration Guide
7+
8+
In this release, we've announced a deprecation that will require action from some customers, depending on their configuration
9+
10+
## Deprecated - lifecycle `retention_policy` blocks
11+
12+
In this release, we announced the deprecation the following lifecycle resource and datasource blocks:
13+
14+
- `octopusdeploy_lifecycles.release_retention_policy`
15+
- `octopusdeploy_lifecycles.tentacle_retention_policy`
16+
- `octopusdeploy_lifecycles.phase.release_retention_policy`
17+
- `octopusdeploy_lifecycles.phase.tentacle_retention_policy`
18+
19+
in favour of the following lifecycle resource blocks:
20+
21+
- `octopusdeploy_lifecycles.release_retention_with_strategy`
22+
- `octopusdeploy_lifecycles.tentacle_retention_with_strategy`
23+
- `octopusdeploy_lifecycles.phase.release_retention_with_strategy`
24+
- `octopusdeploy_lifecycles.phase.tentacle_retention_with_strategy`
25+
26+
**In addition to this**, the fallback retention policy for lifecycles without explicit retention was previously set to "30" "Days". After switching to `retention_with_strategy`, the fallback retention will be "Default". Any phases without explicit retention will still inherit retention from their lifecycle.
27+
28+
### Rationale
29+
30+
In octopus 2025.3 and higher, a customizable default retention setting can be added at the space level and applied to desired lifecycles and phases within that space. The new `retention_with_strategy` blocks support this feature. This feature enables retention of many lifecycles to be changed on mass or more easily initiated at the user’s desired retention.
31+
32+
Lifecycles will now be initially set to the Space Default retention setting (the space default retention setting is initially set to "Keep forever”).
33+
34+
### Impact
35+
36+
This change affects all customers using lifecycles.
37+
38+
Lifecycle resources using `retention_policy` retention settings:
39+
40+
- users will need to change their HCL to use the new `retention_with_strategy` block
41+
42+
Lifecycles resources **without** explicit retention settings:
43+
44+
- if users don't want these lifecycles to have the space default retention, they will need to update their HCL to have explicit retention settings
45+
46+
Lifecycles data source use:
47+
48+
- viewing `retention_policy` settings is potentially inaccurate as it will not show when the space default retention is used
49+
- users will need to update their hcl to access the `retention_with_strategy` blocks instead
50+
51+
### Timeline
52+
53+
Migration will be required no earlier than 21 Oct 2026
54+
55+
| Date | What we'll do | What you need to do |
56+
| ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
57+
| 21 APR 2026 | **Enactment**: Soft-delete the deprecated block (Major release) | Migrate your Terraform config, or use the escape-hatch, before upgrading |
58+
| 21 OCT 2026 | **Completion**: Remove the deprecated block entirely (Patch release) | Migrate your Terraform config before upgrading |
59+
60+
### How to migrate
61+
62+
Please ensure you are working from a clean slate and have no pending changes to your Terraform config, by running a `terraform plan`. If you have outstanding changes, please resolve them before proceeding with this guide.
63+
64+
-> This migration substitutes equivalent resources. This is non-destructive as long as you complete the migration in one go.
65+
66+
1. Within your lifecycle resources, replace all `retention_policy` blocks with `retention_with_strategy` blocks and equivalent retention settings
67+
68+
- e.g. when setting keep forever for the release retention use:
69+
70+
release_retention_with_strategy = {
71+
strategy = “Forever”
72+
}
73+
74+
2. Review all lifecycles without explicit release or tentacle retention blocks and set explicit retention where needed. Note that phases without explicit retention will still inherit from the lifecycle so may not need changes.
75+
All lifecycles without explicit release or tentacle retention blocks are currently being initialised with a retention of “30 days”. If the same behaviour is required after migration, please explicitly set the retention strategy as follows:
76+
77+
release_retention_with_strategy = {
78+
strategy = “Count”
79+
quantity_to_keep = 30
80+
unit = “Days”
81+
}
82+
83+
Or
84+
85+
tentacle_retention_with_strategy = {
86+
strategy = “Count”
87+
quantity_to_keep = 30
88+
unit = “Days”
89+
}
90+
91+
3. If your configuration includes data "octopusdeploy_lifecycles" to view retention properties, only view the `release_retention_with_strategy` and `tentacle_retention_with_strategy` blocks. This will enable you to see when blocks use the space default retention. E.g:
92+
93+
data.octopusdeploy_lifecycles.exampleData.lifecycles[0].release_retention_with_strategy[0]
94+
95+
4. Run `terraform plan`
96+
5. When satisfied, run `terraform apply` to complete the migration
97+
98+
### Escape hatch
99+
100+
We expect customers to migrate their configs in the 6 months between Announcement and Enactment of a deprecation. However, we know that this isn't always possible, so we have a further 6 months grace period.
101+
102+
If you're caught out during this period and need a bit more time to migrate, you can use this escape hatch to revert the soft-deletion from the Enactment stage.
103+
104+
| Environment Variable | Required Value |
105+
| ---------------------------------- | ------------------------------------------- |
106+
| `TF_OCTOPUS_DEPRECATION_REVERSALS` | `octopusdeploy_lifecycles.retention_policy` |
107+
108+
This escape hatch will be removed and migration will be required during the [Completion phase](#Timeline)

0 commit comments

Comments
 (0)