From fa9858369d6c11bc9d7df53470263be774c9e606 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 16 Sep 2022 14:02:29 -0400 Subject: [PATCH] Merge DevPortal into Main (#1061) * Docs Changes for DevDot Migration (#1036) * Remove mentions of HashiCorp Learn * Remaining updates - terraform.io, mentions of docs nav * Update website/docs/plugin/sdkv2/resources/import.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> * Update website/docs/plugin/sdkv2/testing/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> * Update website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> * Update website/docs/plugin/sdkv2/best-practices/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> * Update website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> * Update website/docs/plugin/sdkv2/resources/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> * Update website/docs/plugin/sdkv2/testing/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> * Updating Sidebar to Match Design Spec (#1048) * Updating Sidebar to Match Design Spec * Update website/data/plugin-sdk-nav-data.json * Update website/data/plugin-sdk-nav-data.json * Update index.mdx (#1053) * Update index.mdx * Update website/docs/plugin/sdkv2/index.mdx Co-authored-by: Matthew Garrell <69917312+mgarrell777@users.noreply.github.com> --- website/data/plugin-sdk-nav-data.json | 16 ++-------------- .../docs/plugin/sdkv2/best-practices/index.mdx | 7 ++----- .../plugin/sdkv2/guides/v2-upgrade-guide.mdx | 13 ++++++------- website/docs/plugin/sdkv2/index.mdx | 4 ++-- website/docs/plugin/sdkv2/resources/import.mdx | 2 +- website/docs/plugin/sdkv2/resources/index.mdx | 2 +- .../sdkv2/testing/acceptance-tests/index.mdx | 4 ++-- website/docs/plugin/sdkv2/testing/index.mdx | 14 ++++---------- 8 files changed, 20 insertions(+), 42 deletions(-) diff --git a/website/data/plugin-sdk-nav-data.json b/website/data/plugin-sdk-nav-data.json index 855382810c..352a5efd3c 100644 --- a/website/data/plugin-sdk-nav-data.json +++ b/website/data/plugin-sdk-nav-data.json @@ -1,10 +1,6 @@ [ { "heading": "SDKv2" }, { "title": "Overview", "path": "" }, - { - "title": "Tutorials: Custom Providers", - "href": "https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS" - }, { "title": "Schemas", "routes": [ @@ -40,21 +36,13 @@ } ] }, - { - "title": "Logging", +{ + "title": "Logging", "routes": [ { "title": "Overview", "path": "logging" }, - { - "title": "Writing Logs", - "href": "/plugin/log/writing" - }, - { - "title": "Filtering Logs", - "href": "/plugin/log/filtering" - }, { "title": "HTTP Transport", "path": "logging/http-transport" diff --git a/website/docs/plugin/sdkv2/best-practices/index.mdx b/website/docs/plugin/sdkv2/best-practices/index.mdx index 5797b53303..63ffbf5403 100644 --- a/website/docs/plugin/sdkv2/best-practices/index.mdx +++ b/website/docs/plugin/sdkv2/best-practices/index.mdx @@ -15,11 +15,8 @@ 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 -Providers, with a brief description of each, and link to read more. Each -practice is also linked in navigation on the left. +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. diff --git a/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx b/website/docs/plugin/sdkv2/guides/v2-upgrade-guide.mdx index b7dcfb67de..115499f327 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 @@ -176,11 +176,10 @@ 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 -to whatever you’d document the resource or field as in your terraform.io docs -for the resource. +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 global variable `helper/schema.DescriptionKind`. Its acceptable values are diff --git a/website/docs/plugin/sdkv2/index.mdx b/website/docs/plugin/sdkv2/index.mdx index 0ebb9d830b..403aa6ca00 100644 --- a/website/docs/plugin/sdkv2/index.mdx +++ b/website/docs/plugin/sdkv2/index.mdx @@ -1,6 +1,6 @@ --- page_title: 'Home - Plugin Development: SDKv2' -description: Learn about version 2 of the Terraform Plugin SDK. +description: Maintain plugins built on the legacy SDK. --- # Terraform Plugin SDKv2 @@ -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..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 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 can implement the import functionality on an example Terraform provider. ### Resource Code Implementation diff --git a/website/docs/plugin/sdkv2/resources/index.mdx b/website/docs/plugin/sdkv2/resources/index.mdx index 350f6b2651..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 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 [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 diff --git a/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx b/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx index bb1bc7e555..6d1c13d2d5 100644 --- a/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx +++ b/website/docs/plugin/sdkv2/testing/acceptance-tests/index.mdx @@ -32,9 +32,9 @@ 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. +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. diff --git a/website/docs/plugin/sdkv2/testing/index.mdx b/website/docs/plugin/sdkv2/testing/index.mdx index e5aad44716..e1a4d98722 100644 --- a/website/docs/plugin/sdkv2/testing/index.mdx +++ b/website/docs/plugin/sdkv2/testing/index.mdx @@ -10,11 +10,10 @@ 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 -briefly described below. Each category has more detailed information by clicking -on the matching item in the left navigation. +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 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 @@ -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.