-
Notifications
You must be signed in to change notification settings - Fork 232
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
website: Migrate documentation from terraform-website to project repo…
…sitory (#953) This migrates the https://terraform.io/plugin/sdkv2 content and navigation from the terraform-website repository to this one. For now, merges to the `main` branch will trigger website updates. Developers can preview changes by utilizing a new `make website` target.
- Loading branch information
1 parent
48310fc
commit c31391d
Showing
37 changed files
with
6,686 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| node_modules | ||
| website-preview |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| [ | ||
| { "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": [ | ||
| { "title": "Overview", "path": "schemas" }, | ||
| { "title": "Schema Types", "path": "schemas/schema-types" }, | ||
| { | ||
| "title": "Schema Behaviors", | ||
| "path": "schemas/schema-behaviors" | ||
| }, | ||
| { | ||
| "title": "Schema Methods", | ||
| "path": "schemas/schema-methods", | ||
| "hidden": true | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Resources", | ||
| "routes": [ | ||
| { "title": "Overview", "path": "resources" }, | ||
| { | ||
| "title": "Customizing Differences", | ||
| "path": "resources/customizing-differences" | ||
| }, | ||
| { "title": "Import", "path": "resources/import" }, | ||
| { | ||
| "title": "Retries and Customizable Timeouts", | ||
| "path": "resources/retries-and-customizable-timeouts" | ||
| }, | ||
| { | ||
| "title": "State Migration", | ||
| "path": "resources/state-migration" | ||
| } | ||
| ] | ||
| }, | ||
| { "title": "Debugging Providers", "path": "debugging" }, | ||
| { | ||
| "title": "Upgrade Guides", | ||
| "routes": [ | ||
| { | ||
| "title": "Compatibility with Terraform 0.12", | ||
| "path": "guides/terraform-0.12-compatibility" | ||
| }, | ||
| { | ||
| "title": "Switching to the standalone SDK", | ||
| "path": "guides/v1-upgrade-guide" | ||
| }, | ||
| { | ||
| "title": "v2 Upgrade Guide", | ||
| "path": "guides/v2-upgrade-guide" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Best Practices", | ||
| "routes": [ | ||
| { "title": "Overview", "path": "best-practices" }, | ||
| { | ||
| "title": "Naming", | ||
| "path": "best-practices/naming" | ||
| }, | ||
| { | ||
| "title": "Depending on Providers", | ||
| "path": "best-practices/depending-on-providers" | ||
| }, | ||
| { | ||
| "title": "Deprecations, Removals, and Renames", | ||
| "path": "best-practices/deprecations" | ||
| }, | ||
| { | ||
| "title": "Detecting Drift", | ||
| "path": "best-practices/detecting-drift" | ||
| }, | ||
| { | ||
| "title": "Handling Sensitive Data", | ||
| "path": "best-practices/sensitive-state" | ||
| }, | ||
| { | ||
| "title": "Testing Patterns", | ||
| "path": "best-practices/testing" | ||
| }, | ||
| { | ||
| "title": "Versioning and Changelog", | ||
| "path": "best-practices/versioning" | ||
| }, | ||
| { | ||
| "title": "Writing Non-Go Providers", | ||
| "path": "best-practices/other-languages" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Testing", | ||
| "routes": [ | ||
| { "title": "Overview", "path": "testing" }, | ||
| { | ||
| "title": "Acceptance Testing", | ||
| "routes": [ | ||
| { | ||
| "title": "Overview", | ||
| "path": "testing/acceptance-tests" | ||
| }, | ||
| { | ||
| "title": "Test Cases", | ||
| "path": "testing/acceptance-tests/testcase" | ||
| }, | ||
| { | ||
| "title": "Test Steps", | ||
| "path": "testing/acceptance-tests/teststep" | ||
| }, | ||
| { | ||
| "title": "Sweepers", | ||
| "path": "testing/acceptance-tests/sweepers" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Testing API", | ||
| "path": "testing/testing-api", | ||
| "hidden": true | ||
| }, | ||
| { | ||
| "title": "Testing Patterns", | ||
| "path": "testing/testing-patterns", | ||
| "hidden": true | ||
| }, | ||
| { | ||
| "title": "Unit Testing", | ||
| "path": "testing/unit-testing" | ||
| } | ||
| ] | ||
| } | ||
| ] |
53 changes: 53 additions & 0 deletions
53
website/docs/plugin/sdkv2/best-practices/depending-on-providers.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| --- | ||
| page_title: Plugin Development - Depending on Providers | ||
| description: How to safely depend on providers and understand their interfaces. | ||
| --- | ||
|
|
||
| # Depending on Providers | ||
|
|
||
| Terraform's providers are a substantial amount of code, and occasionally it | ||
| makes sense to depend on their functionality. The most straightforward and | ||
| obvious way to depend on a provider is to depend on the Terraform CLI, but | ||
| occasionally it makes sense to rely on a provider in a different context. | ||
|
|
||
| This guide lays out the supported ways to interface with and depend on | ||
| Terraform's providers. Unless the provider explicitly states otherwise, no | ||
| other compatibility guarantees are provided. | ||
|
|
||
| ## Do Not Import Providers as Go Modules | ||
|
|
||
| Terraform's providers are written as Go packages, and they mostly use Go | ||
| modules as their dependency management solution. This makes it tempting to | ||
| import the provider as a dependency of your Go code, and to call its exposed | ||
| interface. This is explicitly an **unsupported** way to interact with providers | ||
| and provider maintainers make no guarantees around backwards compatibility or | ||
| the continued functioning of code that does this. | ||
|
|
||
| Providers are unable to be imported as Go modules reliably because their | ||
| versioning scheme is intended to convey information about the Terraform config | ||
| interface the provider presents. It's unable to capture both the configuration | ||
| interface _and_ the Go API interface in a useful way, as what is compatible in | ||
| one may not be compatible in the other. Rather than give the impression that | ||
| the package should be imported by using the `/vX` suffix now mandated for | ||
| versions after 2.0.0, providers have chosen to make their incompatibility with | ||
| being imported into Go code explicit. | ||
|
|
||
| If you find yourself needing to do this, perhaps one of the methods below will | ||
| work for you, and is explicitly supported and covered under versioning policies. | ||
| If not, please reach out and [open an issue](https://github.com/hashicorp/terraform/issues/new) | ||
| outlining your use case, and we'll work with you to find an appropriate way | ||
| to interface with Terraform to meet your use case. | ||
|
|
||
| ## Exporting the Schema | ||
|
|
||
| Some projects just care about the schema and resources a provider presents. As | ||
| of Terraform 0.12, the `terraform providers schema -json` command can be used | ||
| to export a JSON representation of the schemas for the providers used in a | ||
| workspace. | ||
|
|
||
| ## Using the RPC Protocol | ||
|
|
||
| For projects that actually want to drive the provider, the supported option is to use the [gRPC protocol](https://github.com/hashicorp/terraform/tree/main/docs/plugin-protocol) | ||
| and the RPC calls the protocol supplies. This | ||
| protocol is the same protocol that drives Terraform's CLI interface, and | ||
| it is versioned using a protocol version. It changes relatively infrequently. |
Oops, something went wrong.