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
Copy file name to clipboardExpand all lines: docs/terraform/advanced-features.mdx
+11-2Lines changed: 11 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,6 @@ title: "Advanced Features"
3
3
description: "Learn about advanced customization options for Terraform providers."
4
4
---
5
5
6
-
7
-
8
6
# Advanced Features
9
7
10
8
## Speciality Annotations
@@ -80,3 +78,14 @@ components:
80
78
nullable: true
81
79
x-speakeasy-terraform-plan-only: true
82
80
```
81
+
82
+
## Deduplicate Terraform Types
83
+
84
+
The `terraform` types folder includes a representation of your data models that is appropriate for the `terraform-plugin-framework` type system. However, if you have multiple types with the same _signature_ (e.g. the same set of child property _types_), there might be a lot of these types that are effectively duplicated. To minimize the git repository / binary size, it might make sense to deduplicate these by re-using types with the same _signature_ across different resources. If you would like to enable this, set the following configuration option:
description: "Learn how to customize Terraform plan behavior and resource versioning."
3
+
description: "Learn how to customize Terraform plan behavior."
4
4
---
5
5
6
-
7
-
8
6
# Plan Modification
9
7
10
-
## Add Custom Plan Modification Logic
8
+
## Custom Attribute Plan Modification
9
+
10
+
Attribute plan modifiers enable advanced default value, resource replacement, and difference suppression logic in managed resources. Due to the Terraform SDK implementation, attribute-level plan modifiers do not have access to provider-level configuration or the API client, however that SDK does support custom resource-level plan modification with implementing the [`resource.ResourceWithModifyPlan` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ResourceWithModifyPlan).
11
11
12
-
Use the `x-speakeasy-plan-modifiers` extension to add custom plan modification logic to Terraform plan operations. Plan modifiers enable advanced default value, resource replacement, and difference suppression logic.
12
+
Use the `x-speakeasy-plan-modifiers` extension to add custom attribute-level plan modification logic to Terraform plan operations.
13
13
14
14
```yaml
15
15
components:
@@ -27,6 +27,14 @@ components:
27
27
28
28
In this scenario, when Speakeasy next generates the Terraform provider, it will bootstrap a custom plan modifier file located at `internal/planmodifiers/int64planmodifier/age_modifier.go`, and import the schema configuration wherever `x-speakeasy-plan-modifiers: AgeModifier` is referenced. Edit the plan modifier file to contain the required logic.
29
29
30
+
The `x-speakeasy-plan-modifiers` extension supports an array of names as well, such as:
31
+
32
+
```yaml
33
+
x-speakeasy-plan-modifiers:
34
+
- FirstPlanModifier
35
+
- SecondPlanModifier
36
+
```
37
+
30
38
### Implementation Notes
31
39
32
40
1. A plan modifier is a type conformant to the `terraform-plugin-framework` expected interface. A unique plan modifier will be bootstrapped in the appropriate subfolder for the Terraform type it is applied to: `boolplanmodifiers`, `float64planmodifiers`, `int64planmodifiers`, `listplanmodifiers`, `mapplanmodifiers`, `numberplanmodifiers`, `objectplanmodifiers`, `setplanmodifiers`, or `stringplanmodifiers`. Speakeasy will always create and use a file as `snake_case.go` for a given `x-speakeasy-plan-modifiers` value.
@@ -35,16 +43,6 @@ In this scenario, when Speakeasy next generates the Terraform provider, it will
35
43
36
44
3. While working with a plan modifier, you have the ability to perform various tasks, including initiating network requests. However, it's important to ensure that plan modifiers do not result in any unintended side effects. Please refer to [the HashiCorp guidance on plan modifier development](https://developer.hashicorp.com/terraform/plugin/framework/resources/plan-modification) or reach out in our Slack if you have questions.
37
45
38
-
4. It is possible to have an array of plan modifiers, for example, `x-speakeasy-plan-modifiers: [FirstModifier, SecondModifier]`.
39
-
40
-
5. A modifier can only be applied to a resource attribute. The annotation will be ignored for data sources. Modifiers cannot be applied at the same level as the `x-speakeasy-entity` annotation because that becomes the "root" of the Terraform resource.
41
-
42
-
6. Speakeasy regenerations do not delete user-written code. If the modifier is no longer in use, it will be ignored (no longer referenced) but the source file will remain. You might want to delete such an orphaned modifier file for repository hygiene.
43
-
44
-
## Specify Resource Version
45
-
46
-
The `x-speakeasy-entity-version` extension specifies the version of a given resource and should *only* be used if you need to write a state migrator, for instance, if you are changing the type of a field.
47
-
48
-
Terraform resource versions are zero-indexed and default to `0`. For your first breaking change requiring a state migrator, set `x-speakeasy-entity-version: 1`. Each state migrator function must migrate from the previous version of the state.
46
+
4. A modifier can only be applied to a resource attribute. The annotation will be ignored for data sources. Modifiers cannot be applied at the same level as the `x-speakeasy-entity` annotation because that becomes the "root" of the Terraform resource.
49
47
50
-
If this is set, a boilerplate state upgrader will be written and hooked into `internal/stateupgraders/your_resource_v1.go`. Please refer to the [Terraform documentation](https://developer.hashicorp.com/terraform/plugin/framework/resources/state-upgrade) for guidance on writing a state migrator.
48
+
5. Speakeasy regenerations do not delete user-written code. If the modifier is no longer in use, it will be ignored (no longer referenced) but the source file will remain. You might want to delete such an orphaned modifier file for repository hygiene.
Copy file name to clipboardExpand all lines: docs/terraform/provider-configuration.mdx
+44-37Lines changed: 44 additions & 37 deletions
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,52 @@
1
1
---
2
-
title: "Configuration"
3
-
description: "Learn how to configure environment values and manage custom resources in the Terraform provider."
2
+
title: "Provider Configuration"
3
+
description: "Learn how to customize the generated Terraform Provider, such as supporting environment variables and custom resources."
4
4
---
5
5
6
-
# Configuration
6
+
# Provider Configuration
7
7
8
-
## Configuring Environment Values
8
+
## Security
9
9
10
-
Use the `environmentVariables` configuration in the `gen.yaml` to set up default values for provider variables to be pulled in from an environment variable. This is useful for mapping known environment values that will hold an API key into the provider.
10
+
The generated Terraform Provider will automatically implement all global security as defined in the OpenAPI Specification via the root level `security` property and its associated `securitySchemes` components. Multiple security options are supported.
11
+
12
+
In this example, the provider will be generated with bearer authenticiation token requirement using an `access_token` provider-level attribute:
13
+
14
+
```yaml
15
+
components:
16
+
securitySchemes:
17
+
accessToken:
18
+
type: http
19
+
scheme: bearer
20
+
security:
21
+
- accessToken: []
22
+
```
23
+
24
+
Refer to the [Configuring Environment Variables section](#configuring-environment-variables) to optionally enable fallback environment variable configuration of the value.
25
+
26
+
Operation-level security is not supported nor recommended. Instead, it is generally more desirable to implement separate providers per security layer. Terraform practitioners are conventionally used to the layering of provider implementations for this use case and Terraform itself is designed around those separation of concerns. Refer to the [HashiCorp provider design principles documentation](https://developer.hashicorp.com/terraform/plugin/best-practices/hashicorp-provider-design-principles) for more context.
27
+
28
+
## Globals
29
+
30
+
Enable provider-level configuration of common properties across many resources via the [`x-speakeasy-globals` extension](/docs/customize/globals). This customization allows Terraform practitioners to configure a value via:
31
+
32
+
* Provider-level only: Default value applied to any resources that use the global
33
+
* Resource-level only: Explicit value applied to only those resource instance(s)
34
+
* Provider-level with resource-level override: Default value applied to any resources that use the global with any explicit resource-level configuration overriding the provider-level value
35
+
36
+
In this example, the provider will accept an `organization_id` configuration as a global:
37
+
38
+
```yaml
39
+
x-speakeasy-globals:
40
+
parameters:
41
+
- name: organizationId
42
+
in: path
43
+
schema:
44
+
type: string
45
+
```
46
+
47
+
## Configuring Environment Variables
48
+
49
+
Use the `environmentVariables` configuration in the `gen.yaml` to set up an environment variable fallback for provider attribute data configuration. For example, accepting an access token value via environment variable, rather than requiring explicit `provider` block attribute configuration from Terraform practitioners.
11
50
12
51
```yaml
13
52
terraform:
@@ -99,35 +138,3 @@ The `additionalEphemeralResources` key follows the same syntax, but will insert
99
138
The `additionalDataSources` key follows the same syntax, but will insert data resources into the provider using `datasource` (instead of `resource`) as the value inserted into the list.
100
139
101
140
To learn more about how to write a Terraform resource, please consult the [official Terraform documentation](https://developer.hashicorp.com/terraform/plugin/framework).
102
-
103
-
## Modifying Resource and Data Source Descriptions
104
-
105
-
The `x-speakeasy-entity-description` extension allows modification of the description of a Terraform resource or data source. This is useful when augmenting the documentation in an OpenAPI specification with documentation for specific resources. This documentation is expected to be in Markdown format. Use this extension alongside the `x-speakeasy-entity` extension.
106
-
107
-
Alternatively, a template folder can be written to customize any or all aspects of generated documentation in alignment with [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs).
108
-
109
-
```yaml
110
-
components:
111
-
schemas:
112
-
Order:
113
-
description: An order helps you make coffee
114
-
x-speakeasy-entity: Order
115
-
x-speakeasy-entity-description: |
116
-
The order resource allows you to declaratively construct an order for coffee.
117
-
118
-
resource "speakeasy_order" "example" {
119
-
name = "Filter Blend"
120
-
price = 11.5
121
-
}
122
-
```
123
-
124
-
## Deduplicate Terraform Types
125
-
126
-
The `terraform` types folder includes a representation of your data models that is appropriate for the `terraform-plugin-framework` type system. However, if you have multiple types with the same _signature_ (e.g. the same set of child property _types_), there might be a lot of these types that are effectively duplicated. To minimize the git repository / binary size, it might make sense to deduplicate these by re-using types with the same _signature_ across different resources. If you would like to enable this, set the following configuration option:
description: "Learn how to customize a generated Terraform Provider resource, such as custom descriptions."
4
+
---
5
+
6
+
# Resource Configuration
7
+
8
+
## Resource Description
9
+
10
+
The `x-speakeasy-entity-description` extension allows modification of the description of a Terraform data or managed resource. This is useful when augmenting the documentation in an OpenAPI specification with documentation for specific resources. This documentation is expected to be in Markdown format. Use this extension alongside the `x-speakeasy-entity` extension.
11
+
12
+
```yaml
13
+
components:
14
+
schemas:
15
+
Order:
16
+
description: An order helps you make coffee
17
+
x-speakeasy-entity: Order
18
+
x-speakeasy-entity-description: |
19
+
The order resource allows you to declaratively construct an order for coffee.
20
+
21
+
resource "speakeasy_order" "example" {
22
+
name = "Filter Blend"
23
+
price = 11.5
24
+
}
25
+
```
26
+
27
+
Alternatively, a template folder can be written to customize any or all aspects of generated documentation in alignment with [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs).
28
+
29
+
## Resource Version
30
+
31
+
The `x-speakeasy-entity-version` extension specifies the version of a given resource and should *only* be used if you need to write a state migrator, for instance, if you are changing the type of a field.
32
+
33
+
Terraform resource versions are zero-indexed and default to `0`. For your first breaking change requiring a state migrator, set `x-speakeasy-entity-version: 1`. Each state migrator function must migrate from the previous version of the state.
34
+
35
+
If this is set, a boilerplate state upgrader will be written and hooked into `internal/stateupgraders/your_resource_v1.go`. Please refer to the [Terraform documentation](https://developer.hashicorp.com/terraform/plugin/framework/resources/state-upgrade) for guidance on writing a state migrator.
0 commit comments