From d260c6c94ed6818e383518c4f1ddda80e476422f Mon Sep 17 00:00:00 2001 From: domenicsim1 Date: Wed, 28 May 2025 09:39:57 +1000 Subject: [PATCH 1/2] chore: more info --- ...eating-a-standardised-space-and-project.md | 9 + .../guides/create-multiple-resources.md | 6 +- ...-create-resource.md => create-resource.md} | 4 +- docs/guides/how-to-find-step-properties.md | 24 +++ .../guides/provider-configuration.md | 4 +- .../{1-terraform.md => why-terraform.md} | 4 +- docs/resources/aws_openid_connect_account.md | 15 +- docs/resources/library_variable_set.md | 44 +---- docs/resources/process_step.md | 2 + .../resources/process_templated_child_step.md | 4 +- docs/resources/tenant_project.md | 17 +- docs/resources/tenant_project_variable.md | 17 +- .../migration-guide-v0.37.1.md | 0 .../migration-guide-v0.8.0.md | 0 .../migration-guide-v1.0.0.md | 0 .../resource.tf | 9 + .../import.sh | 1 + .../octopusdeploy_tenant_project/import.sh | 1 + .../octopusdeploy_tenant_project/resource.tf | 7 + .../import.sh | 1 + .../resource.tf | 7 + ...g-a-standardised-space-and-project.md.tmpl | 9 + templates/guides/3-create-resource.md.tmpl | 57 ------ .../guides/create-multiple-resources.md.tmpl | 6 +- .../how-to-find-step-properties.md.tmpl | 24 +++ .../guides/migration-guide-v0.37.1.md.tmpl | 54 ------ .../guides/migration-guide-v0.8.0.md.tmpl | 166 ------------------ .../guides/migration-guide-v1.0.0.md.tmpl | 80 --------- .../guides/provider-configuration.md.tmpl | 4 +- ...erraform.md.tmpl => why-terraform.md.tmpl} | 4 +- .../aws_openid_connect_account.md.tmpl | 24 +++ .../resources/library_variable_set.md.tmpl | 18 ++ templates/resources/process_step.md.tmpl | 2 + .../process_templated_child_step.md.tmpl | 4 +- templates/resources/tenant_project.md.tmpl | 24 +++ .../resources/tenant_project_variable.md.tmpl | 24 +++ 36 files changed, 258 insertions(+), 418 deletions(-) create mode 100644 docs/examples/creating-a-standardised-space-and-project.md rename templates/guides/4-create-multiple-resources.md.tmpl => docs/guides/create-multiple-resources.md (95%) rename docs/guides/{3-create-resource.md => create-resource.md} (95%) create mode 100644 docs/guides/how-to-find-step-properties.md rename templates/guides/2-provider-configuration.md.tmpl => docs/guides/provider-configuration.md (95%) rename docs/guides/{1-terraform.md => why-terraform.md} (97%) rename docs/{guides => upgrades-and-migrations}/migration-guide-v0.37.1.md (100%) rename docs/{guides => upgrades-and-migrations}/migration-guide-v0.8.0.md (100%) rename docs/{guides => upgrades-and-migrations}/migration-guide-v1.0.0.md (100%) create mode 100644 examples/resources/octopusdeploy_aws_openid_connect_account/resource.tf create mode 100644 examples/resources/octopusdeploy_library_variable_set/import.sh create mode 100644 examples/resources/octopusdeploy_tenant_project/import.sh create mode 100644 examples/resources/octopusdeploy_tenant_project/resource.tf create mode 100644 examples/resources/octopusdeploy_tenant_project_variable/import.sh create mode 100644 examples/resources/octopusdeploy_tenant_project_variable/resource.tf create mode 100644 templates/examples/creating-a-standardised-space-and-project.md.tmpl delete mode 100644 templates/guides/3-create-resource.md.tmpl rename docs/guides/4-create-multiple-resources.md => templates/guides/create-multiple-resources.md.tmpl (95%) create mode 100644 templates/guides/how-to-find-step-properties.md.tmpl delete mode 100644 templates/guides/migration-guide-v0.37.1.md.tmpl delete mode 100644 templates/guides/migration-guide-v0.8.0.md.tmpl delete mode 100644 templates/guides/migration-guide-v1.0.0.md.tmpl rename docs/guides/2-provider-configuration.md => templates/guides/provider-configuration.md.tmpl (95%) rename templates/guides/{1-terraform.md.tmpl => why-terraform.md.tmpl} (97%) create mode 100644 templates/resources/aws_openid_connect_account.md.tmpl create mode 100644 templates/resources/library_variable_set.md.tmpl create mode 100644 templates/resources/tenant_project.md.tmpl create mode 100644 templates/resources/tenant_project_variable.md.tmpl diff --git a/docs/examples/creating-a-standardised-space-and-project.md b/docs/examples/creating-a-standardised-space-and-project.md new file mode 100644 index 000000000..72f4d3708 --- /dev/null +++ b/docs/examples/creating-a-standardised-space-and-project.md @@ -0,0 +1,9 @@ +--- +page_title: "Creating a Standardised Space and Project" +subcategory: "Examples" +--- + +# Creating a Standardised Space and Project + +This example show how to create a standardised space and project that can be used to quickly setup applications used as +microservices. diff --git a/templates/guides/4-create-multiple-resources.md.tmpl b/docs/guides/create-multiple-resources.md similarity index 95% rename from templates/guides/4-create-multiple-resources.md.tmpl rename to docs/guides/create-multiple-resources.md index 3fd1c81bf..01fe57b36 100644 --- a/templates/guides/4-create-multiple-resources.md.tmpl +++ b/docs/guides/create-multiple-resources.md @@ -1,11 +1,11 @@ --- -page_title: "4. Creating Multiple Resources" +page_title: "Creating Multiple Resources" subcategory: "Guides" --- -# 4. Creating multiple Octopus Deploy resources +# Creating multiple Octopus Deploy resources -In step 3, you learned about creating one resource. In this step we will create multiple resources with the same Terraform config file. +In Creating a Resource guide, you learned about creating one resource. In this guide we will create multiple resources with the same Terraform config file. The below Terraform configuration will create the following Octopus Deploy resources: * Environment diff --git a/docs/guides/3-create-resource.md b/docs/guides/create-resource.md similarity index 95% rename from docs/guides/3-create-resource.md rename to docs/guides/create-resource.md index e58d46f9a..959265ccb 100644 --- a/docs/guides/3-create-resource.md +++ b/docs/guides/create-resource.md @@ -1,9 +1,9 @@ --- -page_title: "3. Creating a Resource" +page_title: "Creating a Resource" subcategory: "Guides" --- -# 3. Creating your first Octopus Deploy resource +# Creating your first Octopus Deploy resource ## Provider Setup diff --git a/docs/guides/how-to-find-step-properties.md b/docs/guides/how-to-find-step-properties.md new file mode 100644 index 000000000..29d792024 --- /dev/null +++ b/docs/guides/how-to-find-step-properties.md @@ -0,0 +1,24 @@ +--- +page_title: "How to Find Step Properties" +subcategory: "Guides" +--- + +# How to Find Step Properties + +When defining step properties for a deployment or runbook process it can be challenging to discover the required key and +values for a step. This guides goal is to help with the discovery of step properties. + +To discover properties for a step its best to first define deployment process within the UI including the steps you wish +to use within the provider. Once the deployment process is defined and the step are configured do the following: + +1. Click the ellipsis to the right of the `save` button on the Process Editor page +1. From the menu select `Download as JSON` +1. Open the downloaded JSON file in an editor of your choice +1. Within the JSON you will find a key `Steps`, this is an array of step objects. The objects are in the run order. +1. Locate the key `Properties` within a step object, this maps to the key/value pairs for the `properties` field on the `process_step` resource in HCL. +1. Locate the key `Actions` within a step object, this is and array of actions. Every Step object will have at lest one action, the first action is always related to the step object while additional actions are used to define child steps. +1. Locate the key `Properties` within the first action object of the array, this maps the key/value pairs for the `execution_properties` field on the `process_step` resource in HCL. +1. The following action objects within the array, if any, will map to the `property` key to the `execution_properties` field on the `process_child_step` resource within HCL. + + +Note that in the future we plan to improve the discoverability of step properties. diff --git a/templates/guides/2-provider-configuration.md.tmpl b/docs/guides/provider-configuration.md similarity index 95% rename from templates/guides/2-provider-configuration.md.tmpl rename to docs/guides/provider-configuration.md index 94deaf8af..6b7fec4c9 100644 --- a/templates/guides/2-provider-configuration.md.tmpl +++ b/docs/guides/provider-configuration.md @@ -1,9 +1,9 @@ --- -page_title: "2. Octopus Deploy Provider Configuration" +page_title: "Octopus Deploy Provider Configuration" subcategory: "Guides" --- -# 2. Octopus Deploy Provider Configuration +# Octopus Deploy Provider Configuration ## Example usage diff --git a/docs/guides/1-terraform.md b/docs/guides/why-terraform.md similarity index 97% rename from docs/guides/1-terraform.md rename to docs/guides/why-terraform.md index 31a700d20..916299e2c 100644 --- a/docs/guides/1-terraform.md +++ b/docs/guides/why-terraform.md @@ -1,9 +1,9 @@ --- -page_title: "1. Why Terraform?" +page_title: "Why Terraform?" subcategory: "Guides" --- -# 1. Why Terraform? +# Why Terraform? If you're new to Terraform in general, it may be in your best interest to start with some Terraform Getting Started Docs. diff --git a/docs/resources/aws_openid_connect_account.md b/docs/resources/aws_openid_connect_account.md index 03301f13f..c8714e690 100644 --- a/docs/resources/aws_openid_connect_account.md +++ b/docs/resources/aws_openid_connect_account.md @@ -1,5 +1,4 @@ --- -# generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "octopusdeploy_aws_openid_connect_account Resource - terraform-provider-octopusdeploy" subcategory: "" description: |- @@ -10,7 +9,19 @@ description: |- This resource manages AWS OIDC accounts in Octopus Deploy. - +## Example Usage + +```terraform +resource "octopusdeploy_aws_openid_connect_account" "example" { + name = "AWS OIDC Account" + description = "AWS OIDC Connect Account" + role_arn = "Amazon Resource Name" + account_test_subject_keys = ["space"] + environments = ["environment-123"] + tenants = ["tenants-123"] + execution_subject_keys = ["space"] +} +``` ## Schema diff --git a/docs/resources/library_variable_set.md b/docs/resources/library_variable_set.md index 46bdfca29..b9483d3fc 100644 --- a/docs/resources/library_variable_set.md +++ b/docs/resources/library_variable_set.md @@ -1,5 +1,4 @@ --- -# generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "octopusdeploy_library_variable_set Resource - terraform-provider-octopusdeploy" subcategory: "" description: |- @@ -10,43 +9,10 @@ description: |- This resource manages library variable sets in Octopus Deploy. +## Import +Import is supported using the following syntax: - -## Schema - -### Required - -- `name` (String) The name of this resource. - -### Optional - -- `description` (String) The description of this library variable set. -- `space_id` (String) The space ID associated with this library variable set. -- `template` (Block List) (see [below for nested schema](#nestedblock--template)) - -### Read-Only - -- `id` (String) The unique ID for this resource. -- `template_ids` (Map of String) -- `variable_set_id` (String) - - -### Nested Schema for `template` - -Required: - -- `name` (String) The name of the variable set by the parameter. The name can contain letters, digits, dashes and periods. Example: `ServerName` - -Optional: - -- `default_value` (String) A default value for the parameter, if applicable. This can be a hard-coded value or a variable reference. -- `display_settings` (Map of String) The display settings for the parameter. -- `help_text` (String) The help presented alongside the parameter input. -- `label` (String) The label shown beside the parameter when presented in the deployment process. Example: `Server name`. - -Read-Only: - -- `id` (String) The unique ID for this resource. - - +```shell +terraform import [options] octopusdeploy_library_variable_set. +``` diff --git a/docs/resources/process_step.md b/docs/resources/process_step.md index 420640ec2..61f75af88 100644 --- a/docs/resources/process_step.md +++ b/docs/resources/process_step.md @@ -21,6 +21,8 @@ This resource also contains a concept that doesn't exist in the Octopus Deploy d * `properties` are the inputs to the step itself * `execution_properties` are the controls for _how_ the step runs, particularly relevant in parent/child step situations +For more information on how to discover step properties read the *How to Find Step Properties* under the guides section of the documentation. + ## Example Usage ```terraform diff --git a/docs/resources/process_templated_child_step.md b/docs/resources/process_templated_child_step.md index 032de201c..dd817636f 100644 --- a/docs/resources/process_templated_child_step.md +++ b/docs/resources/process_templated_child_step.md @@ -10,7 +10,9 @@ description: |- This resource manages a child step of a Runbook or Deployment process which based on existing custom step template ### Remarks -This resource exposes only attributes which can be controlled by the consumer of a template. +This resource exposes only attributes which can be controlled by the consumer of a template. + +For more information on how to discover step properties read the *How to Find Step Properties* under the guides section of the documentation. ## Example Usage diff --git a/docs/resources/tenant_project.md b/docs/resources/tenant_project.md index 089ddc20c..8b0cdab31 100644 --- a/docs/resources/tenant_project.md +++ b/docs/resources/tenant_project.md @@ -1,5 +1,4 @@ --- -# generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "octopusdeploy_tenant_project Resource - terraform-provider-octopusdeploy" subcategory: "" description: |- @@ -10,7 +9,17 @@ description: |- +## Example Usage +```terraform +resource "octopusdeploy_tenant_project" "example" { + project_id = "project-123" + tenant_id = "tenant-123" + environment_ids = [ + "environment-123" + ] +} +``` ## Schema @@ -29,4 +38,10 @@ description: |- - `id` (String) The unique ID for this resource. +## Import +Import is supported using the following syntax: + +```shell +terraform import [options] octopusdeploy_tenant_project. +``` diff --git a/docs/resources/tenant_project_variable.md b/docs/resources/tenant_project_variable.md index 053b6739a..2c65a5494 100644 --- a/docs/resources/tenant_project_variable.md +++ b/docs/resources/tenant_project_variable.md @@ -1,5 +1,4 @@ --- -# generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "octopusdeploy_tenant_project_variable Resource - terraform-provider-octopusdeploy" subcategory: "" description: |- @@ -10,7 +9,17 @@ description: |- Manages a tenant project variable in Octopus Deploy. +## Example Usage +```terraform +resource "octopusdeploy_tenant_project_variable" "example" { + environment_id = "environment-123" + project_id = "project-123" + template_id = "template-123" + tenant_id = "tenant-123" + value = "my-tenant-project-variable-value" +} +``` ## Schema @@ -31,4 +40,10 @@ Manages a tenant project variable in Octopus Deploy. - `id` (String) The unique ID for this resource. +## Import +Import is supported using the following syntax: + +```shell +terraform import [options] octopusdeploy_tanant_project_variable. +``` diff --git a/docs/guides/migration-guide-v0.37.1.md b/docs/upgrades-and-migrations/migration-guide-v0.37.1.md similarity index 100% rename from docs/guides/migration-guide-v0.37.1.md rename to docs/upgrades-and-migrations/migration-guide-v0.37.1.md diff --git a/docs/guides/migration-guide-v0.8.0.md b/docs/upgrades-and-migrations/migration-guide-v0.8.0.md similarity index 100% rename from docs/guides/migration-guide-v0.8.0.md rename to docs/upgrades-and-migrations/migration-guide-v0.8.0.md diff --git a/docs/guides/migration-guide-v1.0.0.md b/docs/upgrades-and-migrations/migration-guide-v1.0.0.md similarity index 100% rename from docs/guides/migration-guide-v1.0.0.md rename to docs/upgrades-and-migrations/migration-guide-v1.0.0.md diff --git a/examples/resources/octopusdeploy_aws_openid_connect_account/resource.tf b/examples/resources/octopusdeploy_aws_openid_connect_account/resource.tf new file mode 100644 index 000000000..265cb066d --- /dev/null +++ b/examples/resources/octopusdeploy_aws_openid_connect_account/resource.tf @@ -0,0 +1,9 @@ +resource "octopusdeploy_aws_openid_connect_account" "example" { + name = "AWS OIDC Account" + description = "AWS OIDC Connect Account" + role_arn = "Amazon Resource Name" + account_test_subject_keys = ["space"] + environments = ["environment-123"] + tenants = ["tenants-123"] + execution_subject_keys = ["space"] +} \ No newline at end of file diff --git a/examples/resources/octopusdeploy_library_variable_set/import.sh b/examples/resources/octopusdeploy_library_variable_set/import.sh new file mode 100644 index 000000000..10a298dfd --- /dev/null +++ b/examples/resources/octopusdeploy_library_variable_set/import.sh @@ -0,0 +1 @@ +terraform import [options] octopusdeploy_library_variable_set. diff --git a/examples/resources/octopusdeploy_tenant_project/import.sh b/examples/resources/octopusdeploy_tenant_project/import.sh new file mode 100644 index 000000000..1a352d513 --- /dev/null +++ b/examples/resources/octopusdeploy_tenant_project/import.sh @@ -0,0 +1 @@ +terraform import [options] octopusdeploy_tenant_project. diff --git a/examples/resources/octopusdeploy_tenant_project/resource.tf b/examples/resources/octopusdeploy_tenant_project/resource.tf new file mode 100644 index 000000000..bb5b1cf63 --- /dev/null +++ b/examples/resources/octopusdeploy_tenant_project/resource.tf @@ -0,0 +1,7 @@ +resource "octopusdeploy_tenant_project" "example" { + project_id = "project-123" + tenant_id = "tenant-123" + environment_ids = [ + "environment-123" + ] +} \ No newline at end of file diff --git a/examples/resources/octopusdeploy_tenant_project_variable/import.sh b/examples/resources/octopusdeploy_tenant_project_variable/import.sh new file mode 100644 index 000000000..4b5ac0d8d --- /dev/null +++ b/examples/resources/octopusdeploy_tenant_project_variable/import.sh @@ -0,0 +1 @@ +terraform import [options] octopusdeploy_tanant_project_variable. diff --git a/examples/resources/octopusdeploy_tenant_project_variable/resource.tf b/examples/resources/octopusdeploy_tenant_project_variable/resource.tf new file mode 100644 index 000000000..ea87ce5b8 --- /dev/null +++ b/examples/resources/octopusdeploy_tenant_project_variable/resource.tf @@ -0,0 +1,7 @@ +resource "octopusdeploy_tenant_project_variable" "example" { + environment_id = "environment-123" + project_id = "project-123" + template_id = "template-123" + tenant_id = "tenant-123" + value = "my-tenant-project-variable-value" +} \ No newline at end of file diff --git a/templates/examples/creating-a-standardised-space-and-project.md.tmpl b/templates/examples/creating-a-standardised-space-and-project.md.tmpl new file mode 100644 index 000000000..72f4d3708 --- /dev/null +++ b/templates/examples/creating-a-standardised-space-and-project.md.tmpl @@ -0,0 +1,9 @@ +--- +page_title: "Creating a Standardised Space and Project" +subcategory: "Examples" +--- + +# Creating a Standardised Space and Project + +This example show how to create a standardised space and project that can be used to quickly setup applications used as +microservices. diff --git a/templates/guides/3-create-resource.md.tmpl b/templates/guides/3-create-resource.md.tmpl deleted file mode 100644 index e58d46f9a..000000000 --- a/templates/guides/3-create-resource.md.tmpl +++ /dev/null @@ -1,57 +0,0 @@ ---- -page_title: "3. Creating a Resource" -subcategory: "Guides" ---- - -# 3. Creating your first Octopus Deploy resource - -## Provider Setup - -The provider needs to be configured with proper credentials before it can be used, so first of all we need to create an API key in Octopus that we can then use in our Terraform config. - -### Create an API key - -* Log into the Octopus Web Portal, click your profile image and select **Profile**. -* Click **My API Keys**. -* Click **New API key**, state the purpose of the API key and click **Generate new**. -* Copy the new API key to your Terraform config file. - -### Configure the provider in your Terraform config file. - -```hcl -provider "octopusdeploy" { - address = "https://octopus-cloud-or-server-uri" - api_key = "octous_deploy_api_key" -} -``` - -## Creating your first Octopus Deploy resource - -Once the provider is configured, you can apply the Octopus Deploy resources defined in your Terraform config file. - -The following is an example Terraform config file that creates a new `Project Group` in the `Default` space. - -```hcl -terraform { - required_providers { - octopusdeploy = { - source = OctopusDeployLabs/octopusdeploy - version = ">= 0.7.64" - } - } -} - -provider "octopusdeploy" { - address = "https://octopus-cloud-or-server-uri" - api_key = "octous_deploy_api_key" -} - -resource "octopusdeploy_project_group" "DevOpsProjects" { - name = "DevOps Projects" - description = "My DevOps projects group" -} -``` - -1. Use `terraform init` to download the specified version of the Octopus Deploy provider. -2. Next, use `terraform plan` to display a list of resources to be created, and highlight any possible unknown attributes at apply time. -3. Finally, use `terraform apply` to create the resource shown in the output from the step above. \ No newline at end of file diff --git a/docs/guides/4-create-multiple-resources.md b/templates/guides/create-multiple-resources.md.tmpl similarity index 95% rename from docs/guides/4-create-multiple-resources.md rename to templates/guides/create-multiple-resources.md.tmpl index 3fd1c81bf..01fe57b36 100644 --- a/docs/guides/4-create-multiple-resources.md +++ b/templates/guides/create-multiple-resources.md.tmpl @@ -1,11 +1,11 @@ --- -page_title: "4. Creating Multiple Resources" +page_title: "Creating Multiple Resources" subcategory: "Guides" --- -# 4. Creating multiple Octopus Deploy resources +# Creating multiple Octopus Deploy resources -In step 3, you learned about creating one resource. In this step we will create multiple resources with the same Terraform config file. +In Creating a Resource guide, you learned about creating one resource. In this guide we will create multiple resources with the same Terraform config file. The below Terraform configuration will create the following Octopus Deploy resources: * Environment diff --git a/templates/guides/how-to-find-step-properties.md.tmpl b/templates/guides/how-to-find-step-properties.md.tmpl new file mode 100644 index 000000000..29d792024 --- /dev/null +++ b/templates/guides/how-to-find-step-properties.md.tmpl @@ -0,0 +1,24 @@ +--- +page_title: "How to Find Step Properties" +subcategory: "Guides" +--- + +# How to Find Step Properties + +When defining step properties for a deployment or runbook process it can be challenging to discover the required key and +values for a step. This guides goal is to help with the discovery of step properties. + +To discover properties for a step its best to first define deployment process within the UI including the steps you wish +to use within the provider. Once the deployment process is defined and the step are configured do the following: + +1. Click the ellipsis to the right of the `save` button on the Process Editor page +1. From the menu select `Download as JSON` +1. Open the downloaded JSON file in an editor of your choice +1. Within the JSON you will find a key `Steps`, this is an array of step objects. The objects are in the run order. +1. Locate the key `Properties` within a step object, this maps to the key/value pairs for the `properties` field on the `process_step` resource in HCL. +1. Locate the key `Actions` within a step object, this is and array of actions. Every Step object will have at lest one action, the first action is always related to the step object while additional actions are used to define child steps. +1. Locate the key `Properties` within the first action object of the array, this maps the key/value pairs for the `execution_properties` field on the `process_step` resource in HCL. +1. The following action objects within the array, if any, will map to the `property` key to the `execution_properties` field on the `process_child_step` resource within HCL. + + +Note that in the future we plan to improve the discoverability of step properties. diff --git a/templates/guides/migration-guide-v0.37.1.md.tmpl b/templates/guides/migration-guide-v0.37.1.md.tmpl deleted file mode 100644 index f55e0597d..000000000 --- a/templates/guides/migration-guide-v0.37.1.md.tmpl +++ /dev/null @@ -1,54 +0,0 @@ ---- -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 will be required no earlier than 2025-12-04 - -| 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/templates/guides/migration-guide-v0.8.0.md.tmpl b/templates/guides/migration-guide-v0.8.0.md.tmpl deleted file mode 100644 index 780dd0b64..000000000 --- a/templates/guides/migration-guide-v0.8.0.md.tmpl +++ /dev/null @@ -1,166 +0,0 @@ ---- -page_title: "Migrating to v0.8.0" -subcategory: "Upgrades & 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/migration-guide-v1.0.0.md.tmpl b/templates/guides/migration-guide-v1.0.0.md.tmpl deleted file mode 100644 index 222533eca..000000000 --- a/templates/guides/migration-guide-v1.0.0.md.tmpl +++ /dev/null @@ -1,80 +0,0 @@ ---- -page_title: "Migrating to v1.0.0" -subcategory: "Upgrades & Migrations" ---- - -# v1.0.0 Migration Guide -In this release, we've announced a deprecation that will require action from some customers, depending on their configuration - -## Deprecated - `octopusdeploy_deployment_process` -In this release, we announced the deprecation of the `octopusdeploy_deployment_process` resource in favour of the newly introduced `octopusdeploy_process` resource. - -## Deprecated - `octopusdeploy_runbook_process` -In this release, we announced the deprecation of the `octopusdeploy_runbook_process` resource in favour of the newly introduced `octopusdeploy_process` resource. - -### Rationale -The old resources are prone to state drift issues due to how the schema was defined within in the provider, this would often lead to issues such as not being able to reorder or add additional steps to the process. In addition, the old resources design did not allow for new features such as the ability to use step templates easily. - -### Impact -This change requires some customers to update their HCL. -Only customers who were already using the `octopusdeploy_deployment_process` or `octopusdeploy_runbook_process` resources are impacted by this change. - -### Timeline -Migration will be required no earlier than 2026-05-10 - -| Date | What we'll do | What you need to do | -|------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------| -| 2025-11-05 | **Enactment**: Soft-delete the deprecated attribute (Major release) | Migrate your Terraform config, or use the escape-hatch, before upgrading | -| 2026-05-05 | **Completion**: Remove the deprecated resources entirely (Patch release) | Migrate your Terraform config before upgrading | - -### How to migrate - -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. - --> This migration removes the old deployment process and replaces it with the process resource, this is non-destructive as long as you complete the migration in one go. - -1. Declare a new resource of type `octopusdeploy_process` -1. Set the `project_id` to the existing Project's ID and if migrating a runbook process set the `runbook_id` to the existing Runbook's ID -1. Declare a new resource of type `octopusdeploy_process_step` -1. Set the `process_id` to the `id` of the new process resource -1. Transpose the `name` -1. Transpose the `type`, `type` is the type of embedded action which corresponds to `action_type` in the `action` block, for built-in action like `run_script_action` this is hidden. -1. Transpose the `properties` and `execution_properties` to the new resource from a `step` and `action` in the old deployment process, `properties` are those that are set on the step level and `execution_properties` are those historically set on the `action`. Note that the process step name of the embedded action is now always the same as the name of the step, this can introduce some changes during migration when the name of the first action of a step is different from its step name. -1. Transpose `run_on_server` to the `execution_properties` using the key `Octopus.Action.RunOnServer` -1. Transpose `window_size` to the `execution_properties` using the key `Octopus.Action.TargetRoles` -1. Transpose `target_roles` to the `properties` using the key `Octopus.Action.TargetRoles` -1. Transpose `primary_package` to the `packages` attribute with the key being an empty string `""` -1. Repeat until all parent `steps` have been transposed -1. For child steps create a new resource of type `octopusdeploy_process_child_step` (nested actions) -1. Set the `process_id` to the `id` of the new process resource -1. Set the `parent_id` to the owning `octopusdeploy_process_step.id` -1. Repeat until all child `steps` (actions) have been transposed -1. Declare a new `octopusdeploy_process_steps_order` resource -1. Set the `process_id` to the `id` of the new process resource -1. Set the list of `steps` to a list of `octopusdeploy_process_step.id` in the order you would like the steps to execute -1. For child `step` order declare a new `octopusdeploy_process_child_steps_order`, do this for each group of child steps. -1. Set the `process_id` to the `id` of the new process resource -1. Set the `parent_id` to the owning `octopusdeploy_process_step.id` -1. Set the list of `children` to a list of `octopusdeploy_process_child_step.id` in the order you would like the child steps to execute -1. Note down the existing `process_id`, `step_id`'s and `action_id`'s stored in the `tfstate` file deployment process being migrated -1. Run `terraform state rm [options] 'octopusdeploy_deployment_process.'` to remove the old deployment process from state -1. Remove the old deployment process from the terraform config -1. Run `terraform import [options] octopusdeploy_process. ` to load the new process into state -1. Run `terraform import [options] octopusdeploy_process_step. ":"` for each step to load them into state -1. Run `terraform import [options] octopusdeploy_process_steps_order. ` to load the process step oder into state -1. Run `terraform import [options] octopusdeploy_process_child_step. "::"` for each child step to load them into order -1. Run `terraform import [options] octopusdeploy_process_child_steps_order. ":"` for each child step group to load them into state -1. Run `terraform plan` to see if anything is missing from state, fix accordingly -1. When satisfied run `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` | `Process_v1.0.0` | - -This escape hatch will be removed and migration will be required during the [Completion phase](#Timeline) diff --git a/docs/guides/2-provider-configuration.md b/templates/guides/provider-configuration.md.tmpl similarity index 95% rename from docs/guides/2-provider-configuration.md rename to templates/guides/provider-configuration.md.tmpl index 94deaf8af..6b7fec4c9 100644 --- a/docs/guides/2-provider-configuration.md +++ b/templates/guides/provider-configuration.md.tmpl @@ -1,9 +1,9 @@ --- -page_title: "2. Octopus Deploy Provider Configuration" +page_title: "Octopus Deploy Provider Configuration" subcategory: "Guides" --- -# 2. Octopus Deploy Provider Configuration +# Octopus Deploy Provider Configuration ## Example usage diff --git a/templates/guides/1-terraform.md.tmpl b/templates/guides/why-terraform.md.tmpl similarity index 97% rename from templates/guides/1-terraform.md.tmpl rename to templates/guides/why-terraform.md.tmpl index 31a700d20..916299e2c 100644 --- a/templates/guides/1-terraform.md.tmpl +++ b/templates/guides/why-terraform.md.tmpl @@ -1,9 +1,9 @@ --- -page_title: "1. Why Terraform?" +page_title: "Why Terraform?" subcategory: "Guides" --- -# 1. Why Terraform? +# Why Terraform? If you're new to Terraform in general, it may be in your best interest to start with some Terraform Getting Started Docs. diff --git a/templates/resources/aws_openid_connect_account.md.tmpl b/templates/resources/aws_openid_connect_account.md.tmpl new file mode 100644 index 000000000..caa8d12a9 --- /dev/null +++ b/templates/resources/aws_openid_connect_account.md.tmpl @@ -0,0 +1,24 @@ +--- +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +subcategory: "" +description: |- +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +## Example Usage + +{{ tffile (printf "%s%s%s" "examples/resources/" .Name "/resource.tf") }} + +{{ .SchemaMarkdown | trimspace }} + +{{ if .HasImport -}} +## Import + +Import is supported using the following syntax: + +{{ codefile "shell" (printf "%s%s%s" "examples/resources/" .Name "/import.sh") }} +{{- end }} diff --git a/templates/resources/library_variable_set.md.tmpl b/templates/resources/library_variable_set.md.tmpl new file mode 100644 index 000000000..e8fd502f8 --- /dev/null +++ b/templates/resources/library_variable_set.md.tmpl @@ -0,0 +1,18 @@ +--- +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +subcategory: "" +description: |- +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +{{ if .HasImport -}} +## Import + +Import is supported using the following syntax: + +{{ codefile "shell" (printf "%s%s%s" "examples/resources/" .Name "/import.sh") }} +{{- end }} diff --git a/templates/resources/process_step.md.tmpl b/templates/resources/process_step.md.tmpl index ea93dfa30..f404af64a 100644 --- a/templates/resources/process_step.md.tmpl +++ b/templates/resources/process_step.md.tmpl @@ -21,6 +21,8 @@ This resource also contains a concept that doesn't exist in the Octopus Deploy d * `properties` are the inputs to the step itself * `execution_properties` are the controls for _how_ the step runs, particularly relevant in parent/child step situations +For more information on how to discover step properties read the *How to Find Step Properties* under the guides section of the documentation. + ## Example Usage {{ tffile (printf "%s%s%s" "examples/resources/" .Name "/resource.tf") }} diff --git a/templates/resources/process_templated_child_step.md.tmpl b/templates/resources/process_templated_child_step.md.tmpl index 56b46a9e6..e6bd6db27 100644 --- a/templates/resources/process_templated_child_step.md.tmpl +++ b/templates/resources/process_templated_child_step.md.tmpl @@ -10,7 +10,9 @@ description: |- {{ .Description | trimspace }} ### Remarks -This resource exposes only attributes which can be controlled by the consumer of a template. +This resource exposes only attributes which can be controlled by the consumer of a template. + +For more information on how to discover step properties read the *How to Find Step Properties* under the guides section of the documentation. ## Example Usage diff --git a/templates/resources/tenant_project.md.tmpl b/templates/resources/tenant_project.md.tmpl new file mode 100644 index 000000000..caa8d12a9 --- /dev/null +++ b/templates/resources/tenant_project.md.tmpl @@ -0,0 +1,24 @@ +--- +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +subcategory: "" +description: |- +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +## Example Usage + +{{ tffile (printf "%s%s%s" "examples/resources/" .Name "/resource.tf") }} + +{{ .SchemaMarkdown | trimspace }} + +{{ if .HasImport -}} +## Import + +Import is supported using the following syntax: + +{{ codefile "shell" (printf "%s%s%s" "examples/resources/" .Name "/import.sh") }} +{{- end }} diff --git a/templates/resources/tenant_project_variable.md.tmpl b/templates/resources/tenant_project_variable.md.tmpl new file mode 100644 index 000000000..caa8d12a9 --- /dev/null +++ b/templates/resources/tenant_project_variable.md.tmpl @@ -0,0 +1,24 @@ +--- +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +subcategory: "" +description: |- +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +## Example Usage + +{{ tffile (printf "%s%s%s" "examples/resources/" .Name "/resource.tf") }} + +{{ .SchemaMarkdown | trimspace }} + +{{ if .HasImport -}} +## Import + +Import is supported using the following syntax: + +{{ codefile "shell" (printf "%s%s%s" "examples/resources/" .Name "/import.sh") }} +{{- end }} From 5b7326c346786852ecf2669d30b6c52e995f1139 Mon Sep 17 00:00:00 2001 From: domenicsim1 Date: Wed, 28 May 2025 09:40:03 +1000 Subject: [PATCH 2/2] chore: more info --- templates/guides/create-resource.md.tmpl | 57 ++++++ .../migration-guide-v0.37.1.md.tmpl | 54 ++++++ .../migration-guide-v0.8.0.md.tmpl | 166 ++++++++++++++++++ .../migration-guide-v1.0.0.md.tmpl | 80 +++++++++ 4 files changed, 357 insertions(+) create mode 100644 templates/guides/create-resource.md.tmpl create mode 100644 templates/upgrades-and-migrations/migration-guide-v0.37.1.md.tmpl create mode 100644 templates/upgrades-and-migrations/migration-guide-v0.8.0.md.tmpl create mode 100644 templates/upgrades-and-migrations/migration-guide-v1.0.0.md.tmpl diff --git a/templates/guides/create-resource.md.tmpl b/templates/guides/create-resource.md.tmpl new file mode 100644 index 000000000..959265ccb --- /dev/null +++ b/templates/guides/create-resource.md.tmpl @@ -0,0 +1,57 @@ +--- +page_title: "Creating a Resource" +subcategory: "Guides" +--- + +# Creating your first Octopus Deploy resource + +## Provider Setup + +The provider needs to be configured with proper credentials before it can be used, so first of all we need to create an API key in Octopus that we can then use in our Terraform config. + +### Create an API key + +* Log into the Octopus Web Portal, click your profile image and select **Profile**. +* Click **My API Keys**. +* Click **New API key**, state the purpose of the API key and click **Generate new**. +* Copy the new API key to your Terraform config file. + +### Configure the provider in your Terraform config file. + +```hcl +provider "octopusdeploy" { + address = "https://octopus-cloud-or-server-uri" + api_key = "octous_deploy_api_key" +} +``` + +## Creating your first Octopus Deploy resource + +Once the provider is configured, you can apply the Octopus Deploy resources defined in your Terraform config file. + +The following is an example Terraform config file that creates a new `Project Group` in the `Default` space. + +```hcl +terraform { + required_providers { + octopusdeploy = { + source = OctopusDeployLabs/octopusdeploy + version = ">= 0.7.64" + } + } +} + +provider "octopusdeploy" { + address = "https://octopus-cloud-or-server-uri" + api_key = "octous_deploy_api_key" +} + +resource "octopusdeploy_project_group" "DevOpsProjects" { + name = "DevOps Projects" + description = "My DevOps projects group" +} +``` + +1. Use `terraform init` to download the specified version of the Octopus Deploy provider. +2. Next, use `terraform plan` to display a list of resources to be created, and highlight any possible unknown attributes at apply time. +3. Finally, use `terraform apply` to create the resource shown in the output from the step above. \ No newline at end of file diff --git a/templates/upgrades-and-migrations/migration-guide-v0.37.1.md.tmpl b/templates/upgrades-and-migrations/migration-guide-v0.37.1.md.tmpl new file mode 100644 index 000000000..f55e0597d --- /dev/null +++ b/templates/upgrades-and-migrations/migration-guide-v0.37.1.md.tmpl @@ -0,0 +1,54 @@ +--- +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 will be required no earlier than 2025-12-04 + +| 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/templates/upgrades-and-migrations/migration-guide-v0.8.0.md.tmpl b/templates/upgrades-and-migrations/migration-guide-v0.8.0.md.tmpl new file mode 100644 index 000000000..780dd0b64 --- /dev/null +++ b/templates/upgrades-and-migrations/migration-guide-v0.8.0.md.tmpl @@ -0,0 +1,166 @@ +--- +page_title: "Migrating to v0.8.0" +subcategory: "Upgrades & 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/upgrades-and-migrations/migration-guide-v1.0.0.md.tmpl b/templates/upgrades-and-migrations/migration-guide-v1.0.0.md.tmpl new file mode 100644 index 000000000..222533eca --- /dev/null +++ b/templates/upgrades-and-migrations/migration-guide-v1.0.0.md.tmpl @@ -0,0 +1,80 @@ +--- +page_title: "Migrating to v1.0.0" +subcategory: "Upgrades & Migrations" +--- + +# v1.0.0 Migration Guide +In this release, we've announced a deprecation that will require action from some customers, depending on their configuration + +## Deprecated - `octopusdeploy_deployment_process` +In this release, we announced the deprecation of the `octopusdeploy_deployment_process` resource in favour of the newly introduced `octopusdeploy_process` resource. + +## Deprecated - `octopusdeploy_runbook_process` +In this release, we announced the deprecation of the `octopusdeploy_runbook_process` resource in favour of the newly introduced `octopusdeploy_process` resource. + +### Rationale +The old resources are prone to state drift issues due to how the schema was defined within in the provider, this would often lead to issues such as not being able to reorder or add additional steps to the process. In addition, the old resources design did not allow for new features such as the ability to use step templates easily. + +### Impact +This change requires some customers to update their HCL. +Only customers who were already using the `octopusdeploy_deployment_process` or `octopusdeploy_runbook_process` resources are impacted by this change. + +### Timeline +Migration will be required no earlier than 2026-05-10 + +| Date | What we'll do | What you need to do | +|------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------| +| 2025-11-05 | **Enactment**: Soft-delete the deprecated attribute (Major release) | Migrate your Terraform config, or use the escape-hatch, before upgrading | +| 2026-05-05 | **Completion**: Remove the deprecated resources entirely (Patch release) | Migrate your Terraform config before upgrading | + +### How to migrate + +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. + +-> This migration removes the old deployment process and replaces it with the process resource, this is non-destructive as long as you complete the migration in one go. + +1. Declare a new resource of type `octopusdeploy_process` +1. Set the `project_id` to the existing Project's ID and if migrating a runbook process set the `runbook_id` to the existing Runbook's ID +1. Declare a new resource of type `octopusdeploy_process_step` +1. Set the `process_id` to the `id` of the new process resource +1. Transpose the `name` +1. Transpose the `type`, `type` is the type of embedded action which corresponds to `action_type` in the `action` block, for built-in action like `run_script_action` this is hidden. +1. Transpose the `properties` and `execution_properties` to the new resource from a `step` and `action` in the old deployment process, `properties` are those that are set on the step level and `execution_properties` are those historically set on the `action`. Note that the process step name of the embedded action is now always the same as the name of the step, this can introduce some changes during migration when the name of the first action of a step is different from its step name. +1. Transpose `run_on_server` to the `execution_properties` using the key `Octopus.Action.RunOnServer` +1. Transpose `window_size` to the `execution_properties` using the key `Octopus.Action.TargetRoles` +1. Transpose `target_roles` to the `properties` using the key `Octopus.Action.TargetRoles` +1. Transpose `primary_package` to the `packages` attribute with the key being an empty string `""` +1. Repeat until all parent `steps` have been transposed +1. For child steps create a new resource of type `octopusdeploy_process_child_step` (nested actions) +1. Set the `process_id` to the `id` of the new process resource +1. Set the `parent_id` to the owning `octopusdeploy_process_step.id` +1. Repeat until all child `steps` (actions) have been transposed +1. Declare a new `octopusdeploy_process_steps_order` resource +1. Set the `process_id` to the `id` of the new process resource +1. Set the list of `steps` to a list of `octopusdeploy_process_step.id` in the order you would like the steps to execute +1. For child `step` order declare a new `octopusdeploy_process_child_steps_order`, do this for each group of child steps. +1. Set the `process_id` to the `id` of the new process resource +1. Set the `parent_id` to the owning `octopusdeploy_process_step.id` +1. Set the list of `children` to a list of `octopusdeploy_process_child_step.id` in the order you would like the child steps to execute +1. Note down the existing `process_id`, `step_id`'s and `action_id`'s stored in the `tfstate` file deployment process being migrated +1. Run `terraform state rm [options] 'octopusdeploy_deployment_process.'` to remove the old deployment process from state +1. Remove the old deployment process from the terraform config +1. Run `terraform import [options] octopusdeploy_process. ` to load the new process into state +1. Run `terraform import [options] octopusdeploy_process_step. ":"` for each step to load them into state +1. Run `terraform import [options] octopusdeploy_process_steps_order. ` to load the process step oder into state +1. Run `terraform import [options] octopusdeploy_process_child_step. "::"` for each child step to load them into order +1. Run `terraform import [options] octopusdeploy_process_child_steps_order. ":"` for each child step group to load them into state +1. Run `terraform plan` to see if anything is missing from state, fix accordingly +1. When satisfied run `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` | `Process_v1.0.0` | + +This escape hatch will be removed and migration will be required during the [Completion phase](#Timeline)