diff --git a/docs/guides/v1-to-v2-migration.md b/docs/guides/v1-to-v2-migration.md deleted file mode 100644 index fd39dc90..00000000 --- a/docs/guides/v1-to-v2-migration.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -page_title: "Migrate from v1 to v2" ---- - -# Migrate from v1 to v2 - -Version 2.0.0 of the Coder provider for Terraform is a major release that removes the following deprecated data sources and their properties: - -- `coder_git_auth` data source -- All owner properties from the [`coder_workspace`](../docs/data-sources/workspace.md) data source - -## Migrating `coder_git_auth` data source - -If you are using this data source, you must replace it with the [`coder_external_auth`](../docs/data-sources/external-auth.md) data source. The `coder_external_auth` data source is a more generic data source that can be used to create any external authentication provider. - -### v1.0.0 -```terraform - -data "coder_git_auth" "example" { - id = "example" -} -``` -### v2.0.0 -```terraform -data "coder_external_auth" "example" { - id = "example" -} -``` - - -## Migrating `coder_workspace` data source - -If you are using the `owner` properties of the `coder_workspace` data source, you must remove them and use the `coder_workspace_owner` data source instead. The `coder_workspace_owner` data source is a more generic data source that provide additional properties of the workspace owner. - -| `v1.0.0` | `v2.0.0` | -|-----------|----------| -| `data.coder_workspace.me.owner_id` | `data.coder_workspace_owner.me.id` | -| `data.coder_workspace.me.owner` | `data.coder_workspace_owner.me.name` | -| `data.coder_workspace.me.owner_name` | `data.coder_workspace_owner.me.full_name` | -| `data.coder_workspace.me.owner_email` | `data.coder_workspace_owner.me.email` | -| `data.coder_workspace.me.owner_groups` | `data.coder_workspace_owner.me.groups` | -| `data.coder_workspace.me.owner_oidc_access_token` | `data.coder_workspace_owner.me.oidc_access_token` | -| `data.coder_workspace.me.owner_session_token` | `data.coder_workspace_owner.me.session_token` | - -->While we do not anticipate these changes to affect existing resources, we strongly advice reviewing the plan produced by Terraform to ensure no resources are accidentally removed or altered in an undesired way. If you encounter any unexpected behavior, please report it by opening a GitHub [issue](https://github.com/coder/terraform-provider-coder/issues). diff --git a/docs/guides/version-2-upgrade.md b/docs/guides/version-2-upgrade.md new file mode 100644 index 00000000..9419d8c1 --- /dev/null +++ b/docs/guides/version-2-upgrade.md @@ -0,0 +1,102 @@ +--- +page_title: "Terraform Coder Provider Version 2 Upgrade Guide" +--- + +# Terraform Coder Provider Version 2 Upgrade Guide + +Version 2.0.0 of the Coder provider for Terraform is a major release that removes and introduces some changes that you will need to consider when upgrading. +This guide is intended to help with the process and focus only on the changes from version 1.X to version 2.0.0. + + +!> Using Version 2.0.0 of the Coder provider requires Coder Server version [`2.13.0`](https://github.com/coder/coder/releases/tag/v2.13.0) or later. + +Upgrade topics: + +- [Provider Version Configuration](#provider-version-configuration) +- [Provider Arguments](#provider-arguments) +- [Data Source: coder_git_auth --> coder_external_auth](#data-source-coder_git_auth) +- [Data Source: coder_workspace](#data-source-coder_workspace) + +## Provider Version Configuration + +-> Before upgrading to version 2.0.0, it is recommended to upgrade to the most recent 1.X version and ensure that your environment successfully runs [`terraform plan`](https://developer.hashicorp.com/terraform/cli/commands/plan) without unexpected changes or deprecation notices. + +We recommended using [version constraints](https://developer.hashicorp.com/terraform/language/providers/requirements#version-constraints) when configuring Terraform providers. + + +For example, given the previous configuration: + +```terraform +terraform { + required_providers { + coder = { + source = "coder/coder" + version = "~> 1.0.0" + } + } +} + +provider "coder" { + feature_use_managed_variables = true +} +``` + +Update to the latest 2.X version: + +```terraform +terraform { + required_providers { + coder = { + source = "coder/coder" + version = "~> 2.0.0" + } + } +} + +provider "coder" {} +``` + +## Provider Arguments + +Version 2.0.0 removes the [`feature_use_managed_variables`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs#feature_use_managed_variables-1) argument from the `provider` block. + + +## Data Source: [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) + +If you are using this data source, you must replace it with the [`coder_external_auth`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/external_auth) data source. The `coder_external_auth` data source is a more generic data source that can be used to create any external authentication provider which supports OAuth2. + +For example, given the previous configuration: + +```terraform +data "coder_git_auth" "example" { + id = "example" +} +``` + +Update to the new data source: + +```terraform +data "coder_external_auth" "example" { + id = "example" +} +``` + +## Data Source: [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) + +If you are using the `owner` properties of the `coder_workspace` data source, you must remove them and use the [`coder_workspace_owner`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner) data source instead. The `coder_workspace_owner` data source provides additional properties of the workspace owner. + +Update your Terraform configuration to use the `coder_workspace_owner` data source instead and update the following attributes: + +```terraform +data "coder_workspace_owner" "me" {} +``` + +- Remove `owner_id` attribute. Use [`data.coder_workspace_owner.me.id`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#id) instead. +- Remove `owner` attribute. Use [`data.coder_workspace_owner.me.name`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#name) instead. +- Remove `owner_name` attribute. Use [`data.coder_workspace_owner.me.full_name`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#full_name) instead. +- Remove `owner_email` attribute. Use [`data.coder_workspace_owner.me.email`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#email) instead. +- Remove `owner_groups` attribute. Use [`data.coder_workspace_owner.me.groups`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#groups) instead. +- Remove `owner_oidc_access_token` attribute. Use [`data.coder_workspace_owner.me.oidc_access_token`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#oidc_access_token) instead. +- Remove `owner_session_token` attribute. Use [`data.coder_workspace_owner.me.session_token`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#session_token) instead. + +->While we do not anticipate these changes to affect existing resources, we strongly advice reviewing the plan produced by Terraform to ensure no resources are accidentally removed or altered in an undesired way. If you encounter any unexpected behavior, please report it by opening a GitHub [issue](https://github.com/coder/terraform-provider-coder/issues). \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index ce91f4c5..918dab37 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,11 +8,11 @@ description: |- # Coder Provider -Terraform provider for managing Coder [templates](https://coder.com/docs/templates), which are the underlying infrastructure for Coder [workspaces](https://coder.com/docs/workspaces). +Terraform provider for managing Coder [templates](https://coder.com/docs/admin/templates), which are the underlying infrastructure for Coder [workspaces](https://coder.com/docs/user-guides/workspace-management). -> Requires Coder v2.13.0 or later. -!> `coder_git_auth` and owner related fields of `coder_workspace` data source have been removed. Follow the [v0 to v1migration guide](https://registry.terraform.io/providers/codercom/coder/latest/docs/guides/v1-to-v2-migration) to update your code. +!> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/codercom/coder/latest/docs/guides/version-2-upgrade) to update your code. ## Example diff --git a/go.mod b/go.mod index ec54a5e1..f4f40b67 100644 --- a/go.mod +++ b/go.mod @@ -2,7 +2,7 @@ module github.com/coder/terraform-provider-coder go 1.22 -toolchain go1.22.3 +toolchain go1.22.9 require ( github.com/docker/docker v26.1.5+incompatible diff --git a/templates/guides/v1-to-v2-migration.md.tmpl b/templates/guides/v1-to-v2-migration.md.tmpl deleted file mode 100644 index fd39dc90..00000000 --- a/templates/guides/v1-to-v2-migration.md.tmpl +++ /dev/null @@ -1,45 +0,0 @@ ---- -page_title: "Migrate from v1 to v2" ---- - -# Migrate from v1 to v2 - -Version 2.0.0 of the Coder provider for Terraform is a major release that removes the following deprecated data sources and their properties: - -- `coder_git_auth` data source -- All owner properties from the [`coder_workspace`](../docs/data-sources/workspace.md) data source - -## Migrating `coder_git_auth` data source - -If you are using this data source, you must replace it with the [`coder_external_auth`](../docs/data-sources/external-auth.md) data source. The `coder_external_auth` data source is a more generic data source that can be used to create any external authentication provider. - -### v1.0.0 -```terraform - -data "coder_git_auth" "example" { - id = "example" -} -``` -### v2.0.0 -```terraform -data "coder_external_auth" "example" { - id = "example" -} -``` - - -## Migrating `coder_workspace` data source - -If you are using the `owner` properties of the `coder_workspace` data source, you must remove them and use the `coder_workspace_owner` data source instead. The `coder_workspace_owner` data source is a more generic data source that provide additional properties of the workspace owner. - -| `v1.0.0` | `v2.0.0` | -|-----------|----------| -| `data.coder_workspace.me.owner_id` | `data.coder_workspace_owner.me.id` | -| `data.coder_workspace.me.owner` | `data.coder_workspace_owner.me.name` | -| `data.coder_workspace.me.owner_name` | `data.coder_workspace_owner.me.full_name` | -| `data.coder_workspace.me.owner_email` | `data.coder_workspace_owner.me.email` | -| `data.coder_workspace.me.owner_groups` | `data.coder_workspace_owner.me.groups` | -| `data.coder_workspace.me.owner_oidc_access_token` | `data.coder_workspace_owner.me.oidc_access_token` | -| `data.coder_workspace.me.owner_session_token` | `data.coder_workspace_owner.me.session_token` | - -->While we do not anticipate these changes to affect existing resources, we strongly advice reviewing the plan produced by Terraform to ensure no resources are accidentally removed or altered in an undesired way. If you encounter any unexpected behavior, please report it by opening a GitHub [issue](https://github.com/coder/terraform-provider-coder/issues). diff --git a/templates/guides/version-2-upgrade.md.tmpl b/templates/guides/version-2-upgrade.md.tmpl new file mode 100644 index 00000000..9419d8c1 --- /dev/null +++ b/templates/guides/version-2-upgrade.md.tmpl @@ -0,0 +1,102 @@ +--- +page_title: "Terraform Coder Provider Version 2 Upgrade Guide" +--- + +# Terraform Coder Provider Version 2 Upgrade Guide + +Version 2.0.0 of the Coder provider for Terraform is a major release that removes and introduces some changes that you will need to consider when upgrading. +This guide is intended to help with the process and focus only on the changes from version 1.X to version 2.0.0. + + +!> Using Version 2.0.0 of the Coder provider requires Coder Server version [`2.13.0`](https://github.com/coder/coder/releases/tag/v2.13.0) or later. + +Upgrade topics: + +- [Provider Version Configuration](#provider-version-configuration) +- [Provider Arguments](#provider-arguments) +- [Data Source: coder_git_auth --> coder_external_auth](#data-source-coder_git_auth) +- [Data Source: coder_workspace](#data-source-coder_workspace) + +## Provider Version Configuration + +-> Before upgrading to version 2.0.0, it is recommended to upgrade to the most recent 1.X version and ensure that your environment successfully runs [`terraform plan`](https://developer.hashicorp.com/terraform/cli/commands/plan) without unexpected changes or deprecation notices. + +We recommended using [version constraints](https://developer.hashicorp.com/terraform/language/providers/requirements#version-constraints) when configuring Terraform providers. + + +For example, given the previous configuration: + +```terraform +terraform { + required_providers { + coder = { + source = "coder/coder" + version = "~> 1.0.0" + } + } +} + +provider "coder" { + feature_use_managed_variables = true +} +``` + +Update to the latest 2.X version: + +```terraform +terraform { + required_providers { + coder = { + source = "coder/coder" + version = "~> 2.0.0" + } + } +} + +provider "coder" {} +``` + +## Provider Arguments + +Version 2.0.0 removes the [`feature_use_managed_variables`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs#feature_use_managed_variables-1) argument from the `provider` block. + + +## Data Source: [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) + +If you are using this data source, you must replace it with the [`coder_external_auth`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/external_auth) data source. The `coder_external_auth` data source is a more generic data source that can be used to create any external authentication provider which supports OAuth2. + +For example, given the previous configuration: + +```terraform +data "coder_git_auth" "example" { + id = "example" +} +``` + +Update to the new data source: + +```terraform +data "coder_external_auth" "example" { + id = "example" +} +``` + +## Data Source: [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) + +If you are using the `owner` properties of the `coder_workspace` data source, you must remove them and use the [`coder_workspace_owner`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner) data source instead. The `coder_workspace_owner` data source provides additional properties of the workspace owner. + +Update your Terraform configuration to use the `coder_workspace_owner` data source instead and update the following attributes: + +```terraform +data "coder_workspace_owner" "me" {} +``` + +- Remove `owner_id` attribute. Use [`data.coder_workspace_owner.me.id`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#id) instead. +- Remove `owner` attribute. Use [`data.coder_workspace_owner.me.name`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#name) instead. +- Remove `owner_name` attribute. Use [`data.coder_workspace_owner.me.full_name`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#full_name) instead. +- Remove `owner_email` attribute. Use [`data.coder_workspace_owner.me.email`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#email) instead. +- Remove `owner_groups` attribute. Use [`data.coder_workspace_owner.me.groups`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#groups) instead. +- Remove `owner_oidc_access_token` attribute. Use [`data.coder_workspace_owner.me.oidc_access_token`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#oidc_access_token) instead. +- Remove `owner_session_token` attribute. Use [`data.coder_workspace_owner.me.session_token`](https://registry.terraform.io/providers/coder/coder/2.0.0/docs/data-sources/workspace_owner#session_token) instead. + +->While we do not anticipate these changes to affect existing resources, we strongly advice reviewing the plan produced by Terraform to ensure no resources are accidentally removed or altered in an undesired way. If you encounter any unexpected behavior, please report it by opening a GitHub [issue](https://github.com/coder/terraform-provider-coder/issues). \ No newline at end of file diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index d9780374..7ad932f5 100644 --- a/templates/index.md.tmpl +++ b/templates/index.md.tmpl @@ -8,11 +8,11 @@ description: |- # Coder Provider -Terraform provider for managing Coder [templates](https://coder.com/docs/templates), which are the underlying infrastructure for Coder [workspaces](https://coder.com/docs/workspaces). +Terraform provider for managing Coder [templates](https://coder.com/docs/admin/templates), which are the underlying infrastructure for Coder [workspaces](https://coder.com/docs/user-guides/workspace-management). -> Requires Coder v2.13.0 or later. -!> `coder_git_auth` and owner related fields of `coder_workspace` data source have been removed. Follow the [v0 to v1migration guide](https://registry.terraform.io/providers/codercom/coder/latest/docs/guides/v1-to-v2-migration) to update your code. +!> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/codercom/coder/latest/docs/guides/version-2-upgrade) to update your code. ## Example