Create Your Terraform Provider From OpenAPI / Swagger

Introduction

Terraform is an infrastructure-as-code tool that uses providers to manage cloud infrastructure via API calls. Creating and maintaining these providers, typically written in Go, can be challenging due to the need for specialized skills and continuous updates with API changes.

Speakeasy offers a streamlined solution by generating Terraform providers directly from OpenAPI specifications. This approach minimizes the need for Go expertise, ensures providers are consistently updated, and simplifies the development and maintenance of Terraform providers for complex cloud environments.

What Does Speakeasy Generate?

Using the Terraform Plugin Framework (opens in a new tab), Speakeasy generates a fully functional Terraform provider from an annotated (opens in a new tab) OpenAPI spec.

What Does Speakeasy Support?

Speakeasy follows OpenAPI semantics when generating a provider. In most simple CRUD APIs, very few annotations are required on your OpenAPI specifications, with all of the following inferred from the specification.

What Are the Limitations of Speakeasy Terraform Provider Generation?

Speakeasy covers a wide range of OpenAPI features and we're constantly working to support more. The following outlines the current limitations of our Terraform provider generation product:

Note: Circular References

The Terraform Type schema must be a directed acyclic graph. OpenAPI's use of JSON Schema allows for circular references to be defined. When Speakeasy detects a circular reference, it will output an error and instructions for a few workarounds.

To prevent errors due to circular references, apply x-speakeasy-type-override: any to the attribute causing the circular reference, and the attribute will be inferred as a string that satisfies JSON. A Terraform user can then use the jsonencode function to pass arbitrary data into the attribute.

Terraform Framework Types From JSON Schema Types

Attribute types are inferred, with one exception (see below).

1. Prerequisites

To get started with the Speakeasy Terraform-provider creation, you will need:

• Speakeasy CLI
• An API spec in a supported format:

TIP

If you are using an unsupported spec format, some tools can help you convert to a supported format:

• Swagger2.0 -> OpenAPI v3.0 (opens in a new tab)
• Postman -> OpenAPI v3.0 (opens in a new tab)

2. Add Annotations

Annotate objects representing Terraform entities with x-speakeasy-entity. This determines their inclusion in the Terraform provider.

Terraform Usage:

Speakeasy infers Terraform types from your JSON schema, focusing on the semantics of CREATE and UPDATE requests and responses. You should not need to define any specific Terraform types in your OpenAPI spec.

1. Required vs. Optional: A property is marked as Required: true if it's required in the CREATE request body; otherwise, it's Optional: true.
2. Computed Properties: Properties that appear in a response body but are absent from the CREATE request are marked as Computed: true. This indicates that Terraform will compute the properties' values.
3. The ForceNew Property: If a property exists in the CREATE request but is not present in the UPDATE request, it's labeled ForceNew.
4. Enum Validation: When an attribute is defined as an enum, Speakeasy configures a Validator for runtime type checks. This ensures that all request properties precisely match one of the enumerated values.
5. READ, UPDATE, and DELETE Dependencies: Every parameter essential for READ, UPDATE, or DELETE operations must either be part of the CREATE API response body or be consistently required in the CREATE API request. This ensures that all necessary parameters are available for these operations.

TIP

Use additional x-speakeasy annotations to customize your provider as necessary.

4. Enhance Generated Documentation

Speakeasy helps you autogenerate documentation using the HashiCorp terraform-plugin-docs. For best results, we recommend:

1. Include Descriptions: Ensure your OpenAPI spec contains detailed descriptions of resources, attributes, and operations. Clear and concise descriptions help users understand the purpose and use of each component.
2. Provide Examples: Use examples in your OpenAPI spec to illustrate how resources and attributes should be configured. Speakeasy leverages these examples to generate usage snippets that users can refer to when starting with your provider.

The Swagger Pet Store would generate a usage snippet for the pet resource like the following:

5. Generate Terraform

• Run the Speakeasy generate command:

Frequently Asked Questions

Do generated Terraform providers support the ability to import resources?

Yes, generated Terraform providers do support the ability to import resources. However, there are specific prerequisites and considerations to keep in mind:

Prerequisites

1. API Specification: It is essential to have an annotated and type-complete API operation defined for reading each resource in the OpenAPI specification. Tag the operation with x-speakeasy-entity-operation: MyEntity#read.

2. Single Resource ID: Speakeasy can currently only generate import logic for resources that can be read using a single ID-like attribute. An ID-like attribute is any required attribute in the READ API request.

3. Comprehensive READ Operation: If any attribute of a resource is not defined in the READ API, Terraform will set that attribute to null during the import process.

Handling Composite Keys

Speakeasy doesn't natively support direct import for resources with multiple ID fields. To work around this, serialize composite keys into a single ID field and override the implementation by parsing the import-ID request.

Composite Key Format: "<sourceId>,<workspaceID>"