You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add TF 1.14 documentation for registry and fix up some other provider-related docs (#853)
* add action documentation and fix up some other docs
* add list
* Apply suggestions from code review
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
---------
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Copy file name to clipboardExpand all lines: content/terraform-docs-common/docs/plugin/framework-benefits.mdx
+4-1Lines changed: 4 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -254,8 +254,11 @@ Additional new and improved features in the framework include:
254
254
-**Data Access**: The framework makes it easier to access Terraform data (configuration, plan, and state) and value states (null, known, unknown).
255
255
-**Unrestricted Type System**: The framework lets you create custom attribute types and nested attributes for resources and data sources. The framework type system does not have any restrictions for using complex types as the value for a map type.
256
256
-**Validation Capabilities**: The framework exposes many more configuration validation integration points than the SDK. It is also extensible with provider-defined types that implement validation in the type itself.
257
-
-**Functions**: The framework supports provider-defined functions which are exposed for practitioner configurations.
258
257
-**Enhanced Import and Planning Capabilities**: The framework enables additional import and plan handling capabilities not available in SDKv2.
258
+
-**Dynamic attributes**: The framework supports dynamic data types in schemas, which allows the type of an attribute to be determined at runtime.
259
+
-**Functions**: The framework supports provider-defined functions which are exposed for practitioner configurations.
259
260
-**Ephemeral Resources**: The framework supports ephemeral resources which do not store data in the Terraform plan or state artifacts.
261
+
-**Actions**: The framework supports actions, which are additional operations for expressing workflows that don't strictly fit into CRUD resource management, such as disaster recovery or ad-hoc maintenance.
262
+
-**List Resources**: The framework supports the list operation for a resource, which can be used with Terraform to discover unmanaged resources.
260
263
261
264
Refer to [Framework Feature Comparison](/terraform/plugin/framework/migrating/benefits) for a continued list of features, details, and examples.
Copy file name to clipboardExpand all lines: content/terraform-docs-common/docs/plugin/terraform-plugin-protocol.mdx
+7-82Lines changed: 7 additions & 82 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,6 +13,10 @@ During [discovery](/terraform/plugin/how-terraform-works#discovery), the Terrafo
13
13
14
14
Major versions of the protocol delineate Terraform CLI and Terraform Plugin compatibility. Minor versions of the protocol are additive. The protocol is implemented in [Protocol Buffers](https://developers.google.com/protocol-buffers) and [gRPC](https://grpc.io/), with the canonical source for protocol definitions located in the [Terraform CLI repository](https://github.com/hashicorp/terraform/tree/main/docs/plugin-protocol).
15
15
16
+
For more detail about how the protocol RPCs are used, refer to the following topics:
17
+
-[Framework documentation about RPCs](/terraform/plugin/framework/internals/rpcs)
Protocol version 6 is compatible with Terraform CLI version 1.0 and later. Protocol version 6 includes all version 5 functionality for providers, plus:
@@ -28,6 +32,8 @@ Implementations include:
28
32
*[tf5to6server](/terraform/plugin/mux/translating-protocol-version-5-to-6): A package to translate protocol version 5 providers into protocol version 6.
29
33
*[tf6muxserver](/terraform/plugin/mux/combining-protocol-version-6-providers): A package to combine multiple protocol version 6 providers.
30
34
35
+
Refer to [Terraform Plugin RPC protocol version 6.10](https://github.com/hashicorp/terraform/blob/main/docs/plugin-protocol/tfplugin6.proto) in the Terraform repository for the protocol v6 definition.
36
+
31
37
## Protocol Version 5
32
38
33
39
Protocol version 5 is compatible with Terraform CLI version 0.12 and later.
@@ -40,85 +46,4 @@ Implementations include:
40
46
*[tf6to5server](/terraform/plugin/mux/translating-protocol-version-6-to-5): A package to translate protocol version 6 providers into protocol version 5.
41
47
*[tf5muxserver](/terraform/plugin/mux/combining-protocol-version-5-providers): A package to combine multiple protocol version 5 providers.
42
48
43
-
## Protocol RPCs
44
-
45
-
The Terraform plugin protocol specifies the following RPCs:
46
-
47
-
| Protocol Version 5 | Protocol Version 6 | Description |
|`GetSchema`|`GetProviderSchema`| Returns provider schema, provider metaschema, all resource schemas and all data source schemas. |
50
-
|`GetMetadata`|`GetMetadata`| Returns data source, managed resource, and function metadata, such as names. |
51
-
|`GetFunctions`|`GetFunctions`| Returns function definitions. |
52
-
|`CallFunction`|`CallFunction`| Called when a practitioner configuration contains a provider-defined function. |
53
-
|`PrepareProviderConfig`|`ValidateProviderConfig`| Validates the practitioner supplied provider configuration by verifying types conform to the schema and supports value validation diagnostics. |
54
-
|`ValidateResourceTypeConfig`|`ValidateResourceConfig`| Validates the practitioner supplied resource configuration by verifying types conform to the schema and supports value validation diagnostics. |
55
-
|`ValidateDataSourceConfig`|`ValidateDataResourceConfig`| Validates the practitioner supplied data source configuration by verifying types conform to the schema and supports value validation diagnostics. |
56
-
|`UpgradeResourceState`|`UpgradeResourceState`| Called when a resource has existing state. Primarily useful for when the schema version does not match the current version. The provider is expected to modify the state to upgrade it to the latest schema. |
57
-
|`Configure`|`ConfigureProvider`| Passes the practitioner supplied provider configuration to the provider. |
58
-
|`ReadResource`|`ReadResource`| Called when refreshing a resource's state. |
59
-
|`ReadDataSource`|`ReadDataSource`| Called when refreshing a data source's state. |
60
-
|`PlanResourceChange`|`PlanResourceChange`| Calculates a plan for a resource. A proposed new state is generated, which the provider can modify. |
61
-
|`ApplyResourceChange`|`ApplyResourceChange`| Called when a practitioner has approved a planned change. The provider is to apply the changes contained in the plan, and return a resulting state matching the given plan. |
62
-
|`ImportResourceState`|`ImportResourceState`| Called when importing a resource into state so that the resource becomes managed. |
The following illustrate the RPCs that are sent during execution of the specified Terraform commands.
69
-
70
-
The RPCs issued are for a provider that is using version 6 of the Terraform plugin protocol when the Terraform configuration contains configuration for the provider, a resource and a data source.
71
-
72
-
### _terraform validate_
73
-
74
-
Executing _terraform validate_ results in the following unique RPCs:
Executing _terraform plan_ results in the following unique RPCs:
89
-
90
-
91
-
92
-
The general sequence of RPCs is as follows:
93
-
94
-
- GetProviderSchema
95
-
- CallFunction
96
-
- ValidateProviderConfig
97
-
- ValidateResourceConfig
98
-
- ValidateDataResourceConfig
99
-
- ConfigureProvider
100
-
- ReadDataSource
101
-
- PlanResourceChange
102
-
103
-
### _terraform apply_
104
-
105
-
Executing _terraform apply_ (with default -refresh=true and -auto-approve) results in the following unique RPCs:
106
-
107
-
108
-
109
-
The general sequence of RPCs is as follows:
110
-
111
-
- GetProviderSchema
112
-
- CallFunction
113
-
- ValidateProviderConfig
114
-
- ValidateResourceConfig
115
-
- ValidateDataResourceConfig
116
-
- ConfigureProvider
117
-
- UpgradeResourceState
118
-
- only called if resource already exists in state
119
-
- ReadResource
120
-
- only called if resource already exists in state
121
-
- ReadDataSource
122
-
- PlanResourceChange
123
-
- ApplyResourceChange
124
-
49
+
Refer to [Terraform Plugin RPC protocol version 5.10](https://github.com/hashicorp/terraform/blob/main/docs/plugin-protocol/tfplugin5.proto) in the Terraform repository for the protocol v5 definition.
Copy file name to clipboardExpand all lines: content/terraform-docs-common/docs/registry/providers/docs.mdx
+57-15Lines changed: 57 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,18 +34,20 @@ If preferred you can choose to also invoke this manually for your provider. Once
34
34
35
35
## Format
36
36
37
-
Provider documentation should be a directory of Markdown documents in the provider repository. Each Markdown document is rendered as a separate page. The directory should include a document for the provider index, a document for each resource, data source, ephemeral resource and function, and optional documents for any guides.
37
+
Provider documentation should be a directory of Markdown documents in the provider repository. Each Markdown document is rendered as a separate page. The directory should include a document for the provider index, a document for each resource, data source, ephemeral resource, action, list resource, function, and optional documents for any guides.
|`docs/`|`index.md`| Index page for the provider. |
44
-
|`docs/guides/`|`<guide>.md`| Additional documentation for guides. |
45
-
|`docs/resources/`|`<resource>.md`| Information for a Resource. Filename should not include a `<PROVIDER NAME>_` prefix. |
46
-
|`docs/data-sources/`|`<data_source>.md`| Information on a provider data source. |
47
-
|`docs/functions/`|`<function>.md`| Information on a provider function. |
48
-
|`docs/ephemeral-resources/`|`<ephemeral-resource>.md`| Information for an Ephemeral Resource. Filename should not include a `<PROVIDER NAME>_` prefix. |
|`docs/`|`index.md`| Index page for the provider. |
44
+
|`docs/guides/`|`<guide>.md`| Additional documentation for guides. |
45
+
|`docs/resources/`|`<resource>.md`| Information for a Resource. Filename should not include a `<PROVIDER NAME>_` prefix. |
46
+
|`docs/data-sources/`|`<data_source>.md`| Information on a provider data source. |
47
+
|`docs/functions/`|`<function>.md`| Information on a provider function. |
48
+
|`docs/ephemeral-resources/`|`<ephemeral-resource>.md`| Information for an Ephemeral Resource. Filename should not include a `<PROVIDER NAME>_` prefix. |
49
+
|`docs/actions/`|`<action>.md`| Information for an action. Filename should not include a `<PROVIDER NAME>_` prefix. |
50
+
|`docs/list-resources/`|`<list-resource>.md`| Information for a list resource. Filename should not include a `<PROVIDER NAME>_` prefix. |
49
51
50
52
-> **Note:** To support provider docs already formatted for publishing to [the website][terraform-io-providers], the Terraform Registry also supports docs in a `website/docs/` legacy directory with file extensions of `.html.markdown` or `.html.md`.
Description of what this resource does, with links to official
81
85
app/service documentation.
@@ -155,32 +159,50 @@ If you start a paragraph with a special arrow-like sigil, it will become a color
155
159
156
160
## Navigation Hierarchy
157
161
158
-
Provider docs are organized by category: functions, ephemeral resources, resources, data sources, and guides. At a minimum, a provider must contain an index (`docs/index.md`) and at least one function, ephemeral resource, resource, or data source.
162
+
Provider docs are organized by the following categories:
163
+
164
+
- functions
165
+
- actions
166
+
- list resources
167
+
- ephemeral resources
168
+
- resources
169
+
- data sources
170
+
- guides
171
+
172
+
At a minimum, a provider must contain an index file, `docs/index.md`, and at least one function, action, ephemeral resource, list resource, resource, or data source.
159
173
160
174
### Typical Structure
161
175
162
-
A provider named `example` with a resourceand data source for `instance`, an ephemeral resource for `auth_token`, and a function named `parse_instance_id` would have these 4 files:
176
+
A provider named `example` with a resource, list resource, and data source for `instance`, an ephemeral resource for `auth_token`, an action named `stop_instance`, and a function named `parse_instance_id` would have these 5 files:
163
177
164
178
```
165
179
docs/
166
180
index.md
181
+
actions/
182
+
stop_instance.md
167
183
data-sources/
168
184
instance.md
169
185
ephemeral-resources/
170
186
auth_token.md
171
187
functions/
172
188
parse_instance_id.md
189
+
list-resources/
190
+
instance.md
173
191
resources/
174
192
instance.md
175
193
```
176
194
177
195
After publishing this provider version, its page on the Terraform Registry would display a navigation which resembles this hierarchy:
178
196
179
197
* example Provider
198
+
* Actions
199
+
* example_stop_instance
180
200
* Functions
181
201
* parse_instance_id
182
202
* Ephemeral Resources
183
203
* example_auth_token
204
+
* List Resources
205
+
* example_instance
184
206
* Resources
185
207
* example_instance
186
208
* Data Sources
@@ -200,10 +222,14 @@ This would change the navigation hierarchy to the following:
200
222
201
223
* example Provider
202
224
* Compute
225
+
* Actions
226
+
* example_stop_instance
203
227
* Functions
204
228
* parse_instance_id
205
229
* Ephemeral Resources
206
230
* example_auth_token
231
+
* List Resources
232
+
* example_instance
207
233
* Resources
208
234
* example_instance
209
235
* Data Sources
@@ -225,12 +251,16 @@ docs/
225
251
index.md
226
252
guides/
227
253
authenticating.md
254
+
actions/
255
+
stop_instance.md
228
256
data-sources/
229
257
instance.md
230
258
ephemeral-resources/
231
259
auth_token.md
232
260
functions/
233
261
parse_instance_id.md
262
+
list-resources/
263
+
instance.md
234
264
resources/
235
265
instance.md
236
266
```
@@ -248,16 +278,20 @@ The `page_title` is used (instead of the filename) for rendering the link to thi
248
278
* example Provider
249
279
* Guides
250
280
* Authenticating with Example Cloud
281
+
* Actions
282
+
* example_stop_instance
251
283
* Functions
252
284
* parse_instance_id
253
285
* Ephemeral Resources
254
286
* example_auth_token
287
+
* List Resources
288
+
* example_instance
255
289
* Resources
256
290
* example_instance
257
291
* Data Sources
258
292
* example_instance
259
293
260
-
Guides are always rendered before resources, data sources, functions, ephemeral resources, and any subcategories.
294
+
Guides are always rendered before resources, data sources, functions, actions, ephemeral resources, list resources, and any subcategories.
261
295
262
296
If a `page_title` attribute is not found, the title will default to the filename without the extension.
263
297
@@ -272,12 +306,16 @@ docs/
272
306
authenticating-basic.md
273
307
authenticating-oauth.md
274
308
setup.md
309
+
actions/
310
+
stop_instance.md
275
311
data-sources/
276
312
instance.md
277
313
ephemeral-resources/
278
314
auth_token.md
279
315
functions/
280
316
parse_instance_id.md
317
+
list-resources/
318
+
instance.md
281
319
resources/
282
320
instance.md
283
321
```
@@ -290,10 +328,14 @@ Assuming that these three guides have titles similar to their filenames, and the
290
328
* Authentication
291
329
* Authenticating with Basic Authentication
292
330
* Authenticating with OAuth
331
+
* Actions
332
+
* example_stop_instance
293
333
* Functions
294
334
* parse_instance_id
295
335
* Ephemeral Resources
296
336
* example_auth_token
337
+
* List Resources
338
+
* example_instance
297
339
* Resources
298
340
* example_instance
299
341
* Data Sources
@@ -313,7 +355,7 @@ If you want to publish docs on the Terraform Registry that are not available on
313
355
1. Expand the folder names to match the Terraform Registry's expected format:
314
356
* Rename `docs/d/` to `docs/data-sources/`
315
357
* Rename `docs/r/` to `docs/resources/`
316
-
* No changes necessary for `docs/functions/`, `docs/ephemeral-resources`, or `docs/guides`
358
+
* No changes necessary for `docs/functions/`, `docs/ephemeral-resources`, `docs/list-resources`, `docs/actions`, or `docs/guides`
317
359
1. Change file suffixes from `.html.markdown` or `.html.md` to `.md`.
0 commit comments