From dc4688d77f1c6b18c50c655d84b827f87ab1e565 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 19 Aug 2022 17:48:24 -0400 Subject: [PATCH 1/9] Remove mentions of HashiCorp Learn --- website/docs/plugin/sdkv2/index.mdx | 2 +- website/docs/plugin/sdkv2/resources/import.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/plugin/sdkv2/index.mdx b/website/docs/plugin/sdkv2/index.mdx index 0ebb9d830b..5d7a33e5c9 100644 --- a/website/docs/plugin/sdkv2/index.mdx +++ b/website/docs/plugin/sdkv2/index.mdx @@ -11,7 +11,7 @@ Terraform Plugin SDKv2 is an established way to develop Terraform Plugins on [pr ## Get Started -- Try the [Call APIs with Custom Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials on HashiCorp Learn. +- Try the [Call APIs with Custom Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. - Clone the [terraform-provider-scaffolding](https://github.com/hashicorp/terraform-provider-scaffolding) template repository on GitHub. ## Key Concepts diff --git a/website/docs/plugin/sdkv2/resources/import.mdx b/website/docs/plugin/sdkv2/resources/import.mdx index 6db26cfeaa..59613b9087 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 on HashiCorp Learn. In this tutorial, you will implement the import functionality on an example Terraform provider. +> **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 will implement the import functionality on an example Terraform provider. ### Resource Code Implementation From ffe8f61d38ae4f534eb9419c88a7c338a5c940bd Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 19 Aug 2022 17:57:54 -0400 Subject: [PATCH 2/9] Remaining updates - terraform.io, mentions of docs nav --- website/docs/plugin/sdkv2/best-practices/index.mdx | 3 +-- website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx | 7 +++---- website/docs/plugin/sdkv2/resources/index.mdx | 2 +- .../plugin/sdkv2/testing/acceptance-tests/index.mdx | 2 +- website/docs/plugin/sdkv2/testing/index.mdx | 10 ++-------- 5 files changed, 8 insertions(+), 16 deletions(-) diff --git a/website/docs/plugin/sdkv2/best-practices/index.mdx b/website/docs/plugin/sdkv2/best-practices/index.mdx index 5797b53303..27f1ed1061 100644 --- a/website/docs/plugin/sdkv2/best-practices/index.mdx +++ b/website/docs/plugin/sdkv2/best-practices/index.mdx @@ -18,8 +18,7 @@ configuration management systems, et. al). While each provider is unique, over the years we’ve accumulated some patterns that should be adhered to, to ensure a consistent user experience when using Terraform for any given provider. Listed below are a few best practices we’ve found that generally apply to most -Providers, with a brief description of each, and link to read more. Each -practice is also linked in navigation on the left. +Providers, with a brief description of each, and link to read more. This section is a work in progress, with more sections to come. diff --git a/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx b/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx index b7dcfb67de..e4ecea9fcb 100644 --- a/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx +++ b/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx @@ -147,10 +147,10 @@ func Create(ctx context.Context, *schema.ResourceData, meta any) diag.Diagnostic // this is the standard way to convert a Go error to Diagnostics return diag.FromErr(err) } - + // Warning or Errors can be collected in a slice type var diags diag.Diagnostics - + // Diagnostics supports warnings, a detailed message // as well as linking to a specific attribute // see github.com/hashicorp/go-cty for learning the Path types @@ -179,8 +179,7 @@ The `helper/schema.Resource` and `helper/schema.Schema` types both now have groundwork for future improvements to Terraform, and will have no visible effect to the Terraform CLI at the moment. If you’d like to build in support for your provider starting now, it’s recommended that you set these properties -to whatever you’d document the resource or field as in your terraform.io docs -for the resource. +to whatever you would document the resource or field as in your provider documentation for the resource. You can globally set the format of the text in these fields by setting the global variable `helper/schema.DescriptionKind`. Its acceptable values are diff --git a/website/docs/plugin/sdkv2/resources/index.mdx b/website/docs/plugin/sdkv2/resources/index.mdx index 350f6b2651..5f22791bc5 100644 --- a/website/docs/plugin/sdkv2/resources/index.mdx +++ b/website/docs/plugin/sdkv2/resources/index.mdx @@ -7,7 +7,7 @@ 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 basic aspects of developing Terraform resources have already been covered in the [Call APIs with Terraform Providers Learn collection](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) and [Schemas](/plugin/sdkv2/schemas), 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 basic aspects of developing Terraform resources have already been covered in 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](/plugin/sdkv2/schemas), this section covers more advanced features of resource development. ## Import diff --git a/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx b/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx index bb1bc7e555..d440d70555 100644 --- a/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx +++ b/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx @@ -32,7 +32,7 @@ left over from testing and development. Provider acceptance tests use a Terraform CLI binary to run real Terraform commands. The goal is to approximate using the provider with Terraform in production as closely as possible. -Terraform Core and Terraform Plugins act as gRPC client and server, implemented using HashiCorp's [go-plugin](https://github.com/hashicorp/go-plugin) system (see the [RPC Plugin Model](https://github.com/hashicorp/terraform/tree/main/docs/plugin-protocol) section of the Terraform Core documentation). When `go test` is run, the SDK's acceptance test framework starts a plugin server in the same process as the Go test framework. This plugin server runs for the duration of the test case, and each Terraform command (`terraform plan`, `terraform apply`, etc) creates a client that reattaches to this server. +Terraform Core and Terraform Plugins act as gRPC client and server, implemented using HashiCorp's [go-plugin](https://github.com/hashicorp/go-plugin) system (refer to the [RPC Plugin Model](https://github.com/hashicorp/terraform/tree/main/docs/plugin-protocol) section of the Terraform documentation). When `go test` is run, the SDK's acceptance test framework starts a plugin server in the same process as the Go test framework. This plugin server runs for the duration of the test case, and each Terraform command (`terraform plan`, `terraform apply`, etc) creates a client that reattaches to this server. Real-world Terraform usage requires a config file and Terraform working directory on the local filesystem. The framework uses the [`internal/plugintest` package](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/internal/plugintest) to manage temporary directories and files during test runs. This library is not intended for use directly by provider developers. diff --git a/website/docs/plugin/sdkv2/testing/index.mdx b/website/docs/plugin/sdkv2/testing/index.mdx index e5aad44716..5ff573fce1 100644 --- a/website/docs/plugin/sdkv2/testing/index.mdx +++ b/website/docs/plugin/sdkv2/testing/index.mdx @@ -11,8 +11,7 @@ Here we cover information needed to write successful tests for Terraform Plugins. Tests are a vital part of the Terraform ecosystem, verifying we can deliver on our mission to safely and predictably create, change, and improve infrastructure. Documentation for Terraform tests are broken into categories -briefly described below. Each category has more detailed information by clicking -on the matching item in the left navigation. +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 developer overrides are only recommended as a last resort option for missing functionality. @@ -46,7 +45,7 @@ For a given plugin, Acceptance Tests can be run from the root of the project by using a common make task: ```shell -$ make testacc +$ make testacc ``` See [Acceptance Testing](/plugin/sdkv2/testing/acceptance-tests) to learn more. @@ -67,8 +66,3 @@ $ make test ``` See [Unit Testing](/plugin/sdkv2/testing/unit-testing) to learn more. - -## Next Steps - -See the navigation on the left of this page for documentation and guides on -writing tests for Terraform Plugins. From becf9136c0a1b750fb281c7a023fd74279bc8728 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 25 Aug 2022 12:05:29 -0400 Subject: [PATCH 3/9] Update website/docs/plugin/sdkv2/resources/import.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> --- website/docs/plugin/sdkv2/resources/import.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/plugin/sdkv2/resources/import.mdx b/website/docs/plugin/sdkv2/resources/import.mdx index 59613b9087..f0c640ab72 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 will implement the import functionality on an example Terraform provider. +> **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. ### Resource Code Implementation From ab40846344570420a188af849b55f77b53ae98f2 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 25 Aug 2022 12:06:04 -0400 Subject: [PATCH 4/9] Update website/docs/plugin/sdkv2/testing/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> --- website/docs/plugin/sdkv2/testing/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/plugin/sdkv2/testing/index.mdx b/website/docs/plugin/sdkv2/testing/index.mdx index 5ff573fce1..b5feddf74e 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 are broken 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 developer overrides are only recommended as a last resort option for missing functionality. +-> **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. ## Acceptance Tests From 182ab303afdd405afefde2e9e15ebbf75e32f576 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 25 Aug 2022 12:06:14 -0400 Subject: [PATCH 5/9] Update website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> --- website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx b/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx index d440d70555..6d1c13d2d5 100644 --- a/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx +++ b/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx @@ -34,7 +34,7 @@ Provider acceptance tests use a Terraform CLI binary to run real Terraform comma Terraform Core and Terraform Plugins act as gRPC client and server, implemented using HashiCorp's [go-plugin](https://github.com/hashicorp/go-plugin) system (refer to the [RPC Plugin Model](https://github.com/hashicorp/terraform/tree/main/docs/plugin-protocol) section of the Terraform documentation). When `go test` is run, the SDK's acceptance test framework starts a plugin server in the same process as the Go test framework. This plugin server runs for the duration of the test case, and each Terraform command (`terraform plan`, `terraform apply`, etc) creates a client that reattaches to this server. -Real-world Terraform usage requires a config file and Terraform working directory on the local filesystem. The framework uses the [`internal/plugintest` package](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/internal/plugintest) to manage temporary directories and files during test runs. This library is not intended for use directly by provider developers. +Real-world Terraform usage requires a config file and Terraform working directory on the local filesystem. The framework uses the [`internal/plugintest` package](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/v2/internal/plugintest) to manage temporary directories and files during test runs. Provider developers should not use this library directly. While the test framework provides a reasonable simulation of real-world usage, there are some differences, the major one being in the lifecycle of the plugin gRPC server. During normal Terraform operation, the plugin server starts and stops once per graph walk, of which there may be several during one Terraform command. The acceptance test framework, however, maintains one plugin gRPC server for the duration of each test case. In theory, it is possible for providers to carry internal state between operations during tests - but providers would have to go out of their way (and the SDK's public API) to do this. From 737b09b984c2cbe53262e2a58abce53e080b8b51 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 25 Aug 2022 12:07:12 -0400 Subject: [PATCH 6/9] Update website/docs/plugin/sdkv2/best-practices/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> --- website/docs/plugin/sdkv2/best-practices/index.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/docs/plugin/sdkv2/best-practices/index.mdx b/website/docs/plugin/sdkv2/best-practices/index.mdx index 27f1ed1061..63ffbf5403 100644 --- a/website/docs/plugin/sdkv2/best-practices/index.mdx +++ b/website/docs/plugin/sdkv2/best-practices/index.mdx @@ -15,9 +15,7 @@ specific cloud provider, allowing each provider to fully support its unique resources and lifecycles and not settling for the lowest common denominator across all provider resources of that type (virtual machines, networks, configuration management systems, et. al). While each provider is unique, over -the years we’ve accumulated some patterns that should be adhered to, to -ensure a consistent user experience when using Terraform for any given provider. -Listed below are a few best practices we’ve found that generally apply to most +the years, we accumulated recommended patterns that help ensure a consistent user experience when using Terraform for any given provider. This page describes best practices that generally apply to most Providers, with a brief description of each, and link to read more. This section is a work in progress, with more sections to come. From 6ce523b0caad37778be327fb67a03b800018a640 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 25 Aug 2022 12:07:27 -0400 Subject: [PATCH 7/9] Update website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> --- website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx b/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx index e4ecea9fcb..115499f327 100644 --- a/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx +++ b/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx @@ -176,9 +176,9 @@ func Create(ctx context.Context, *schema.ResourceData, meta any) diag.Diagnostic The `helper/schema.Resource` and `helper/schema.Schema` types both now have `Description` properties that accept strings. These properties are laying the -groundwork for future improvements to Terraform, and will have no visible -effect to the Terraform CLI at the moment. If you’d like to build in support -for your provider starting now, it’s recommended that you set these properties +groundwork for future improvements to Terraform, and has no visible +effect to the Terraform CLI at the moment. If you want to build in support +for your provider starting now, we recommend that you set these properties to whatever you would document the resource or field as in your provider documentation for the resource. You can globally set the format of the text in these fields by setting the From 6a288434cc4fea69f89db94e27cec8cc291f09dc Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 25 Aug 2022 12:08:47 -0400 Subject: [PATCH 8/9] Update website/docs/plugin/sdkv2/resources/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> --- website/docs/plugin/sdkv2/resources/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/plugin/sdkv2/resources/index.mdx b/website/docs/plugin/sdkv2/resources/index.mdx index 5f22791bc5..f066fb571e 100644 --- a/website/docs/plugin/sdkv2/resources/index.mdx +++ b/website/docs/plugin/sdkv2/resources/index.mdx @@ -7,7 +7,7 @@ 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 basic aspects of developing Terraform resources have already been covered in 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](/plugin/sdkv2/schemas), 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](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. ## Import From 1143155e2d5eef86c888218b3e99d6eb421721f5 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 25 Aug 2022 12:09:34 -0400 Subject: [PATCH 9/9] Update website/docs/plugin/sdkv2/testing/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> --- website/docs/plugin/sdkv2/testing/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/plugin/sdkv2/testing/index.mdx b/website/docs/plugin/sdkv2/testing/index.mdx index b5feddf74e..e1a4d98722 100644 --- a/website/docs/plugin/sdkv2/testing/index.mdx +++ b/website/docs/plugin/sdkv2/testing/index.mdx @@ -10,7 +10,7 @@ description: |- Here we cover information needed to write successful tests for Terraform Plugins. Tests are a vital part of the Terraform ecosystem, verifying we can deliver on our mission to safely and predictably create, change, and improve -infrastructure. Documentation for Terraform tests are broken into categories +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.