From 4041f0506c7ac4723d1d94995e1f4481ec7fd307 Mon Sep 17 00:00:00 2001 From: Ashlee M Boyer <43934258+ashleemboyer@users.noreply.github.com> Date: Mon, 13 Feb 2023 16:26:31 -0500 Subject: [PATCH] Migrating links to new format (#1137) --- .../sdkv2/best-practices/deprecations.mdx | 8 ++++---- .../sdkv2/best-practices/detecting-drift.mdx | 6 +++--- .../plugin/sdkv2/best-practices/index.mdx | 10 +++++----- .../sdkv2/best-practices/sensitive-state.mdx | 4 ++-- .../plugin/sdkv2/best-practices/testing.mdx | 14 ++++++------- website/docs/plugin/sdkv2/debugging.mdx | 2 +- .../guides/terraform-0.12-compatibility.mdx | 14 ++++++------- .../plugin/sdkv2/guides/v1-upgrade-guide.mdx | 2 +- .../plugin/sdkv2/guides/v2-upgrade-guide.mdx | 8 ++++---- website/docs/plugin/sdkv2/index.mdx | 18 ++++++++--------- .../plugin/sdkv2/logging/http-transport.mdx | 20 +++++++++---------- website/docs/plugin/sdkv2/logging/index.mdx | 10 +++++----- .../docs/plugin/sdkv2/resources/import.mdx | 4 ++-- website/docs/plugin/sdkv2/resources/index.mdx | 12 +++++------ .../retries-and-customizable-timeouts.mdx | 2 +- .../sdkv2/resources/state-migration.mdx | 2 +- website/docs/plugin/sdkv2/schemas/index.mdx | 4 ++-- .../plugin/sdkv2/schemas/schema-types.mdx | 8 ++++---- .../sdkv2/testing/acceptance-tests/index.mdx | 12 +++++------ .../testing/acceptance-tests/sweepers.mdx | 2 +- .../testing/acceptance-tests/testcase.mdx | 4 ++-- .../testing/acceptance-tests/teststep.mdx | 4 ++-- website/docs/plugin/sdkv2/testing/index.mdx | 6 +++--- 23 files changed, 88 insertions(+), 88 deletions(-) diff --git a/website/docs/plugin/sdkv2/best-practices/deprecations.mdx b/website/docs/plugin/sdkv2/best-practices/deprecations.mdx index b9487f0807..7f0f5db4b0 100644 --- a/website/docs/plugin/sdkv2/best-practices/deprecations.mdx +++ b/website/docs/plugin/sdkv2/best-practices/deprecations.mdx @@ -7,7 +7,7 @@ description: 'Recommendations for deprecations, removals, and renames.' Terraform is trusted for managing many facets of infrastructure across many organizations. Part of that trust is due to consistent versioning guidelines and setting expectations for various levels of upgrades. Ensuring backwards compatibility for all patch and minor releases, potentially in concert with any upcoming major changes, is recommended and supported by the Terraform development framework. This allows operators to iteratively update their Terraform configurations rather than require massive refactoring. -This guide is designed to walk through various scenarios where existing Terraform functionality requires future removal, while maintaining backwards compatibility. Further information about the versioning terminology (e.g. `MAJOR`.`MINOR`.`PATCH`) in this guide can be found in [the versioning guidelines documentation](/plugin/sdkv2/best-practices/versioning). +This guide is designed to walk through various scenarios where existing Terraform functionality requires future removal, while maintaining backwards compatibility. Further information about the versioning terminology (e.g. `MAJOR`.`MINOR`.`PATCH`) in this guide can be found in [the versioning guidelines documentation](/terraform/plugin/sdkv2/best-practices/versioning). ~> **NOTE:** Removals should only ever occur in `MAJOR` version upgrades. @@ -34,7 +34,7 @@ The recommended process for removing an attribute from a data source or resource ## Provider Attribute Rename -When renaming an attribute from one name to another, it is important to keep backwards compatibility with both existing Terraform configurations and the [Terraform state](/language/state) while operators migrate. To accomplish this, there will be some duplicated logic to support both attributes until the next `MAJOR` release. Once both attributes are appropriately handled, the process for deprecating and removing the old attribute is the same as noted in the [Provider Attribute Removal section](#provider-attribute-removal). +When renaming an attribute from one name to another, it is important to keep backwards compatibility with both existing Terraform configurations and the [Terraform state](/terraform/language/state) while operators migrate. To accomplish this, there will be some duplicated logic to support both attributes until the next `MAJOR` release. Once both attributes are appropriately handled, the process for deprecating and removing the old attribute is the same as noted in the [Provider Attribute Removal section](#provider-attribute-removal). The procedure for renaming an attribute depends on what type of attribute it is: @@ -46,7 +46,7 @@ The procedure for renaming an attribute depends on what type of attribute it is: ~> **NOTE:** If the schema definition does not contain `Optional` or `Required`, see the [Renaming a Computed Attribute section](#renaming-a-computed-attribute) instead. If the schema definition contains `Optional` instead of `Required`, see the [Renaming an Optional Attribute section](#renaming-an-optional-attribute). --> [Required attributes](/plugin/sdkv2/schemas/schema-behaviors#required) are also referred to as required "arguments" throughout the Terraform documentation. +-> [Required attributes](/terraform/plugin/sdkv2/schemas/schema-behaviors#required) are also referred to as required "arguments" throughout the Terraform documentation. In general, the procedure here does two things: @@ -261,7 +261,7 @@ func resourceExampleWidgetUpdate(d *schema.ResourceData, meta any) error { ~> **NOTE:** If the schema definition does not contain `Optional` or `Required`, see the [Renaming a Computed Attribute section](#renaming-a-computed-attribute) instead. If the schema definition contains `Required` instead of `Optional`, see the [Renaming a Required Attribute section](#renaming-a-required-attribute). --> [Optional attributes](/plugin/sdkv2/schemas/schema-behaviors#optional) are also referred to as optional "arguments" throughout the Terraform documentation. +-> [Optional attributes](/terraform/plugin/sdkv2/schemas/schema-behaviors#optional) are also referred to as optional "arguments" throughout the Terraform documentation. In general, the procedure here allows the operator to migrate the configuration to the new attribute at the same time requiring that any other references only work with the new attribute. This is to prevent a situation with Terraform showing a difference when the existing attribute is configured, but the new attribute is saved into the Terraform state. For example, in `terraform plan` output format: diff --git a/website/docs/plugin/sdkv2/best-practices/detecting-drift.mdx b/website/docs/plugin/sdkv2/best-practices/detecting-drift.mdx index 8628dc2998..0ae3334286 100644 --- a/website/docs/plugin/sdkv2/best-practices/detecting-drift.mdx +++ b/website/docs/plugin/sdkv2/best-practices/detecting-drift.mdx @@ -185,8 +185,8 @@ set for unset attributes. These situations expectedly result in drift, but can be reconciled by using Terraform's [schema functions][2], such as `DiffSuppressFunc` or `DefaultFunc`. -[0]: /plugin/sdkv2/schemas/schema-types#primitive-types +[0]: /terraform/plugin/sdkv2/schemas/schema-types#primitive-types -[1]: /plugin/sdkv2/schemas/schema-types#aggregate-types +[1]: /terraform/plugin/sdkv2/schemas/schema-types#aggregate-types -[2]: /plugin/sdkv2/schemas/schema-behaviors#function-behaviors +[2]: /terraform/plugin/sdkv2/schemas/schema-behaviors#function-behaviors diff --git a/website/docs/plugin/sdkv2/best-practices/index.mdx b/website/docs/plugin/sdkv2/best-practices/index.mdx index 63ffbf5403..7391ac675b 100644 --- a/website/docs/plugin/sdkv2/best-practices/index.mdx +++ b/website/docs/plugin/sdkv2/best-practices/index.mdx @@ -71,12 +71,12 @@ documenting those changes, a trust is formed between the two audiences. In [Versioning and Changelog][versioning] we cover some guidelines when deciding release versions and how to relay changes through documentation. -[naming]: /plugin/sdkv2/best-practices/naming +[naming]: /terraform/plugin/sdkv2/best-practices/naming -[deprecations]: /plugin/sdkv2/best-practices/deprecations +[deprecations]: /terraform/plugin/sdkv2/best-practices/deprecations -[drift]: /plugin/sdkv2/best-practices/detecting-drift +[drift]: /terraform/plugin/sdkv2/best-practices/detecting-drift -[testing-patterns]: /plugin/sdkv2/best-practices/testing +[testing-patterns]: /terraform/plugin/sdkv2/best-practices/testing -[versioning]: /plugin/sdkv2/best-practices/versioning +[versioning]: /terraform/plugin/sdkv2/best-practices/versioning diff --git a/website/docs/plugin/sdkv2/best-practices/sensitive-state.mdx b/website/docs/plugin/sdkv2/best-practices/sensitive-state.mdx index 4d052ce4e5..b1af62f6a9 100644 --- a/website/docs/plugin/sdkv2/best-practices/sensitive-state.mdx +++ b/website/docs/plugin/sdkv2/best-practices/sensitive-state.mdx @@ -7,7 +7,7 @@ description: Recommendations for handling sensitive information in state. Many organizations use Terraform to manage their entire infrastructure, and it's inevitable that [sensitive information will find its way into -Terraform](/language/state/sensitive-data) in these circumstances. There are a +Terraform](/terraform/language/state/sensitive-data) in these circumstances. There are a couple of recommended approaches for managing sensitive state in Terraform. ## Using the `Sensitive` Flag @@ -32,7 +32,7 @@ HashiCorp-supported providers over time. This strategy was tailored to a time when Terraform's state had to be stored in cleartext on any machine running `terraform apply`, and was meant to provide a bit of security in that scenario. With the introduction and use of -[remote backends](/language/settings/backends/configuration) +[remote backends](/terraform/language/settings/backends/configuration) and especially the availability of [Terraform Cloud](https://app.terraform.io/), there are now a variety of backends that will encrypt state at rest and will not store the state in diff --git a/website/docs/plugin/sdkv2/best-practices/testing.mdx b/website/docs/plugin/sdkv2/best-practices/testing.mdx index 3b6908b886..1cf644d2da 100644 --- a/website/docs/plugin/sdkv2/best-practices/testing.mdx +++ b/website/docs/plugin/sdkv2/best-practices/testing.mdx @@ -369,20 +369,20 @@ correctly across the most common use cases and everyday operations users will have using their plugins, and ensure that Terraform remains a world-class tool for safely managing infrastructure. -[1]: /plugin/sdkv2/testing +[1]: /terraform/plugin/sdkv2/testing -[2]: /plugin/sdkv2/testing/acceptance-tests/testcase +[2]: /terraform/plugin/sdkv2/testing/acceptance-tests/testcase -[3]: /plugin/sdkv2/testing/acceptance-tests/testcase#precheck +[3]: /terraform/plugin/sdkv2/testing/acceptance-tests/testcase#precheck -[4]: /plugin/sdkv2/testing/acceptance-tests/testcase#checkdestroy +[4]: /terraform/plugin/sdkv2/testing/acceptance-tests/testcase#checkdestroy -[5]: /plugin/sdkv2/testing/acceptance-tests/teststep +[5]: /terraform/plugin/sdkv2/testing/acceptance-tests/teststep [6]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#TestStep.ExpectNonEmptyPlan [7]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#TestStep.ExpectError -[8]: /plugin/sdkv2/testing/acceptance-tests/teststep#check-functions +[8]: /terraform/plugin/sdkv2/testing/acceptance-tests/teststep#check-functions -[9]: /plugin/sdkv2/testing/acceptance-tests/teststep#builtin-check-functions +[9]: /terraform/plugin/sdkv2/testing/acceptance-tests/teststep#builtin-check-functions diff --git a/website/docs/plugin/sdkv2/debugging.mdx b/website/docs/plugin/sdkv2/debugging.mdx index 0a39e7ea6a..22341e0df4 100644 --- a/website/docs/plugin/sdkv2/debugging.mdx +++ b/website/docs/plugin/sdkv2/debugging.mdx @@ -5,7 +5,7 @@ description: How to implement debugger support in SDKv2 Terraform providers. # Debugging SDKv2 Providers -This page contains implementation details for inspecting runtime information of a Terraform provider developed with SDKv2 via a debugger tool. Review the top level [Debugging](/plugin/debugging) page for information pertaining to the overall Terraform provider debugging process and other inspection options, such as log-based debugging. +This page contains implementation details for inspecting runtime information of a Terraform provider developed with SDKv2 via a debugger tool. Review the top level [Debugging](/terraform/plugin/debugging) page for information pertaining to the overall Terraform provider debugging process and other inspection options, such as log-based debugging. ## Code Implementation diff --git a/website/docs/plugin/sdkv2/guides/terraform-0.12-compatibility.mdx b/website/docs/plugin/sdkv2/guides/terraform-0.12-compatibility.mdx index 159a1dc5ad..442ffdb76a 100644 --- a/website/docs/plugin/sdkv2/guides/terraform-0.12-compatibility.mdx +++ b/website/docs/plugin/sdkv2/guides/terraform-0.12-compatibility.mdx @@ -16,7 +16,7 @@ The _provider protocol_ is the physical mechanism by which Terraform Core launches a provider executable and directs it to take actions. Provider developers do not generally interact with the protocol directly, but rather implement against the Terraform SDK (as described elsewhere in -[the _Extend_ section](/plugin)) which in turn implements the provider side of +[the _Extend_ section](/terraform/plugin)) which in turn implements the provider side of the protocol itself. As a result, most of the work to support Terraform 0.12 comes just from @@ -43,7 +43,7 @@ to the latest Terraform SDK involves upgrading all of the dependencies on Go packages with the prefix `github.com/hashicorp/terraform/` to a version with support for the new provider protocol. -~> **NOTE:** The SDK is now its own Go module. Existing providers should upgrade to at least v0.12.7 before [switching to the standalone SDK](/plugin/sdkv2/guides/v1-upgrade-guide). This is to isolate issues between Terraform SDK v0.11 and v0.12, and the standalone SDK. New providers should vendor the standalone SDK from the start. +~> **NOTE:** The SDK is now its own Go module. Existing providers should upgrade to at least v0.12.7 before [switching to the standalone SDK](/terraform/plugin/sdkv2/guides/v1-upgrade-guide). This is to isolate issues between Terraform SDK v0.11 and v0.12, and the standalone SDK. New providers should vendor the standalone SDK from the start. Terraform Core is now using [Go Modules](https://github.com/golang/go/wiki/Modules) for dependency @@ -76,7 +76,7 @@ if you see unexpected new test failures after upgrading. ## Configuration Syntax Changes If your provider follows -[the usual test patterns](/plugin/sdkv2/testing/acceptance-tests/testcase) +[the usual test patterns](/terraform/plugin/sdkv2/testing/acceptance-tests/testcase) then there will be configuration snippets in your tests that will, after upgrading the SDK, be parsed using the new configuration language engine from Terraform 0.12. Although the new syntax is broadly compatible, there are some @@ -87,11 +87,11 @@ If you see new configuration-related errors in your tests after upgrading, you may need to update the configuration snippets in similar ways to how an end-user might update their own configurations for compatibility. There are lots of details on the common situations in -[the v0.12 upgrade guide](/language/v1.1.x/upgrade-guides/0-12). +[the v0.12 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-12). If you see an error you're not sure how to resolve, it may help to copy the configuration snippet into a separate `.tf` file in a new directory and use -[the `terraform 0.12upgrade` command](/cli/commands/0.12upgrade) +[the `terraform 0.12upgrade` command](/terraform/cli/commands/0.12upgrade) to see what changes Terraform itself proposes. One particular situation that we've seen crop up a lot in provider upgrades @@ -212,7 +212,7 @@ that `null_resource.example.triggers["foo"]` was interpolated into, rather than the resource that caused the problem: `null_resource.example`. If you see either of these errors, the remedy is the same: implement -[`CustomizeDiff`](/plugin/sdkv2/resources/customizing-differences) +[`CustomizeDiff`](/terraform/plugin/sdkv2/resources/customizing-differences) for the resource type that is causing the problem, and write logic to more accurately predict the outcome of any changes to `Computed` attributes. If you can predict the exact new value then that is preferable, but if you @@ -252,7 +252,7 @@ Terraform v0.12 does not support using `Computed` with a collection of sub-resources, but to avoid breaking existing uses of that mechanism for the reason described above, we introduced a compromise which you can read more about from the end-user perspective in -[Attributes as Blocks](/language/attr-as-blocks). +[Attributes as Blocks](/terraform/language/attr-as-blocks). If you have an existing `Computed` attribute that has `Elem: *schema.Resource` and which expects to treat explicit assignment of an empty list differently diff --git a/website/docs/plugin/sdkv2/guides/v1-upgrade-guide.mdx b/website/docs/plugin/sdkv2/guides/v1-upgrade-guide.mdx index e1fc9e483b..940c3cdb01 100644 --- a/website/docs/plugin/sdkv2/guides/v1-upgrade-guide.mdx +++ b/website/docs/plugin/sdkv2/guides/v1-upgrade-guide.mdx @@ -44,7 +44,7 @@ If this command succeeds, proceed to Step 2. Otherwise, the tool will output the steps you need to take to ensure the provider can be migrated. Please see for more information about the eligibility checks, and see the [Deprecations section](#deprecations) below for what to do if you are using deprecated packages or identifiers. -Projects that are on an old version of the legacy Terraform plugin SDK, particularly < v0.12, should first [upgrade to v0.12](/plugin/sdkv2/guides/terraform-0.12-compatibility). +Projects that are on an old version of the legacy Terraform plugin SDK, particularly < v0.12, should first [upgrade to v0.12](/terraform/plugin/sdkv2/guides/terraform-0.12-compatibility). #### Step 2: Migrate diff --git a/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx b/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx index 115499f327..28a41d323e 100644 --- a/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx +++ b/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx @@ -249,7 +249,7 @@ Third, the provider must be started by delve, and Terraform must be told how to connect to it. Providers using `plugin.Debug` will output instructions on how to tell Terraform how to connect. --> **Note**: You can find more details on the [Debugging Providers page](/plugin/sdkv2/debugging). +-> **Note**: You can find more details on the [Debugging Providers page](/terraform/plugin/sdkv2/debugging). ## Support for Provider Metadata @@ -616,7 +616,7 @@ help us understand your use case so we can recommend a path forward. The `Removed` property of `helper/schema.Schema`, used to provide a friendly error message when a field has been removed after its [deprecation -period](/plugin/sdkv2/best-practices/deprecations), +period](/terraform/plugin/sdkv2/best-practices/deprecations), behaved unexpectedly in tests and other situations. It has been removed. The recommendation is now to delete the field after the deprecation period, and let Terraform’s built-in error messaging indicate its removal. @@ -624,9 +624,9 @@ Terraform’s built-in error messaging indicate its removal. ## Removal of `helper/encryption` Package The `helper/encryption` package supports an [anti-pattern that is now -discouraged](/plugin/sdkv2/best-practices/sensitive-state#don-39-t-encrypt-state), +discouraged](/terraform/plugin/sdkv2/best-practices/sensitive-state#don-39-t-encrypt-state), so it has been removed. Providers relying on it should see the -[documentation](/plugin/sdkv2/best-practices/sensitive-state) +[documentation](/terraform/plugin/sdkv2/best-practices/sensitive-state) on that pattern and select an alternative approach. ## Removal of Discouraged Variables, Functions, Types, and Interfaces diff --git a/website/docs/plugin/sdkv2/index.mdx b/website/docs/plugin/sdkv2/index.mdx index dd305b0eb0..8947e80b06 100644 --- a/website/docs/plugin/sdkv2/index.mdx +++ b/website/docs/plugin/sdkv2/index.mdx @@ -5,23 +5,23 @@ description: Maintain plugins built on the legacy SDK. # Terraform Plugin SDKv2 -Terraform Plugin SDKv2 is a way to maintain Terraform Plugins on [protocol version 5](/plugin/terraform-plugin-protocol#protocol-version-5). +Terraform Plugin SDKv2 is a way to maintain Terraform Plugins on [protocol version 5](/terraform/plugin/terraform-plugin-protocol#protocol-version-5). -We recommend using the [framework](/plugin/framework) to develop new provider functionality because it offers significant advantages as compared to the SDKv2. We also recommend migrating existing providers to the framework when possible. Refer to [Plugin Framework Benefits](/plugin/framework-benefits) for higher level details about how the framework makes provider development easier and [Plugin Framework Features](/plugin/framework/migrating/benefits) for a detailed functionality comparison between the SDKv2 and the framework. +We recommend using the [framework](/terraform/plugin/framework) to develop new provider functionality because it offers significant advantages as compared to the SDKv2. We also recommend migrating existing providers to the framework when possible. Refer to [Plugin Framework Benefits](/terraform/plugin/framework-benefits) for higher level details about how the framework makes provider development easier and [Plugin Framework Features](/terraform/plugin/framework/migrating/benefits) for a detailed functionality comparison between the SDKv2 and the framework. ## Maintain Existing Providers -- Try the [Call APIs with Custom Providers](https://developer.hashicorp.com/terraform/tutorials/providers) tutorials. +- Try the [Call APIs with Custom Providers](/terraform/tutorials/providers) tutorials. - Clone the [terraform-provider-scaffolding](https://github.com/hashicorp/terraform-provider-scaffolding) template repository on GitHub. -- Review the SDKv2 documentation for key concepts such as [Schemas](/plugin/sdkv2/schemas) and [Resources](/plugin/sdkv2/resources). +- Review the SDKv2 documentation for key concepts such as [Schemas](/terraform/plugin/sdkv2/schemas) and [Resources](/terraform/plugin/sdkv2/resources). ## Debug and Test -- Learn how to [debug your provider](/plugin/sdkv2/debugging) using either logging calls or a debugging tool. -- Write [acceptance and unit tests](/plugin/sdkv2/testing) for your provider. +- Learn how to [debug your provider](/terraform/plugin/sdkv2/debugging) using either logging calls or a debugging tool. +- Write [acceptance and unit tests](/terraform/plugin/sdkv2/testing) for your provider. ## Migrate, Combine, or Translate -- Use the [framework migration guide](/plugin/framework/migrating) to migrate existing providers from SDKv2 to the framework. You can use `terraform-plugin-mux` to migrate individual resources and data sources slowly over time. -- [Combine your provider](/plugin/mux/combining-protocol-version-5-providers) with other [protocol version 5](/plugin/terraform-plugin-protocol#protocol-version-5) providers. -- [Translate your provider](/plugin/mux/translating-protocol-version-5-to-6) into a [protocol version 6](/plugin/terraform-plugin-protocol#protocol-version-6) provider to require Terraform 1.0 and later or to combine with a framework provider and use protocol version 6 exclusive functionality such as nested attributes. +- Use the [framework migration guide](/terraform/plugin/framework/migrating) to migrate existing providers from SDKv2 to the framework. You can use `terraform-plugin-mux` to migrate individual resources and data sources slowly over time. +- [Combine your provider](/terraform/plugin/mux/combining-protocol-version-5-providers) with other [protocol version 5](/terraform/plugin/terraform-plugin-protocol#protocol-version-5) providers. +- [Translate your provider](/terraform/plugin/mux/translating-protocol-version-5-to-6) into a [protocol version 6](/terraform/plugin/terraform-plugin-protocol#protocol-version-6) provider to require Terraform 1.0 and later or to combine with a framework provider and use protocol version 6 exclusive functionality such as nested attributes. diff --git a/website/docs/plugin/sdkv2/logging/http-transport.mdx b/website/docs/plugin/sdkv2/logging/http-transport.mdx index efedff58f1..4302b6d640 100644 --- a/website/docs/plugin/sdkv2/logging/http-transport.mdx +++ b/website/docs/plugin/sdkv2/logging/http-transport.mdx @@ -10,16 +10,16 @@ Terraform's public interface has included `helper/logging` [`NewTransport()`](ht We do not recommend using this original helper because it is designed to log the entirety of each request and response. This includes any sensitive content that may be present in the message header or body, presenting security concerns. -Instead, we recommend using the [terraform-plugin-log](/plugin/log) library to produce logs for your provider. This library does not present the same security concerns and provides [log filtering](/plugin/log/filtering) functionality. This page explains how to set up the new `RoundTripper()` helper to log HTTP Transactions with `terraform-plugin-log`. +Instead, we recommend using the [terraform-plugin-log](/terraform/plugin/log) library to produce logs for your provider. This library does not present the same security concerns and provides [log filtering](/terraform/plugin/log/filtering) functionality. This page explains how to set up the new `RoundTripper()` helper to log HTTP Transactions with `terraform-plugin-log`. # Setting Up Logging for HTTP Transactions -The recommended logging helper for SDK is built on top of [terraform-plugin-log](/plugin/log). This lets you leverage the features from our structured logging framework without having to write an entire implementation of `http.RoundTripper`. +The recommended logging helper for SDK is built on top of [terraform-plugin-log](/terraform/plugin/log). This lets you leverage the features from our structured logging framework without having to write an entire implementation of `http.RoundTripper`. -There are two functions inside `helper/logging` that target a specific logging setup for your provider. Refer to [“Writing Log Output”](/plugin/log/writing) for details. +There are two functions inside `helper/logging` that target a specific logging setup for your provider. Refer to [“Writing Log Output”](/terraform/plugin/log/writing) for details. * `NewLoggingHTTPTransport(transport http.RoundTripper)`: Use this method when you want logging against the `tflog` Provider root logger. -* `NewSubsystemLoggingHTTPTransport(subsystem string, transport http.RoundTripper)`: Use this method when you want logging against a `tflog` Provider [Subsystem logger](/plugin/log/writing#subsystems). The `subsystem` string you use with `NewSubsystemLoggingHTTPTransport()` must match the [pre-created subsystem logger name](/plugin/log/writing#create-subsystems). +* `NewSubsystemLoggingHTTPTransport(subsystem string, transport http.RoundTripper)`: Use this method when you want logging against a `tflog` Provider [Subsystem logger](/terraform/plugin/log/writing#subsystems). The `subsystem` string you use with `NewSubsystemLoggingHTTPTransport()` must match the [pre-created subsystem logger name](/terraform/plugin/log/writing#create-subsystems). To set up HTTP transport, you must create the HTTP Client to use the new transport and then add logging configuration to the HTTP request context. @@ -75,7 +75,7 @@ The logging transport produces two log entries for each HTTP transaction: one fo ### Request Example -The following example shows a log generated from an HTTP Request to [https://terraform.io](https://terraform.io). +The following example shows a log generated from an HTTP Request to [https://terraform.io](https://terraform.io/). ```text 2022-07-26T18:54:08.880+0100 [DEBUG] provider: Sending HTTP Request: Accept-Encoding=gzip Content-Length=0 \ @@ -84,7 +84,7 @@ The following example shows a log generated from an HTTP Request to [https://ter tf_http_req_uri=/ tf_http_req_version=HTTP/1.1 tf_http_trans_id=7e80e48d-8f32-f527-1412-52a8c84359e7 ``` -The following example shows the same logs after you enable [logging in JSON format](/internals/debugging). +The following example shows the same logs after you enable [logging in JSON format](/terraform/internals/debugging). ```json { @@ -109,7 +109,7 @@ The following example shows the same logs after you enable [logging in JSON form ### Response Example -The following example shows logs from a [https://terraform.io](https://terraform.io) HTTP response. +The following example shows logs from a [https://terraform.io](https://terraform.io/) HTTP response. ```text 2022-07-26T18:54:10.734+0100 [DEBUG] provider: Received HTTP Response: Age=9 \ @@ -157,7 +157,7 @@ the following example shows the same logs in JSON format. ### Log Information -Each log contains the following information, which is represented as [fields](/plugin/log/writing#fields) in the JSON format. +Each log contains the following information, which is represented as [fields](/terraform/plugin/log/writing#fields) in the JSON format. | Log field name | Description | Possible values | Applies to | |---------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|:------------------:| @@ -175,7 +175,7 @@ Each log contains the following information, which is represented as [fields](/p ## Filtering Sensitive Data -To [filter logs](/plugin/log/filtering), you must configure the `context.Context` before before it is added to the `http.Request`. +To [filter logs](/terraform/plugin/log/filtering), you must configure the `context.Context` before before it is added to the `http.Request`. The following example masks all the header values of HTTP Requests containing an `Authorization` and `Proxy-Authorization` credentials. @@ -198,6 +198,6 @@ defer res.Body.Close() # Links -* [Plugin Development - Logging](/plugin/log) - Learn more about the logging framework +* [Plugin Development - Logging](/terraform/plugin/log) - Learn more about the logging framework * [terraform-plugin-log - tflog](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-log/tflog) - Read the Golang documentation for the logging framework * Read the Golang documentation for [`NewLoggingHTTPTransport()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/logging#NewLoggingHTTPTransport) and [`NewSubsystemLoggingHTTPTransport()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/logging#NewSubsystemLoggingHTTPTransport) diff --git a/website/docs/plugin/sdkv2/logging/index.mdx b/website/docs/plugin/sdkv2/logging/index.mdx index dc7314fdd6..9cfc333c6f 100644 --- a/website/docs/plugin/sdkv2/logging/index.mdx +++ b/website/docs/plugin/sdkv2/logging/index.mdx @@ -6,20 +6,20 @@ description: |- # Logging -Terraform Plugin SDKv2 integrates with the structured logging framework [terraform-plugin-log](/plugin/log). High-quality logs are critical to quickly [debugging your provider](/plugin/debugging). +Terraform Plugin SDKv2 integrates with the structured logging framework [terraform-plugin-log](/terraform/plugin/log). High-quality logs are critical to quickly [debugging your provider](/terraform/plugin/debugging). ## Managing Log Output -Learn how to use [environment variables and other methods](/plugin/log/managing) to enable and filter logs. +Learn how to use [environment variables and other methods](/terraform/plugin/log/managing) to enable and filter logs. ## Writing Log Output -Learn how to [implement code in provider logic](/plugin/log/writing) to output logs. +Learn how to [implement code in provider logic](/terraform/plugin/log/writing) to output logs. ## Filtering Log Output -Learn how to [implement code in provider logic](/plugin/log/filtering) to omit logs or mask specific log messages and structured log fields. +Learn how to [implement code in provider logic](/terraform/plugin/log/filtering) to omit logs or mask specific log messages and structured log fields. ## Log HTTP Transactions -Learn how to [set up the Logging HTTP Transport](./logging/http-transport) to log HTTP Transactions with the [structured logging framework](/plugin/log). +Learn how to [set up the Logging HTTP Transport](/terraform/plugin/sdkv2/logging/http-transport) to log HTTP Transactions with the [structured logging framework](/terraform/plugin/log). diff --git a/website/docs/plugin/sdkv2/resources/import.mdx b/website/docs/plugin/sdkv2/resources/import.mdx index f0c640ab72..e10120bd5d 100644 --- a/website/docs/plugin/sdkv2/resources/import.mdx +++ b/website/docs/plugin/sdkv2/resources/import.mdx @@ -19,7 +19,7 @@ $ terraform import example_thing.foo abc123 Implementing import support requires three changes: an `Importer` `State` function in the resource code, a `TestStep` with `ImportState: true` in the acceptance tests, and documentation of the import ID format. -> **Hands-on:** Try the [Implement Import](https://learn.hashicorp.com/tutorials/terraform/provider-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. In this tutorial, you can implement the import functionality on an example Terraform provider. +> **Hands-on:** Try the [Implement Import](/terraform/tutorials/providers/provider-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. In this tutorial, you can implement the import functionality on an example Terraform provider. ### Resource Code Implementation @@ -80,7 +80,7 @@ The items below are coding/testing styles that should generally be followed when - The `TestStep` including `ImportState` testing should not be performed solely in a separate acceptance test. This duplicates testing infrastructure/time and does not check that all resource configurations import into Terraform properly. - The `TestStep` including `ImportState` should be included in all applicable resource acceptance tests (except those that delete the resource in question, e.g. `_disappears` tests) -- Import implementations should not change existing `Create` function `d.SetId()` calls. [Versioning best practices for Terraform Provider development](/plugin/sdkv2/best-practices/versioning#example-major-number-increments) notes that changing the resource ID is considered a breaking change for a major version upgrade as it makes the `id` attribute ambiguous between provider versions. +- Import implementations should not change existing `Create` function `d.SetId()` calls. [Versioning best practices for Terraform Provider development](/terraform/plugin/sdkv2/best-practices/versioning#example-major-number-increments) notes that changing the resource ID is considered a breaking change for a major version upgrade as it makes the `id` attribute ambiguous between provider versions. - `ImportStateVerifyIgnore` should only be used where its not possible to `d.Set()` the attribute in the `Read` function (preferable) or `Importer` `State` function. ### Importer State Function diff --git a/website/docs/plugin/sdkv2/resources/index.mdx b/website/docs/plugin/sdkv2/resources/index.mdx index f066fb571e..d753b92213 100644 --- a/website/docs/plugin/sdkv2/resources/index.mdx +++ b/website/docs/plugin/sdkv2/resources/index.mdx @@ -7,22 +7,22 @@ description: >- # Resources -A key component to Terraform Provider development is defining the creation, read, update, and deletion functionality of a resource to map those API operations into the Terraform lifecycle. While the [Call APIs with Terraform Providers tutorial](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) and [Schemas documentation](/plugin/sdkv2/schemas) cover the basic aspects of developing Terraform resources, this section covers more advanced features of resource development. +A key component to Terraform Provider development is defining the creation, read, update, and deletion functionality of a resource to map those API operations into the Terraform lifecycle. While the [Call APIs with Terraform Providers tutorial](/terraform/tutorials/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) and [Schemas documentation](/terraform/plugin/sdkv2/schemas) cover the basic aspects of developing Terraform resources, this section covers more advanced features of resource development. ## Import -Many operators migrating to Terraform will have previously existing infrastructure they want to bring under the management of Terraform. Terraform allows resources to implement [Import Support](/plugin/sdkv2/resources/import) to begin managing those existing infrastructure components. +Many operators migrating to Terraform will have previously existing infrastructure they want to bring under the management of Terraform. Terraform allows resources to implement [Import Support](/terraform/plugin/sdkv2/resources/import) to begin managing those existing infrastructure components. ## Retries and Customizable Timeouts -The reality of cloud infrastructure is that it typically takes time to perform operations such as booting operating systems, discovering services, and replicating state across network edges. Terraform implements functionality to retry API requests or specifically declare state change criteria, while allowing customizable timeouts for operators. More information can be found in the [Retries and Customizable Timeouts section](/plugin/sdkv2/resources/retries-and-customizable-timeouts). +The reality of cloud infrastructure is that it typically takes time to perform operations such as booting operating systems, discovering services, and replicating state across network edges. Terraform implements functionality to retry API requests or specifically declare state change criteria, while allowing customizable timeouts for operators. More information can be found in the [Retries and Customizable Timeouts section](/terraform/plugin/sdkv2/resources/retries-and-customizable-timeouts). ## Customizing Differences -Terraform tracks the state of provisioned resources in its state file, and compares the user-passed configuration against that state. When Terraform detects a discrepancy, it presents the user with the differences between the configuration and the state. Sometimes these scenarios require special handling, which is where [Customizing Differences](/plugin/sdkv2/resources/customizing-differences) can help. +Terraform tracks the state of provisioned resources in its state file, and compares the user-passed configuration against that state. When Terraform detects a discrepancy, it presents the user with the differences between the configuration and the state. Sometimes these scenarios require special handling, which is where [Customizing Differences](/terraform/plugin/sdkv2/resources/customizing-differences) can help. ## State Migrations -Resources define the data types and API interactions required to create, update, and destroy infrastructure with a cloud vendor, while the [Terraform state](/language/state) stores mapping and metadata information for those remote objects. +Resources define the data types and API interactions required to create, update, and destroy infrastructure with a cloud vendor, while the [Terraform state](/terraform/language/state) stores mapping and metadata information for those remote objects. -When resource implementations change (due to bug fixes, improvements, or changes to the backend APIs Terraform interacts with), they can sometimes become incompatible with existing state. When this happens, a migration is needed for resources provisioned in the wild with old schema configurations. Terraform resources support migrating state values in these scenarios via [State Migration](/plugin/sdkv2/resources/state-migration). +When resource implementations change (due to bug fixes, improvements, or changes to the backend APIs Terraform interacts with), they can sometimes become incompatible with existing state. When this happens, a migration is needed for resources provisioned in the wild with old schema configurations. Terraform resources support migrating state values in these scenarios via [State Migration](/terraform/plugin/sdkv2/resources/state-migration). diff --git a/website/docs/plugin/sdkv2/resources/retries-and-customizable-timeouts.mdx b/website/docs/plugin/sdkv2/resources/retries-and-customizable-timeouts.mdx index 607a50f2cc..fa411df00a 100644 --- a/website/docs/plugin/sdkv2/resources/retries-and-customizable-timeouts.mdx +++ b/website/docs/plugin/sdkv2/resources/retries-and-customizable-timeouts.mdx @@ -36,7 +36,7 @@ func resourceExampleInstance() *schema.Resource { } ``` -In the above example we see the usage of the timeouts in the schema being configured for what is deemed the appropriate amount of time for the `Create` function. `Read`, `Update`, and `Delete` are also configurable as well as a `Default`. These configured timeouts can be fetched in the CRUD function logic using the [`(*schema.ResourceData).Timeout()` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema#ResourceData.Timeout), such as `d.Timeout(schema.TimeoutCreate)`. Practitioners can override these timeout values with [resource timeouts configuration](/language/resources/syntax#operation-timeouts), such as: +In the above example we see the usage of the timeouts in the schema being configured for what is deemed the appropriate amount of time for the `Create` function. `Read`, `Update`, and `Delete` are also configurable as well as a `Default`. These configured timeouts can be fetched in the CRUD function logic using the [`(*schema.ResourceData).Timeout()` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema#ResourceData.Timeout), such as `d.Timeout(schema.TimeoutCreate)`. Practitioners can override these timeout values with [resource timeouts configuration](/terraform/language/resources/syntax#operation-timeouts), such as: ```terraform resource "example_thing" "example" { diff --git a/website/docs/plugin/sdkv2/resources/state-migration.mdx b/website/docs/plugin/sdkv2/resources/state-migration.mdx index 8ead2af768..1ab7943bd6 100644 --- a/website/docs/plugin/sdkv2/resources/state-migration.mdx +++ b/website/docs/plugin/sdkv2/resources/state-migration.mdx @@ -5,7 +5,7 @@ description: Migrating state values within resources. # Resources - State Migration -Resources define the data types and API interactions required to create, update, and destroy infrastructure with a cloud vendor while the [Terraform state](/language/state) stores mapping and metadata information for those remote objects. There are several reasons why a resource implementation needs to change: backend APIs Terraform interacts with will change overtime, or the current implementation might be incorrect or unmaintainable. Some of these changes may not be backward compatible and a migration is needed for resources provisioned in the wild with old schema configurations. +Resources define the data types and API interactions required to create, update, and destroy infrastructure with a cloud vendor while the [Terraform state](/terraform/language/state) stores mapping and metadata information for those remote objects. There are several reasons why a resource implementation needs to change: backend APIs Terraform interacts with will change overtime, or the current implementation might be incorrect or unmaintainable. Some of these changes may not be backward compatible and a migration is needed for resources provisioned in the wild with old schema configurations. The mechanism that is used for state migrations changed between v0.11 and v0.12 of the SDK bundled with Terraform core. Be sure to choose the method that matches your Terraform dependency. diff --git a/website/docs/plugin/sdkv2/schemas/index.mdx b/website/docs/plugin/sdkv2/schemas/index.mdx index 800ecde153..6a00e371b2 100644 --- a/website/docs/plugin/sdkv2/schemas/index.mdx +++ b/website/docs/plugin/sdkv2/schemas/index.mdx @@ -57,7 +57,7 @@ Schema items must be defined using one of the builtin types, such as `TypeString`, `TypeBool`, `TypeInt`, et. al. The type defines what is considered valid input for a given schema item in a users configuration. -See [Schema Types](/plugin/sdkv2/schemas/schema-types) for more +See [Schema Types](/terraform/plugin/sdkv2/schemas/schema-types) for more information on the types available to schemas. ## Schema Behaviors @@ -67,5 +67,5 @@ behaviors represented by their API. Some items are **Required**, others **Optional**, while others may be **Computed** such that they are useful to be tracked in state, but cannot be configured by users. -See [Schema Behaviors](/plugin/sdkv2/schemas/schema-behaviors) for more +See [Schema Behaviors](/terraform/plugin/sdkv2/schemas/schema-behaviors) for more information on the properties a schema can have. diff --git a/website/docs/plugin/sdkv2/schemas/schema-types.mdx b/website/docs/plugin/sdkv2/schemas/schema-types.mdx index ac2d56ce77..d6a17d6c36 100644 --- a/website/docs/plugin/sdkv2/schemas/schema-types.mdx +++ b/website/docs/plugin/sdkv2/schemas/schema-types.mdx @@ -39,14 +39,14 @@ func resourceExampleResource() *schema.Resource { The Schema attribute `Type` defines what kind of values users can provide in their configuration for this element. Here we define the available schema types -supported. See [Schema Behaviors](/plugin/sdkv2/schemas/schema-behaviors) +supported. See [Schema Behaviors](/terraform/plugin/sdkv2/schemas/schema-behaviors) for more information on configuring element behaviors. ## Types The schema attribute `Type` determines what data is valid in configuring the element, as well as the type of data returned when used in an -[expression](/language/expressions). Schemas attributes must +[expression](/terraform/language/expressions). Schemas attributes must be one of the types defined below, and can be loosely categorized as either **Primitive** or **Aggregate** types: @@ -54,7 +54,7 @@ be one of the types defined below, and can be loosely categorized as either Primitive types are simple values such as integers, booleans, and strings. Primitives are stored in the -[state file](/language/state) as `"key": "value"` +[state file](/terraform/language/state) as `"key": "value"` string pairs, where both `key` and `value` are string representations. **Aggregate types** @@ -405,5 +405,5 @@ of the attributes of the set. ## Next Steps -Checkout [Schema Behaviors](/plugin/sdkv2/schemas/schema-behaviors) to learn +Checkout [Schema Behaviors](/terraform/plugin/sdkv2/schemas/schema-behaviors) to learn how to customize each schema elements behavior. diff --git a/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx b/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx index aadf570acc..77b6b38b27 100644 --- a/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx +++ b/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx @@ -239,8 +239,8 @@ A number of environment variables are available to control aspects of acceptance | Environment Variable Name | Default | Description | |---------------------------|---------|-------------| | `TF_ACC` | N/A | Set to any value to enable acceptance testing via the [`helper/resource.ParallelTest()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#ParallelTest) and [`helper/resource.Test()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#Test) functions. | -| `TF_ACC_PROVIDER_HOST`: | `registry.terraform.io` | Set the hostname of the provider under test, such as `example.com` in the `example.com/myorg/myprovider` provider source address. This is only required if any [`TestStep.Config`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#TestStep.Config) specifies a provider source address, such as in the [`terraform` configuration block `required_providers` attribute](/language/settings#specifying-provider-requirements). | -| `TF_ACC_PROVIDER_NAMESPACE` | `hashicorp` | Set the namespace of the provider under test, such as `myorg` in the `registry.terraform.io/myorg/myprovider` provider source address. This is only required if any [`TestStep.Config`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#TestStep.Config) specifies a provider source address, such as in the [`terraform` configuration block `required_providers` attribute](/language/settings#specifying-provider-requirements). | +| `TF_ACC_PROVIDER_HOST`: | `registry.terraform.io` | Set the hostname of the provider under test, such as `example.com` in the `example.com/myorg/myprovider` provider source address. This is only required if any [`TestStep.Config`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#TestStep.Config) specifies a provider source address, such as in the [`terraform` configuration block `required_providers` attribute](/terraform/language/settings#specifying-provider-requirements). | +| `TF_ACC_PROVIDER_NAMESPACE` | `hashicorp` | Set the namespace of the provider under test, such as `myorg` in the `registry.terraform.io/myorg/myprovider` provider source address. This is only required if any [`TestStep.Config`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#TestStep.Config) specifies a provider source address, such as in the [`terraform` configuration block `required_providers` attribute](/terraform/language/settings#specifying-provider-requirements). | | `TF_ACC_STATE_LINEAGE` | N/A | Set to `1` to enable state lineage debug logs, which are normally suppressed during acceptance testing. | | `TF_ACC_TEMP_DIR` | Operating system specific via [`os.TempDir()`](https://pkg.go.dev/os#TempDir) | Set a temporary directory used for testing files and installing Terraform CLI, if installation is required. | | `TF_ACC_TERRAFORM_PATH` | N/A | Set the path to a Terraform CLI binary on the local filesystem to be used during testing. It must be executable. If not found and `TF_ACC_TERRAFORM_VERSION` is not set, an error is returned. | @@ -248,14 +248,14 @@ A number of environment variables are available to control aspects of acceptance ### Logging Environment Variables -A number of environment variables available to control logging aspects during acceptance test execution. Some of these modify or replace the production behaviors defined in [managing provider log output](/plugin/log/managing) and [debugging Terraform](/internals/debugging). +A number of environment variables available to control logging aspects during acceptance test execution. Some of these modify or replace the production behaviors defined in [managing provider log output](/terraform/plugin/log/managing) and [debugging Terraform](/terraform/internals/debugging). #### Logging Levels | Environment Variable Name | Default | Description | |---------------------------|---------|-------------| | `TF_ACC_LOG` | N/A | Set the `TF_LOG` environment variable used by Terraform CLI while testing. If set, overrides `TF_LOG_CORE`. Use `TF_LOG_CORE` and `TF_LOG_PROVIDER` to configure separate levels for Terraform CLI logging. | -| `TF_LOG` | N/A | Set the log level for the Go standard library `log` package. If set to any level, sets the `TRACE` log level for any SDK and provider logs written by [`terraform-plugin-log`](/plugin/log/writing). Use the `TF_LOG_SDK*` and `TF_LOG_PROVIDER_*` environment variables described in [managing log output](/plugin/log/managing) to decrease or disable SDK and provider logs written by [`terraform-plugin-log`](/plugin/log/writing). Use `TF_ACC_LOG`, `TF_LOG_CORE`, or `TF_LOG_PROVIDER` environment variables to set the logging levels used by Terraform CLI while testing. | +| `TF_LOG` | N/A | Set the log level for the Go standard library `log` package. If set to any level, sets the `TRACE` log level for any SDK and provider logs written by [`terraform-plugin-log`](/terraform/plugin/log/writing). Use the `TF_LOG_SDK*` and `TF_LOG_PROVIDER_*` environment variables described in [managing log output](/terraform/plugin/log/managing) to decrease or disable SDK and provider logs written by [`terraform-plugin-log`](/terraform/plugin/log/writing). Use `TF_ACC_LOG`, `TF_LOG_CORE`, or `TF_LOG_PROVIDER` environment variables to set the logging levels used by Terraform CLI while testing. | | `TF_LOG_CORE` | `TF_ACC_LOG` | Set the `TF_LOG_CORE` environment variable used by Terraform CLI logging of graph operations and other core functionality while testing. If `TF_ACC_LOG` is set, this setting has no effect. Use `TF_LOG_PROVIDER` to configure a separate level for Terraform CLI logging of external providers while testing (e.g. defined by the `TestCase` or `TestStep` type `ExternalProviders` field). | | `TF_LOG_PROVIDER` | `TF_ACC_LOG` | Set the `TF_LOG_PROVIDER` environment variable used by Terraform CLI logging of external providers while testing (e.g. defined by the `TestCase` or `TestStep` type `ExternalProviders` field). If set, overrides `TF_ACC_LOG`. Use `TF_LOG_CORE` to configure a separate level for Terraform CLI logging of graph operations and other core functionality while testing. | @@ -270,7 +270,7 @@ By default, there is no logging output when running the `go test` command. Use o The logs associated with each test can output across incorrect files as each new test starts if the provider is using the Go standard library [`log` package](https://pkg.go.dev/log) for logging, acceptance testing that uses [`helper/resource.ParallelTest()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#ParallelTest), and `TF_LOG_PATH_MASK`. To resolve this issue, choose one of the following approaches: -* Use [`terraform-plugin-log`](/plugin/log/writing) based logging. Each logger will be correctly associated with each test name output. +* Use [`terraform-plugin-log`](/terraform/plugin/log/writing) based logging. Each logger will be correctly associated with each test name output. * Wrap testing execution so that each test is individually executed with `go test`. Since each `go test` process will have its own `log` package output handling, logging will be correctly associated with each test name output. * Replace [`helper/resource.ParallelTest()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#ParallelTest) with [`helper/resource.Test()`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#Test) and ensure [`(*testing.T).Parallel()`](https://pkg.go.dev/testing#T.Parallel) is not called in tests. This serializes all testing so each test will be associated with each test name output. @@ -300,4 +300,4 @@ helping users safely and predictably create, change, and improve infrastructure. In our next section we detail how to create “Test Cases”, individual acceptance tests using Terraform’s testing framework, in order to build and verify real infrastructure. [Proceed to Test -Cases](/plugin/sdkv2/testing/acceptance-tests/testcase) +Cases](/terraform/plugin/sdkv2/testing/acceptance-tests/testcase) diff --git a/website/docs/plugin/sdkv2/testing/acceptance-tests/sweepers.mdx b/website/docs/plugin/sdkv2/testing/acceptance-tests/sweepers.mdx index 53c45682a3..62d5cf4072 100644 --- a/website/docs/plugin/sdkv2/testing/acceptance-tests/sweepers.mdx +++ b/website/docs/plugin/sdkv2/testing/acceptance-tests/sweepers.mdx @@ -7,7 +7,7 @@ description: >- # Sweepers -Acceptance tests in Terraform provision and verify real infrastructure using [Terraform's testing framework](/plugin/sdkv2/testing/acceptance-tests). Ideally all infrastructure created is then destroyed within the lifecycle of a test, however the reality is that there are several situations that can arise where resources created during a test are “leaked”. Leaked test resources are resources created by Terraform during a test, but Terraform either failed to destroy them as part of the test, or the test falsely reported all resources were destroyed after completing the test. Common causes are intermittent errors or failures in vendor APIs, or developer error in the resource code or test. +Acceptance tests in Terraform provision and verify real infrastructure using [Terraform's testing framework](/terraform/plugin/sdkv2/testing/acceptance-tests). Ideally all infrastructure created is then destroyed within the lifecycle of a test, however the reality is that there are several situations that can arise where resources created during a test are “leaked”. Leaked test resources are resources created by Terraform during a test, but Terraform either failed to destroy them as part of the test, or the test falsely reported all resources were destroyed after completing the test. Common causes are intermittent errors or failures in vendor APIs, or developer error in the resource code or test. To address the possibility of leaked resources, Terraform provides a mechanism called sweepers to cleanup leftover infrastructure. We will add a file to our folder structure that will invoke the sweeper helper. diff --git a/website/docs/plugin/sdkv2/testing/acceptance-tests/testcase.mdx b/website/docs/plugin/sdkv2/testing/acceptance-tests/testcase.mdx index a67308b42a..513b345a9f 100644 --- a/website/docs/plugin/sdkv2/testing/acceptance-tests/testcase.mdx +++ b/website/docs/plugin/sdkv2/testing/acceptance-tests/testcase.mdx @@ -268,7 +268,7 @@ two steps, to verify the resource can be created and subsequently updated, depending on the properties of the resource. In general, simply create/destroy tests will only need one step. -`TestStep`s are covered in detail in [the next section, `TestSteps`](/plugin/sdkv2/testing/acceptance-tests/teststep). +`TestStep`s are covered in detail in [the next section, `TestSteps`](/terraform/plugin/sdkv2/testing/acceptance-tests/teststep). **Example usage:** @@ -309,6 +309,6 @@ to create these scenarios by iterating on Terraform configurations. [1]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource#TestCase -[2]: /plugin/sdkv2/testing/acceptance-tests/teststep +[2]: /terraform/plugin/sdkv2/testing/acceptance-tests/teststep [3]: https://pkg.go.dev/testing#T diff --git a/website/docs/plugin/sdkv2/testing/acceptance-tests/teststep.mdx b/website/docs/plugin/sdkv2/testing/acceptance-tests/teststep.mdx index b0fe8b08a5..9922580cba 100644 --- a/website/docs/plugin/sdkv2/testing/acceptance-tests/teststep.mdx +++ b/website/docs/plugin/sdkv2/testing/acceptance-tests/teststep.mdx @@ -36,7 +36,7 @@ Reference API](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/help ## Steps `Steps` is a field within -[TestCase](/plugin/sdkv2/testing/acceptance-tests/testcase), the struct used +[TestCase](/terraform/plugin/sdkv2/testing/acceptance-tests/testcase), the struct used to construct acceptance tests. Each step represents a full `terraform apply` of a given configuration language, followed by zero or more checks (defined later) to verify the application. Each `Step` is applied in order, and require its own @@ -296,4 +296,4 @@ func testAccCheckExampleWidgetExists(resourceName string, widget *example.Widget ## Next Steps -Acceptance Testing is an essential approach to validating the implementation of a Terraform Provider. Using actual APIs to provision resources for testing can leave behind real infrastructure that costs money between tests. The reasons for these leaks can vary, regardless Terraform provides a mechanism known as [Sweepers](/plugin/sdkv2/testing/acceptance-tests/sweepers) to help keep the testing account clean. +Acceptance Testing is an essential approach to validating the implementation of a Terraform Provider. Using actual APIs to provision resources for testing can leave behind real infrastructure that costs money between tests. The reasons for these leaks can vary, regardless Terraform provides a mechanism known as [Sweepers](/terraform/plugin/sdkv2/testing/acceptance-tests/sweepers) to help keep the testing account clean. diff --git a/website/docs/plugin/sdkv2/testing/index.mdx b/website/docs/plugin/sdkv2/testing/index.mdx index e1a4d98722..4b9bd82ee1 100644 --- a/website/docs/plugin/sdkv2/testing/index.mdx +++ b/website/docs/plugin/sdkv2/testing/index.mdx @@ -13,7 +13,7 @@ deliver on our mission to safely and predictably create, change, and improve infrastructure. Documentation for Terraform tests falls into categories briefly described on this page. Each category has more detailed information on a separate page within the documentation. --> **Note:** Recent versions of Terraform CLI also support [developer overrides in the CLI configuration](/cli/config/config-file#development-overrides-for-provider-developers), which can be useful for manually testing providers. The acceptance testing framework uses real Terraform CLI executions, so we only recommend developer overrides as a last resort option for missing functionality. +-> **Note:** Recent versions of Terraform CLI also support [developer overrides in the CLI configuration](/terraform/cli/config/config-file#development-overrides-for-provider-developers), which can be useful for manually testing providers. The acceptance testing framework uses real Terraform CLI executions, so we only recommend developer overrides as a last resort option for missing functionality. ## Acceptance Tests @@ -48,7 +48,7 @@ using a common make task: $ make testacc ``` -See [Acceptance Testing](/plugin/sdkv2/testing/acceptance-tests) to learn more. +See [Acceptance Testing](/terraform/plugin/sdkv2/testing/acceptance-tests) to learn more. ## Unit Tests @@ -65,4 +65,4 @@ a common make task: $ make test ``` -See [Unit Testing](/plugin/sdkv2/testing/unit-testing) to learn more. +See [Unit Testing](/terraform/plugin/sdkv2/testing/unit-testing) to learn more.