From 1f5eaa614ccdf646008b38196e2feb63370a62dd Mon Sep 17 00:00:00 2001 From: Matt Hilton Date: Mon, 3 Feb 2025 16:12:11 +1100 Subject: [PATCH 1/7] docs: add migration guide for v0.37.1 --- docs/guides/migration-guide-0.37.1.md | 45 +++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/guides/migration-guide-0.37.1.md diff --git a/docs/guides/migration-guide-0.37.1.md b/docs/guides/migration-guide-0.37.1.md new file mode 100644 index 00000000..b692a3ef --- /dev/null +++ b/docs/guides/migration-guide-0.37.1.md @@ -0,0 +1,45 @@ +# v0.37.1 Migration Guide +In this release, we've announced a deprecation that will require action from some customers depending on their configuration + +## Deprecated - `octopusdeploy_project.versioning_strategy` +In this release, we announced the deprecation of the `octopusdeploy_project.versioning_strategy` attribute in favour of the newly introduced `octopusdeploy_project_versioning_strategy` resource. + +### Rationale +The old attribute was constrained because certain use cases for the the versioning strategy need knowledge of the Deployment Process, which is a separate resource. Trying to configure versioning strategies that reference packages used in a process would cause circular-dependency problems in Terraform that aren't an issue in the Octopus Server Portal. To unlock this scenario, we've extracted the versioning strategy to be its own resource, allowing Terraform to properly plan and apply the dependencies between the Project, the Process and the Versioning Strategy. + +### Impact +This change requires some customers to update their HCL. +Only customers who were already using the `octopusdeploy_project.versioning_strategy` attribute are impacted by this change. + +### Timeline +Migration is not yet required, + +| Date | What we'll do | What you need to do | +|------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------| +| 2025-06-04 | **Enactment**: Soft-delete the deprecated attribute (Major release) | Migrate your Terraform config, or use the escape-hatch, before upgrading | +| 2025-12-04 | **Completion**: Remove the deprecated attribute entirely (Patch release) | Migrate your Terraform config before upgrading | + +### How to migrate +This guide assumes that you already have a Project managed by Terraform, which is using the `versioning_strategy` attribute. + +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. + +1. Declare a new resource of type `octopusdeploy_project_versioning_strategy` +1. Set the new resource's `project_id` attribute to the existing Project's ID +1. Explicitly set the new resource's `space_id` attribute to the existing Project's Space ID +1. Explicitly set the new resource to depend on the existing Project +1. Transpose the properties from the existing Project's `versioning_strategy` attribute to the new resource. No changes should be required, as we've kept all names and values compatible between the two. +1. Run a `terraform plan`. The only planned changes should be a modification of the Project to remove the `versioning_strategy` attribute, and creation of the new resource. +1. Once you are satisfied with the planned changes, run a `terraform apply` to complete the migration + +### Escape hatch + +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. + +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. + +| Environment Variable | Required Value | +| - | - | +| `TF_OCTOPUS_DEPRECATION_REVERSALS` | `Project-Versioning-Strategy` | + +This escape hatch will be removed and migration will be required during the [Completion phase](#Timeline) From 5cafa0e2b8839baf7930440104e739e766a71d97 Mon Sep 17 00:00:00 2001 From: Matt Hilton Date: Mon, 3 Feb 2025 16:12:39 +1100 Subject: [PATCH 2/7] docs: add list of breaking changes being tracked --- docs/guides/breaking-changes-list.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 docs/guides/breaking-changes-list.md diff --git a/docs/guides/breaking-changes-list.md b/docs/guides/breaking-changes-list.md new file mode 100644 index 00000000..f16325f1 --- /dev/null +++ b/docs/guides/breaking-changes-list.md @@ -0,0 +1,17 @@ +# Breaking Changes +This page details the breaking changes and deprecations we're managing according to our [Breaking Changes policy](./breaking-changes-policy.md). + +## Announced + +| Version | Deprecated | Replacement | Migration Guide | Enactment | Completion | +| - |---------------------------------------------------------| - | - | - | - | +| [v0.37.1](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.37.1) | `octopusdeploy_project.versioning_strategy` (attribute) | `octopusdeploy_project_versioning_strategy` (new resource) | [Guide](./migration-guide-0.37.1.md) | 2025-06-04 | 2025-12-04 | + +## Enacted + +We aren't currently tracking any enacted Breaking Changes. + + +## Completed + +We aren't currently tracking any completed Breaking Changes. \ No newline at end of file From 94976362815776b3633f0e4089435e9fe3922868 Mon Sep 17 00:00:00 2001 From: Matt Hilton Date: Mon, 3 Feb 2025 16:13:18 +1100 Subject: [PATCH 3/7] chore: fix deprecation message for project versioning_strategy --- octopusdeploy_framework/schemas/project.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/octopusdeploy_framework/schemas/project.go b/octopusdeploy_framework/schemas/project.go index 60d9f9f1..a81d408b 100644 --- a/octopusdeploy_framework/schemas/project.go +++ b/octopusdeploy_framework/schemas/project.go @@ -148,7 +148,7 @@ func (p ProjectSchema) GetResourceSchema() resourceSchema.Schema { }, }, "versioning_strategy": resourceSchema.ListNestedBlock{ - DeprecationMessage: "versioning_strategy is deprecated in favor of resource project_versioning strategy", + DeprecationMessage: "octopusdeploy_project.versioning_strategy is deprecated in favor of resource octopusdeploy_project_versioning_strategy. See https://oc.to/deprecation-tfp-project-versioning-strategy for more info and migration guidance.", NestedObject: resourceSchema.NestedBlockObject{ Attributes: map[string]resourceSchema.Attribute{ "donor_package_step_id": util.ResourceString().Optional().Build(), From bc5b7b9db52d7df6ebe7a7e20b6104bd6572e298 Mon Sep 17 00:00:00 2001 From: Matt Hilton Date: Fri, 7 Feb 2025 11:11:21 +1100 Subject: [PATCH 4/7] docs: update migration guides --- .../guides/migration-guide-v0.37.1.md.tmpl | 14 +- .../guides/migration-guide-v0.8.0.md.tmpl | 0 .../migrations/migration-to-v0.8.0.md.tmpl | 166 ------------------ 3 files changed, 11 insertions(+), 169 deletions(-) rename docs/guides/migration-guide-0.37.1.md => templates/guides/migration-guide-v0.37.1.md.tmpl (72%) rename docs/migrations/migration-to-v0.8.0.md => templates/guides/migration-guide-v0.8.0.md.tmpl (100%) delete mode 100644 templates/migrations/migration-to-v0.8.0.md.tmpl diff --git a/docs/guides/migration-guide-0.37.1.md b/templates/guides/migration-guide-v0.37.1.md.tmpl similarity index 72% rename from docs/guides/migration-guide-0.37.1.md rename to templates/guides/migration-guide-v0.37.1.md.tmpl index b692a3ef..9e47b377 100644 --- a/docs/guides/migration-guide-0.37.1.md +++ b/templates/guides/migration-guide-v0.37.1.md.tmpl @@ -1,5 +1,10 @@ +--- +page_title: "Migrating to v0.37.1" +subcategory: "Upgrades & Migrations" +--- + # v0.37.1 Migration Guide -In this release, we've announced a deprecation that will require action from some customers depending on their configuration +In this release, we've announced a deprecation that will require action from some customers, depending on their configuration ## Deprecated - `octopusdeploy_project.versioning_strategy` In this release, we announced the deprecation of the `octopusdeploy_project.versioning_strategy` attribute in favour of the newly introduced `octopusdeploy_project_versioning_strategy` resource. @@ -22,13 +27,16 @@ Migration is not yet required, ### How to migrate This guide assumes that you already have a Project managed by Terraform, which is using the `versioning_strategy` attribute. +-> This migration removes and then re-configures the Versioning Strategy on the Project, but this is non-destructive as long as you complete the migration in one go and don't try to create releases between removing the old attribute approach and applying the new resource approach. +~> The original `octopusdeploy_project_versioning_strategy` resource had some incorrect schema definitions that didn't match what Octopus Server API expected, which will make following this upgrade guide impossible if you use only a Release Notes `template`, and not a `donor_package`. We fixed this bug in [Release `v0.40.2`](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.40.2). If your config requires using the `template` attribute, please ugprade directly to v0.40.2 or higher. There were no breaking changes between v0.37.1 and v0.40.2. + 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. 1. Declare a new resource of type `octopusdeploy_project_versioning_strategy` 1. Set the new resource's `project_id` attribute to the existing Project's ID 1. Explicitly set the new resource's `space_id` attribute to the existing Project's Space ID 1. Explicitly set the new resource to depend on the existing Project -1. Transpose the properties from the existing Project's `versioning_strategy` attribute to the new resource. No changes should be required, as we've kept all names and values compatible between the two. +1. Transpose the properties from the existing Project's `versioning_strategy` attribute to the new resource. (See the note above about the `template` attribute if you're using it: you may need to go straight to `v0.40.2` to successfully migrate). 1. Run a `terraform plan`. The only planned changes should be a modification of the Project to remove the `versioning_strategy` attribute, and creation of the new resource. 1. Once you are satisfied with the planned changes, run a `terraform apply` to complete the migration @@ -40,6 +48,6 @@ If you're caught out during this period and need a bit more time to migrate, you | Environment Variable | Required Value | | - | - | -| `TF_OCTOPUS_DEPRECATION_REVERSALS` | `Project-Versioning-Strategy` | +| `TF_OCTOPUS_DEPRECATION_REVERSALS` | `Project-Attribute-Versioning-Strategy-0-37-1` | This escape hatch will be removed and migration will be required during the [Completion phase](#Timeline) diff --git a/docs/migrations/migration-to-v0.8.0.md b/templates/guides/migration-guide-v0.8.0.md.tmpl similarity index 100% rename from docs/migrations/migration-to-v0.8.0.md rename to templates/guides/migration-guide-v0.8.0.md.tmpl diff --git a/templates/migrations/migration-to-v0.8.0.md.tmpl b/templates/migrations/migration-to-v0.8.0.md.tmpl deleted file mode 100644 index 0e83a3e7..00000000 --- a/templates/migrations/migration-to-v0.8.0.md.tmpl +++ /dev/null @@ -1,166 +0,0 @@ ---- -page_title: "Migration to v0.8.0" -subcategory: "Migrations" ---- - -`v0.8.0` includes a number of breaking changes. This guide provides an outline of these changes along with tips on migration. - -This guide pertains to configuration that references one of the following resources: - -* `octopusdeploy_account` (was deprecated; now removed) -* `octopusdeploy_deployment_target` (was deprecated; now removed) -* `octopusdeploy_feed` (was deprecated; now removed) -* `octopusdeploy_tag_set` (changed) -* `octopusdeploy_tag` (new; added) - -As always, please ensure to [`validate`](https://www.terraform.io/cli/commands/validate) your configuration and review the changes from [`plan`](https://www.terraform.io/cli/commands/plan) before committing changes through [`apply`](https://www.terraform.io/cli/commands/apply). - -## Pinning a Provider Configuration to v0.7.73 (or Earlier) - -If the configuration fails to [`validate`](https://www.terraform.io/cli/commands/validate) after updating to `v0.8.0` then you can pin the version of the provider to the previous version: `v0.7.73`: - -```terraform -terraform { - required_providers { - octopusdeploy = { - source = "OctopusDeployLabs/octopusdeploy" - version = "0.7.73" # avoid qualifiers for versions, which can be dangerous until v1.0.0 - } - } -} -``` - -At a later time, you may migrate your existing state and configuration to the new resource types. - -## Tag Sets and Tags - -In `v0.8.0`, the `octopusdeploy_tag_set` has been modified by hoisting its embedded `tag` blocks into a separate a distinct resource (`octopusdeploy_tag`). - -Prior to `v0.8.0`, a tag set and tag(s) could be defined as follows: - -```terraform -resource "octopusdeploy_tag_set" "test-tag-set" { - name = "Test Tag Set (OK to Delete)" - - tag { - color = "#FF0000" - name = "test-tag-1" - } - - tag { - color = "#00FF00" - name = "test-tag-2" - } -} -``` - -In `v0.8.0`, the schema has been modified to resemble this: - -```terraform -resource "octopusdeploy_tag_set" "test-tag-set" { - name = "Test Tag Set (OK to Delete)" -} - -resource "octopusdeploy_tag" "us-west" { - color = "#FF0000" - name = "test-tag-1" - tag_set_id = octopusdeploy_tag_set.test-tag-set.id -} - -resource "octopusdeploy_tag" "us-east" { - color = "#00FF00" - name = "test-tag-2" - tag_set_id = octopusdeploy_tag_set.test-tag-set.id -} -``` - -The `octopusdeploy_tag` resource is new and has a required property, `tag_set_id` which associates it with an `octopusdeploy_tag_set` resource. - -## octopusdeploy_account (removed) - -The `octopusdeploy_account` was marked as deprecated and it has removed in `v0.8.0`. There are equivalent replacements available that provide more robust validation: - -* [`octopusdeploy_aws_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/aws_account) -* [`octopusdeploy_azure_service_principal`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_service_principal) -* [`octopusdeploy_azure_subscription_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_subscription_account) -* [`octopusdeploy_gcp_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/gcp_account) -* [`octopusdeploy_ssh_key_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/ssh_key_account) -* [`octopusdeploy_token_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/token_account) -* [`octopusdeploy_username_password_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/username_password_account) - -## octopusdeploy_deployment_target (removed) - -The `octopusdeploy_deployment_target` was marked as deprecated and it has removed in `v0.8.0`. There are equivalent replacements available that provide more robust validation: - -* [`octopusdeploy_azure_cloud_service_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_cloud_service_deployment_target) -* [`octopusdeploy_azure_service_fabric_cluster_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_service_fabric_cluster_deployment_target) -* [`octopusdeploy_azure_web_app_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_web_app_deployment_target) -* [`octopusdeploy_cloud_region_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/cloud_region_deployment_target) -* [`octopusdeploy_kubernetes_cluster_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/kubernetes_cluster_deployment_target) -* [`octopusdeploy_listening_tentacle_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/listening_tentacle_deployment_target) -* [`octopusdeploy_offline_package_drop_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/offline_package_drop_deployment_target) -* [`octopusdeploy_polling_tentacle_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/polling_tentacle_deployment_target) -* [`octopusdeploy_ssh_connection_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/ssh_connection_deployment_target) - -## octopusdeploy_feed (removed) - -The `octopusdeploy_feed` was marked as deprecated and it has removed in `v0.8.0`. There are equivalent replacements available that provide more robust validation: - -* [`octopusdeploy_aws_elastic_container_registry`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/aws_elastic_container_registry) -* [`octopusdeploy_docker_container_registry`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/docker_container_registry) -* [`octopusdeploy_github_repository_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/github_repository_feed) -* [`octopusdeploy_helm_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/helm_feed) -* [`octopusdeploy_maven_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/maven_feed) -* [`octopusdeploy_nuget_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/nuget_feed) - -### Example: `octopusdeploy_feed` to [`octopusdeploy_nuget_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/nuget_feed) - -Assume the following resource: - -```terraform -resource "octopusdeploy_feed" "feed" { - download_attempts = 1 - download_retry_backoff_seconds = 30 - feed_uri = "https://api.nuget.org/v3/index.json" - feed_type = "NuGet" - is_enhanced_mode = true - password = "test-password" - name = "Test NuGet Feed (OK to Delete)" - username = "test-username" -} -``` - -The process to migrate from `v0.7.*` to `v0.8.0` requires three (3) steps: - -1. update configuration by replacing the resource (i.e. `octopusdeploy_feed`) with its replacement (i.e. [`octopusdeploy_nuget_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/nuget_feed)) -2. [`import`](https://www.terraform.io/cli/import) the state to reflect these changes -3. update configuration to reflect your desired changes - -Updating the configuration requires a new and empty resource: - -```terraform -resource "octopusdeploy_nuget_feed" "feed" { -} -``` - -Next, import the existing state via the CLI: - -```shell -$ terraform import octopusdeploy_nuget_feed.feed "Feeds-123" -``` - -The address, `octopusdeploy_nuget_feed.feed` will match the resource in your configuration. The ID field, `"Feeds-123"` is the ID of the feed in Octopus Deploy. - -Finally, you'll need to update the resource to reflect these changes: - -```terraform -resource "octopusdeploy_nuget_feed" "feed" { - download_attempts = 1 - download_retry_backoff_seconds = 30 - feed_uri = "https://api.nuget.org/v3/index.json" - is_enhanced_mode = true - password = "test-password" - name = "Test NuGet Feed (OK to Delete)" - username = "test-username" -} -``` \ No newline at end of file From 0df3eb710ec7fda9a7096cf8ffc5e09b70a3aa97 Mon Sep 17 00:00:00 2001 From: Matt Hilton Date: Fri, 7 Feb 2025 11:13:23 +1100 Subject: [PATCH 5/7] docs: regenerate docs from templates --- docs/guides/breaking-changes-list.md | 8 +- docs/guides/migration-guide-v0.37.1.md | 53 ++++++ docs/guides/migration-guide-v0.8.0.md | 166 ++++++++++++++++++ .../guides/breaking-changes-list.md.tmpl | 21 +++ 4 files changed, 246 insertions(+), 2 deletions(-) create mode 100644 docs/guides/migration-guide-v0.37.1.md create mode 100644 docs/guides/migration-guide-v0.8.0.md create mode 100644 templates/guides/breaking-changes-list.md.tmpl diff --git a/docs/guides/breaking-changes-list.md b/docs/guides/breaking-changes-list.md index f16325f1..0bd417a5 100644 --- a/docs/guides/breaking-changes-list.md +++ b/docs/guides/breaking-changes-list.md @@ -5,7 +5,7 @@ This page details the breaking changes and deprecations we're managing according | Version | Deprecated | Replacement | Migration Guide | Enactment | Completion | | - |---------------------------------------------------------| - | - | - | - | -| [v0.37.1](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.37.1) | `octopusdeploy_project.versioning_strategy` (attribute) | `octopusdeploy_project_versioning_strategy` (new resource) | [Guide](./migration-guide-0.37.1.md) | 2025-06-04 | 2025-12-04 | +| [v0.37.1](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.37.1) | `octopusdeploy_project.versioning_strategy` (attribute) | `octopusdeploy_project_versioning_strategy` (new resource) | [Guide](./migration-guide-v0.37.1.md) | 2025-06-04 | 2025-12-04 | ## Enacted @@ -14,4 +14,8 @@ We aren't currently tracking any enacted Breaking Changes. ## Completed -We aren't currently tracking any completed Breaking Changes. \ No newline at end of file +| Version | Deprecated | Replacement | Migration Guide | Enactment | Completion | +|---------|------------|-------------|-----------------|-----------|------------| +| [v0.8.0](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.8.0) | Many changes* | Many changes* | [Guide](./migration-guide-v0.8.0.md) | N/A | N/A | + +-> *The breaking changes in v0.8.0 were all done years before our Breaking Changes policy was officially established, so didn't follow those procedures, but the Migration Guide is noted here just in case. \ No newline at end of file diff --git a/docs/guides/migration-guide-v0.37.1.md b/docs/guides/migration-guide-v0.37.1.md new file mode 100644 index 00000000..9e47b377 --- /dev/null +++ b/docs/guides/migration-guide-v0.37.1.md @@ -0,0 +1,53 @@ +--- +page_title: "Migrating to v0.37.1" +subcategory: "Upgrades & Migrations" +--- + +# v0.37.1 Migration Guide +In this release, we've announced a deprecation that will require action from some customers, depending on their configuration + +## Deprecated - `octopusdeploy_project.versioning_strategy` +In this release, we announced the deprecation of the `octopusdeploy_project.versioning_strategy` attribute in favour of the newly introduced `octopusdeploy_project_versioning_strategy` resource. + +### Rationale +The old attribute was constrained because certain use cases for the the versioning strategy need knowledge of the Deployment Process, which is a separate resource. Trying to configure versioning strategies that reference packages used in a process would cause circular-dependency problems in Terraform that aren't an issue in the Octopus Server Portal. To unlock this scenario, we've extracted the versioning strategy to be its own resource, allowing Terraform to properly plan and apply the dependencies between the Project, the Process and the Versioning Strategy. + +### Impact +This change requires some customers to update their HCL. +Only customers who were already using the `octopusdeploy_project.versioning_strategy` attribute are impacted by this change. + +### Timeline +Migration is not yet required, + +| Date | What we'll do | What you need to do | +|------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------| +| 2025-06-04 | **Enactment**: Soft-delete the deprecated attribute (Major release) | Migrate your Terraform config, or use the escape-hatch, before upgrading | +| 2025-12-04 | **Completion**: Remove the deprecated attribute entirely (Patch release) | Migrate your Terraform config before upgrading | + +### How to migrate +This guide assumes that you already have a Project managed by Terraform, which is using the `versioning_strategy` attribute. + +-> This migration removes and then re-configures the Versioning Strategy on the Project, but this is non-destructive as long as you complete the migration in one go and don't try to create releases between removing the old attribute approach and applying the new resource approach. +~> The original `octopusdeploy_project_versioning_strategy` resource had some incorrect schema definitions that didn't match what Octopus Server API expected, which will make following this upgrade guide impossible if you use only a Release Notes `template`, and not a `donor_package`. We fixed this bug in [Release `v0.40.2`](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.40.2). If your config requires using the `template` attribute, please ugprade directly to v0.40.2 or higher. There were no breaking changes between v0.37.1 and v0.40.2. + +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. + +1. Declare a new resource of type `octopusdeploy_project_versioning_strategy` +1. Set the new resource's `project_id` attribute to the existing Project's ID +1. Explicitly set the new resource's `space_id` attribute to the existing Project's Space ID +1. Explicitly set the new resource to depend on the existing Project +1. Transpose the properties from the existing Project's `versioning_strategy` attribute to the new resource. (See the note above about the `template` attribute if you're using it: you may need to go straight to `v0.40.2` to successfully migrate). +1. Run a `terraform plan`. The only planned changes should be a modification of the Project to remove the `versioning_strategy` attribute, and creation of the new resource. +1. Once you are satisfied with the planned changes, run a `terraform apply` to complete the migration + +### Escape hatch + +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. + +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. + +| Environment Variable | Required Value | +| - | - | +| `TF_OCTOPUS_DEPRECATION_REVERSALS` | `Project-Attribute-Versioning-Strategy-0-37-1` | + +This escape hatch will be removed and migration will be required during the [Completion phase](#Timeline) diff --git a/docs/guides/migration-guide-v0.8.0.md b/docs/guides/migration-guide-v0.8.0.md new file mode 100644 index 00000000..0e83a3e7 --- /dev/null +++ b/docs/guides/migration-guide-v0.8.0.md @@ -0,0 +1,166 @@ +--- +page_title: "Migration to v0.8.0" +subcategory: "Migrations" +--- + +`v0.8.0` includes a number of breaking changes. This guide provides an outline of these changes along with tips on migration. + +This guide pertains to configuration that references one of the following resources: + +* `octopusdeploy_account` (was deprecated; now removed) +* `octopusdeploy_deployment_target` (was deprecated; now removed) +* `octopusdeploy_feed` (was deprecated; now removed) +* `octopusdeploy_tag_set` (changed) +* `octopusdeploy_tag` (new; added) + +As always, please ensure to [`validate`](https://www.terraform.io/cli/commands/validate) your configuration and review the changes from [`plan`](https://www.terraform.io/cli/commands/plan) before committing changes through [`apply`](https://www.terraform.io/cli/commands/apply). + +## Pinning a Provider Configuration to v0.7.73 (or Earlier) + +If the configuration fails to [`validate`](https://www.terraform.io/cli/commands/validate) after updating to `v0.8.0` then you can pin the version of the provider to the previous version: `v0.7.73`: + +```terraform +terraform { + required_providers { + octopusdeploy = { + source = "OctopusDeployLabs/octopusdeploy" + version = "0.7.73" # avoid qualifiers for versions, which can be dangerous until v1.0.0 + } + } +} +``` + +At a later time, you may migrate your existing state and configuration to the new resource types. + +## Tag Sets and Tags + +In `v0.8.0`, the `octopusdeploy_tag_set` has been modified by hoisting its embedded `tag` blocks into a separate a distinct resource (`octopusdeploy_tag`). + +Prior to `v0.8.0`, a tag set and tag(s) could be defined as follows: + +```terraform +resource "octopusdeploy_tag_set" "test-tag-set" { + name = "Test Tag Set (OK to Delete)" + + tag { + color = "#FF0000" + name = "test-tag-1" + } + + tag { + color = "#00FF00" + name = "test-tag-2" + } +} +``` + +In `v0.8.0`, the schema has been modified to resemble this: + +```terraform +resource "octopusdeploy_tag_set" "test-tag-set" { + name = "Test Tag Set (OK to Delete)" +} + +resource "octopusdeploy_tag" "us-west" { + color = "#FF0000" + name = "test-tag-1" + tag_set_id = octopusdeploy_tag_set.test-tag-set.id +} + +resource "octopusdeploy_tag" "us-east" { + color = "#00FF00" + name = "test-tag-2" + tag_set_id = octopusdeploy_tag_set.test-tag-set.id +} +``` + +The `octopusdeploy_tag` resource is new and has a required property, `tag_set_id` which associates it with an `octopusdeploy_tag_set` resource. + +## octopusdeploy_account (removed) + +The `octopusdeploy_account` was marked as deprecated and it has removed in `v0.8.0`. There are equivalent replacements available that provide more robust validation: + +* [`octopusdeploy_aws_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/aws_account) +* [`octopusdeploy_azure_service_principal`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_service_principal) +* [`octopusdeploy_azure_subscription_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_subscription_account) +* [`octopusdeploy_gcp_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/gcp_account) +* [`octopusdeploy_ssh_key_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/ssh_key_account) +* [`octopusdeploy_token_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/token_account) +* [`octopusdeploy_username_password_account`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/username_password_account) + +## octopusdeploy_deployment_target (removed) + +The `octopusdeploy_deployment_target` was marked as deprecated and it has removed in `v0.8.0`. There are equivalent replacements available that provide more robust validation: + +* [`octopusdeploy_azure_cloud_service_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_cloud_service_deployment_target) +* [`octopusdeploy_azure_service_fabric_cluster_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_service_fabric_cluster_deployment_target) +* [`octopusdeploy_azure_web_app_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/azure_web_app_deployment_target) +* [`octopusdeploy_cloud_region_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/cloud_region_deployment_target) +* [`octopusdeploy_kubernetes_cluster_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/kubernetes_cluster_deployment_target) +* [`octopusdeploy_listening_tentacle_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/listening_tentacle_deployment_target) +* [`octopusdeploy_offline_package_drop_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/offline_package_drop_deployment_target) +* [`octopusdeploy_polling_tentacle_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/polling_tentacle_deployment_target) +* [`octopusdeploy_ssh_connection_deployment_target`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/ssh_connection_deployment_target) + +## octopusdeploy_feed (removed) + +The `octopusdeploy_feed` was marked as deprecated and it has removed in `v0.8.0`. There are equivalent replacements available that provide more robust validation: + +* [`octopusdeploy_aws_elastic_container_registry`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/aws_elastic_container_registry) +* [`octopusdeploy_docker_container_registry`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/docker_container_registry) +* [`octopusdeploy_github_repository_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/github_repository_feed) +* [`octopusdeploy_helm_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/helm_feed) +* [`octopusdeploy_maven_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/maven_feed) +* [`octopusdeploy_nuget_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/nuget_feed) + +### Example: `octopusdeploy_feed` to [`octopusdeploy_nuget_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/nuget_feed) + +Assume the following resource: + +```terraform +resource "octopusdeploy_feed" "feed" { + download_attempts = 1 + download_retry_backoff_seconds = 30 + feed_uri = "https://api.nuget.org/v3/index.json" + feed_type = "NuGet" + is_enhanced_mode = true + password = "test-password" + name = "Test NuGet Feed (OK to Delete)" + username = "test-username" +} +``` + +The process to migrate from `v0.7.*` to `v0.8.0` requires three (3) steps: + +1. update configuration by replacing the resource (i.e. `octopusdeploy_feed`) with its replacement (i.e. [`octopusdeploy_nuget_feed`](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs/resources/nuget_feed)) +2. [`import`](https://www.terraform.io/cli/import) the state to reflect these changes +3. update configuration to reflect your desired changes + +Updating the configuration requires a new and empty resource: + +```terraform +resource "octopusdeploy_nuget_feed" "feed" { +} +``` + +Next, import the existing state via the CLI: + +```shell +$ terraform import octopusdeploy_nuget_feed.feed "Feeds-123" +``` + +The address, `octopusdeploy_nuget_feed.feed` will match the resource in your configuration. The ID field, `"Feeds-123"` is the ID of the feed in Octopus Deploy. + +Finally, you'll need to update the resource to reflect these changes: + +```terraform +resource "octopusdeploy_nuget_feed" "feed" { + download_attempts = 1 + download_retry_backoff_seconds = 30 + feed_uri = "https://api.nuget.org/v3/index.json" + is_enhanced_mode = true + password = "test-password" + name = "Test NuGet Feed (OK to Delete)" + username = "test-username" +} +``` \ No newline at end of file diff --git a/templates/guides/breaking-changes-list.md.tmpl b/templates/guides/breaking-changes-list.md.tmpl new file mode 100644 index 00000000..0bd417a5 --- /dev/null +++ b/templates/guides/breaking-changes-list.md.tmpl @@ -0,0 +1,21 @@ +# Breaking Changes +This page details the breaking changes and deprecations we're managing according to our [Breaking Changes policy](./breaking-changes-policy.md). + +## Announced + +| Version | Deprecated | Replacement | Migration Guide | Enactment | Completion | +| - |---------------------------------------------------------| - | - | - | - | +| [v0.37.1](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.37.1) | `octopusdeploy_project.versioning_strategy` (attribute) | `octopusdeploy_project_versioning_strategy` (new resource) | [Guide](./migration-guide-v0.37.1.md) | 2025-06-04 | 2025-12-04 | + +## Enacted + +We aren't currently tracking any enacted Breaking Changes. + + +## Completed + +| Version | Deprecated | Replacement | Migration Guide | Enactment | Completion | +|---------|------------|-------------|-----------------|-----------|------------| +| [v0.8.0](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.8.0) | Many changes* | Many changes* | [Guide](./migration-guide-v0.8.0.md) | N/A | N/A | + +-> *The breaking changes in v0.8.0 were all done years before our Breaking Changes policy was officially established, so didn't follow those procedures, but the Migration Guide is noted here just in case. \ No newline at end of file From 71f033bac63b0f19c3118959cc90e5968952b5b9 Mon Sep 17 00:00:00 2001 From: Matt Hilton Date: Fri, 7 Feb 2025 11:20:31 +1100 Subject: [PATCH 6/7] docs: fix typo in 0.37.1 migration guide --- docs/guides/migration-guide-v0.37.1.md | 2 +- templates/guides/migration-guide-v0.37.1.md.tmpl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/migration-guide-v0.37.1.md b/docs/guides/migration-guide-v0.37.1.md index 9e47b377..cacf346f 100644 --- a/docs/guides/migration-guide-v0.37.1.md +++ b/docs/guides/migration-guide-v0.37.1.md @@ -17,7 +17,7 @@ This change requires some customers to update their HCL. Only customers who were already using the `octopusdeploy_project.versioning_strategy` attribute are impacted by this change. ### Timeline -Migration is not yet required, +Migration will be required no earlier than 2025-12-04 | Date | What we'll do | What you need to do | |------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------| diff --git a/templates/guides/migration-guide-v0.37.1.md.tmpl b/templates/guides/migration-guide-v0.37.1.md.tmpl index 9e47b377..cacf346f 100644 --- a/templates/guides/migration-guide-v0.37.1.md.tmpl +++ b/templates/guides/migration-guide-v0.37.1.md.tmpl @@ -17,7 +17,7 @@ This change requires some customers to update their HCL. Only customers who were already using the `octopusdeploy_project.versioning_strategy` attribute are impacted by this change. ### Timeline -Migration is not yet required, +Migration will be required no earlier than 2025-12-04 | Date | What we'll do | What you need to do | |------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------| From 5ed7af81ddda459ae072d9e3efed3ac80c05605c Mon Sep 17 00:00:00 2001 From: Matt Hilton Date: Fri, 7 Feb 2025 11:21:26 +1100 Subject: [PATCH 7/7] docs: add missing empty final line --- docs/guides/breaking-changes-list.md | 2 +- templates/guides/breaking-changes-list.md.tmpl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/breaking-changes-list.md b/docs/guides/breaking-changes-list.md index 0bd417a5..8a17154e 100644 --- a/docs/guides/breaking-changes-list.md +++ b/docs/guides/breaking-changes-list.md @@ -18,4 +18,4 @@ We aren't currently tracking any enacted Breaking Changes. |---------|------------|-------------|-----------------|-----------|------------| | [v0.8.0](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.8.0) | Many changes* | Many changes* | [Guide](./migration-guide-v0.8.0.md) | N/A | N/A | --> *The breaking changes in v0.8.0 were all done years before our Breaking Changes policy was officially established, so didn't follow those procedures, but the Migration Guide is noted here just in case. \ No newline at end of file +-> *The breaking changes in v0.8.0 were all done years before our Breaking Changes policy was officially established, so didn't follow those procedures, but the Migration Guide is noted here just in case. diff --git a/templates/guides/breaking-changes-list.md.tmpl b/templates/guides/breaking-changes-list.md.tmpl index 0bd417a5..8a17154e 100644 --- a/templates/guides/breaking-changes-list.md.tmpl +++ b/templates/guides/breaking-changes-list.md.tmpl @@ -18,4 +18,4 @@ We aren't currently tracking any enacted Breaking Changes. |---------|------------|-------------|-----------------|-----------|------------| | [v0.8.0](https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy/releases/tag/v0.8.0) | Many changes* | Many changes* | [Guide](./migration-guide-v0.8.0.md) | N/A | N/A | --> *The breaking changes in v0.8.0 were all done years before our Breaking Changes policy was officially established, so didn't follow those procedures, but the Migration Guide is noted here just in case. \ No newline at end of file +-> *The breaking changes in v0.8.0 were all done years before our Breaking Changes policy was officially established, so didn't follow those procedures, but the Migration Guide is noted here just in case.