Create Your Terraform Provider from OpenAPI / Swagger

What Is a Terraform Provider?

Terraform is a popular infrastructure-as-code tool that allows developers to manage cloud infrastructure through declarative configuration files. Terraform works by making API calls to different services, documented in providers, to fulfill a "plan" to take an existing cloud infrastructure state to an intended specification. For example, the AWS provider allows users to access the full range of the Amazon API within their infrastructure code, allowing for easy management of AWS resources.

If you have an API and your API manages durable entities (such as Service Configuration), and you expect the people using your API to be software engineering teams, then a provider is essential for a good developer experience. Whether or not you have a provider will affect purchasing decisions, especially if your API service is considered "infrastructure" for your customers or your customers have multiple environments with complex configurations.

Why Should You Use OpenAPI for Your Terraform Provider?

While Terraform providers offer many benefits, building and maintaining them can be a challenging task. The biggest issues that companies face when building Terraform providers are:

  1. Technical resources are hard to find. Providers are written in Go, which not every company has expertise in.
  2. Maintaining providers is a burden. With every API update, you need to make sure that the updates are propagated to the provider.

This is where OpenAPI comes in. OpenAPI is the industry standard for defining your API. Most developers are familiar with the format and updating OpenAPI specs is already part of most API teams' processes. Many server frameworks will generate OpenAPI specs for you from your existing server code without additional effort.

With Speakeasy, you can now derive your Terraform provider directly from your OpenAPI spec. This eliminates the need for domain expertise and ensures that your provider stays up to date with your API definition.

Create a Terraform Provider with Speakeasy

To get started with the Speakeasy Terraform creation, you will need an API spec. See below for the Speakeasy-supported formats:

Spec FormatSupported
OpenAPI 3.0
OpenAPI 3.1
JSON Schema
Postman Collection🔜
Success Icon


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

In addition to a spec, you'll also need access to the Speakeasy platform. If you don't yet have access, you can join our beta here (opens in a new tab).

graphic showing how terraform creation works with Speakeasy

How It Works: Adding Annotations

To create your Terraform provider, you'll start with your OpenAPI spec as input. Terraform providers are composed of entities, which are the objects that users will configure. Every entity has a set of methods that define how these entities can be created, updated, downloaded, and destroyed through API requests.

The framework of entity and methods is similar to an API definition (with objects and endpoints), but not every endpoint in your API definition will need to be included in the Terraform provider. You can add annotations to your OpenAPI spec to specify which objects represent entity and which endpoints represent each entity's associated methods.

Here's a basic example of an OpenAPI spec with annotations:

- pet
summary: Add a new pet to the store
x-speakeasy-entity-operation: Pet#create
description: Add a new pet to the store
operationId: addPet
description: Successful operation
$ref: '#/components/schemas/Pet'
description: Create a new pet in the store
required: true
$ref: '#/components/schemas/Pet'
x-speakeasy-entity: Pet
- name
- photoUrls
type: integer
format: int64
example: 10
type: string
$ref: '#/components/schemas/Category'
type: array
type: string

Add the x-speakeasy-entity annotation to a resource-based API with annotations to each operation, such as:

  • x-speakeasy-entity-operation: Pet#create
  • x-speakeasy-entity-operation: Pet#delete
  • x-speakeasy-entity-operation: Pet#update

This is all that is required to generate a valid Terraform provider with Terraform Registry documentation, which you can use as follows:

resource "petstore_pet" "myPet" {
name = "Freddie"
photo_urls = [""]
tags = {
name = "foo"

In the next section, we will walk through a more complex example using the canonical Hashicups example (opens in a new tab).

Hashicups Example

Our Hashicups repo (opens in a new tab) contains a full example of a Terraform provider created using Speakeasy. In the Loom video above, a Speakeasy engineer walks you through how to appropriately annotate the Hashicup OpenAPI spec (opens in a new tab) to create a functional provider.