Skip to content

Commit c31391d

Browse files
thiskevinwangthiskevinwang
authored
website: Migrate documentation from terraform-website to project repository (#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.
1 parent 48310fc commit c31391d

37 files changed

+6686
-1
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules
2+
website-preview

‎Makefile‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
GOFMT_FILES?=$$(find . -name '*.go')
22

3+
WEBSITE_REPO=github.com/hashicorp/terraform-website
4+
WEBSITE_BRANCH=master
5+
6+
CURRENT_GIT_REPO=$$(basename `git rev-parse --show-toplevel`)
7+
CURRENT_GIT_BRANCH=$$(git rev-parse --abbrev-ref HEAD)
8+
9+
WEBSITE_DOCKER_IMAGE="hashicorp/terraform-website:full"
10+
WEBSITE_DOCKER_IMAGE_LOCAL="hashicorp-terraform-website-local"
11+
WEBSITE_DOCKER_RUN_FLAGS=--interactive \
12+
--rm \
13+
--tty \
14+
--workdir "/website" \
15+
--volume "$(shell pwd)/website:/website/preview" \
16+
--publish "3000:3000" \
17+
-e "IS_CONTENT_PREVIEW=true" \
18+
-e "PREVIEW_FROM_REPO=$(CURRENT_GIT_REPO)" \
19+
-e "NAV_DATA_DIRNAME=./preview/data" \
20+
-e "CONTENT_DIRNAME=./preview/docs" \
21+
-e "CURRENT_GIT_BRANCH=$(CURRENT_GIT_BRANCH)"
22+
323
default: test
424

525
test: fmtcheck generate
@@ -14,4 +34,25 @@ fmt:
1434
fmtcheck:
1535
@sh -c "'$(CURDIR)/scripts/gofmtcheck.sh'"
1636

17-
.PHONY: default fmt fmtcheck generate test
37+
# Run the terraform.io website to preview local content changes
38+
website:
39+
@echo "==> Downloading latest Docker image..."
40+
@docker pull ${WEBSITE_DOCKER_IMAGE}
41+
@echo "==> Starting website in Docker..."
42+
@docker run ${WEBSITE_DOCKER_RUN_FLAGS} ${WEBSITE_DOCKER_IMAGE} npm start
43+
44+
# Run the terraform.io website via a locally built docker image
45+
#
46+
# This is useful for development as you may be building an image
47+
# with local changes from the `terraform-website` repo.
48+
website/local:
49+
@echo "==> Starting website in Docker..."
50+
@docker run ${WEBSITE_DOCKER_RUN_FLAGS} ${WEBSITE_DOCKER_IMAGE_LOCAL} npm start
51+
52+
# Build the terraform.io image using `terraform-website` git repo as the build context
53+
website/build-local:
54+
@echo "==> Building local Docker image"
55+
@docker build https://github.com/hashicorp/terraform-website.git\#$(WEBSITE_BRANCH) \
56+
-t $(WEBSITE_DOCKER_IMAGE_LOCAL)
57+
58+
.PHONY: default fmt fmtcheck generate test website website/local website/build-local

‎website/data/plugin-sdk-nav-data.json‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
[
2+
{ "heading": "SDKv2" },
3+
{ "title": "Overview", "path": "" },
4+
{
5+
"title": "Tutorials: Custom Providers",
6+
"href": "https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS"
7+
},
8+
{
9+
"title": "Schemas",
10+
"routes": [
11+
{ "title": "Overview", "path": "schemas" },
12+
{ "title": "Schema Types", "path": "schemas/schema-types" },
13+
{
14+
"title": "Schema Behaviors",
15+
"path": "schemas/schema-behaviors"
16+
},
17+
{
18+
"title": "Schema Methods",
19+
"path": "schemas/schema-methods",
20+
"hidden": true
21+
}
22+
]
23+
},
24+
{
25+
"title": "Resources",
26+
"routes": [
27+
{ "title": "Overview", "path": "resources" },
28+
{
29+
"title": "Customizing Differences",
30+
"path": "resources/customizing-differences"
31+
},
32+
{ "title": "Import", "path": "resources/import" },
33+
{
34+
"title": "Retries and Customizable Timeouts",
35+
"path": "resources/retries-and-customizable-timeouts"
36+
},
37+
{
38+
"title": "State Migration",
39+
"path": "resources/state-migration"
40+
}
41+
]
42+
},
43+
{ "title": "Debugging Providers", "path": "debugging" },
44+
{
45+
"title": "Upgrade Guides",
46+
"routes": [
47+
{
48+
"title": "Compatibility with Terraform 0.12",
49+
"path": "guides/terraform-0.12-compatibility"
50+
},
51+
{
52+
"title": "Switching to the standalone SDK",
53+
"path": "guides/v1-upgrade-guide"
54+
},
55+
{
56+
"title": "v2 Upgrade Guide",
57+
"path": "guides/v2-upgrade-guide"
58+
}
59+
]
60+
},
61+
{
62+
"title": "Best Practices",
63+
"routes": [
64+
{ "title": "Overview", "path": "best-practices" },
65+
{
66+
"title": "Naming",
67+
"path": "best-practices/naming"
68+
},
69+
{
70+
"title": "Depending on Providers",
71+
"path": "best-practices/depending-on-providers"
72+
},
73+
{
74+
"title": "Deprecations, Removals, and Renames",
75+
"path": "best-practices/deprecations"
76+
},
77+
{
78+
"title": "Detecting Drift",
79+
"path": "best-practices/detecting-drift"
80+
},
81+
{
82+
"title": "Handling Sensitive Data",
83+
"path": "best-practices/sensitive-state"
84+
},
85+
{
86+
"title": "Testing Patterns",
87+
"path": "best-practices/testing"
88+
},
89+
{
90+
"title": "Versioning and Changelog",
91+
"path": "best-practices/versioning"
92+
},
93+
{
94+
"title": "Writing Non-Go Providers",
95+
"path": "best-practices/other-languages"
96+
}
97+
]
98+
},
99+
{
100+
"title": "Testing",
101+
"routes": [
102+
{ "title": "Overview", "path": "testing" },
103+
{
104+
"title": "Acceptance Testing",
105+
"routes": [
106+
{
107+
"title": "Overview",
108+
"path": "testing/acceptance-tests"
109+
},
110+
{
111+
"title": "Test Cases",
112+
"path": "testing/acceptance-tests/testcase"
113+
},
114+
{
115+
"title": "Test Steps",
116+
"path": "testing/acceptance-tests/teststep"
117+
},
118+
{
119+
"title": "Sweepers",
120+
"path": "testing/acceptance-tests/sweepers"
121+
}
122+
]
123+
},
124+
{
125+
"title": "Testing API",
126+
"path": "testing/testing-api",
127+
"hidden": true
128+
},
129+
{
130+
"title": "Testing Patterns",
131+
"path": "testing/testing-patterns",
132+
"hidden": true
133+
},
134+
{
135+
"title": "Unit Testing",
136+
"path": "testing/unit-testing"
137+
}
138+
]
139+
}
140+
]

‎website/docs/plugin/sdkv2/best-practices/depending-on-providers.mdx‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
page_title: Plugin Development - Depending on Providers
3+
description: How to safely depend on providers and understand their interfaces.
4+
---
5+
6+
# Depending on Providers
7+
8+
Terraform's providers are a substantial amount of code, and occasionally it
9+
makes sense to depend on their functionality. The most straightforward and
10+
obvious way to depend on a provider is to depend on the Terraform CLI, but
11+
occasionally it makes sense to rely on a provider in a different context.
12+
13+
This guide lays out the supported ways to interface with and depend on
14+
Terraform's providers. Unless the provider explicitly states otherwise, no
15+
other compatibility guarantees are provided.
16+
17+
## Do Not Import Providers as Go Modules
18+
19+
Terraform's providers are written as Go packages, and they mostly use Go
20+
modules as their dependency management solution. This makes it tempting to
21+
import the provider as a dependency of your Go code, and to call its exposed
22+
interface. This is explicitly an **unsupported** way to interact with providers
23+
and provider maintainers make no guarantees around backwards compatibility or
24+
the continued functioning of code that does this.
25+
26+
Providers are unable to be imported as Go modules reliably because their
27+
versioning scheme is intended to convey information about the Terraform config
28+
interface the provider presents. It's unable to capture both the configuration
29+
interface _and_ the Go API interface in a useful way, as what is compatible in
30+
one may not be compatible in the other. Rather than give the impression that
31+
the package should be imported by using the `/vX` suffix now mandated for
32+
versions after 2.0.0, providers have chosen to make their incompatibility with
33+
being imported into Go code explicit.
34+
35+
If you find yourself needing to do this, perhaps one of the methods below will
36+
work for you, and is explicitly supported and covered under versioning policies.
37+
If not, please reach out and [open an issue](https://github.com/hashicorp/terraform/issues/new)
38+
outlining your use case, and we'll work with you to find an appropriate way
39+
to interface with Terraform to meet your use case.
40+
41+
## Exporting the Schema
42+
43+
Some projects just care about the schema and resources a provider presents. As
44+
of Terraform 0.12, the `terraform providers schema -json` command can be used
45+
to export a JSON representation of the schemas for the providers used in a
46+
workspace.
47+
48+
## Using the RPC Protocol
49+
50+
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)
51+
and the RPC calls the protocol supplies. This
52+
protocol is the same protocol that drives Terraform's CLI interface, and
53+
it is versioned using a protocol version. It changes relatively infrequently.

0 commit comments

Comments
 (0)