Provider configuration

Security

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.

In this example, the generated provider requires a bearer authentication token using an access_token provider-level attribute:

Refer to the Configuring environment variables section to optionally enable the fallback environment variable configuration of the value.

Operation-level security is neither supported nor recommended. Instead, we recommend implementing separate providers for each security layer. Terraform practitioners are conventionally used to the layering of provider implementations for this use case, and Terraform itself is designed around this separation of concerns. Refer to the HashiCorp provider design principles  for more context.

Server URL

Choose how the generated Terraform Provider will handle the server URL for API requests:

• Hardcoded server URL in Speakeasy generation configuration (gen.yaml file generation section baseServerUrl property) and not configurable in Terraform configurations.
• As defined in the OpenAPI Specification, via the root-level servers property. The generation will automatically handle:
  • Creating a server_url attribute that defaults to the first defined url value and is configurable in Terraform configurations.
  • Creating server URL variable attributes that default to their defined default values and are configurable in Terraform configurations.

In this example, the provider configuration is generated with configurable location and server_url attributes:

Refer to the Configuring environment variables section to optionally enable the fallback environment variable configuration of the value(s).

Globals

Use the x-speakeasy-globals extension to enable provider-level configuration of common properties across multiple resources. This customization allows Terraform practitioners to configure a value in three ways:

• Provider-level only: The default value is applied to any resources that use the global.
• Resource-level only: The explicit value is applied only to those resource instance(s).
• Provider-level with resource-level override: The default value is applied to any resources that use the global, but any explicit resource-level configurations override the provider-level value.

In this example, the provider will accept an organization_id configuration as a global:

Configuring environment variables

Use the environmentVariables configuration in the gen.yaml to set up an environment variable fallback for configuring provider attribute data. For example, the fallback may be accepting an access token value via an environment variable, rather than requiring an explicit provider block attribute configuration from Terraform practitioners.

The environmentVariables configuration is expected to be a list of objects with {env: string, providerAttribute: string} keys and values. These associate environment variables (referenced as env) with provider attributes (referenced as providerAttribute).

Additional provider configurations

Use the additionalProviderAttributes configuration in the gen.yaml file to enable Terraform configurations to specify additional provider-wide customizations. For example:

Custom HTTP headers

Set the httpHeaders configuration with the desired attribute name to enable Terraform configurations to map additional HTTP headers for all HTTP requests.

In this example, HTTP header customization is enabled using the http_headers provider attribute name:

This configuration enables a provider configuration, such as:

Skip TLS verification

Set the tlsSkipVerify configuration with the desired attribute name to enable Terraform configurations to specify a Boolean to disable TLS verification in the HTTP client.

In this example, TLS verification customization is enabled using the tls_skip_verify provider attribute name:

This configuration enables a provider configuration, such as:

Custom resources or data sources

To include an existing resource that is outside of the Speakeasy-generated provider, reference it in gen.yaml as follows:

The additionalResources key is expected to contain a list of { importLocation?: string, importAlias?: string, resource: string } objects. Each resource is inserted into the provider-managed resource list. If importLocation or importAlias is defined, Speakeasy adds them to the import list at the top of the provider file. The value of resource is arbitrary text, and could contain a function invocation if desired.

The additionalEphemeralResources key follows the same syntax, but inserts ephemeral resources into the provider.

The additionalDataSources key follows the same syntax, but inserts data resources into the provider using datasource (instead of resource) as the value inserted into the list.

To learn more about how to write a Terraform resource, please consult the official Terraform documentation .