Introduction

What are Terraform Providers & Why do they matter?

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 Amazon's API within their infrastructure code. This allows for easy management of their 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. The existence (or lack there-of) will affect purchasing decisions, especially when you want your API Service to be considered "infrastructure" for your customers, or when they have multiple environments with complex configuration.

Why Should You Use OpenAPI?

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 team's process. 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.

What You'll Need

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

Spec Format	Supported
OpenAPI 3.0	✅
OpenAPI 3.1	✅
JSON Schema	✅
Postman Collection	🔜

tip

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

• Swagger2.0 -> OpenAPI3.0
• Postman -> OpenAPI3.0

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.

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, and every entity has a set of methods which define how these entities can be Created, Updated, Downloaded, and Destroyed through API requests.

The framework of entity and methods is not dissimilar 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 will therefore add annotations to your OpenAPI spec in order to specify which objects represent entity, and which endpoints represent it's associated methods.

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

paths:
 /pet:
   post:
     tags:
       - 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
     responses:
       '200':
         description: Successful operation
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Pet'
     requestBody:
       description: Create a new pet in the store
       required: true
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Pet'
…
Pet:
 x-speakeasy-entity: Pet
 required:
   - name
   - photoUrls
 properties:
   id:
     type: integer
     format: int64
     example: 10
   name:
     type: string
   category:
     $ref: '#/components/schemas/Category'
   photoUrls:
     type: array
     items:
       type: string
…

Adding the x-speakeasy-entity annotation to a resource-based API, along 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

are all that’s required to generate a valid terraform provider with terraform-registry documentation, usable like the following:

resource "petstore_pet" "myPet" {
 name = "Freddie"
 photo_urls = ["https://example.com/example.jpg"]
 tags = {
   name = "foo"
 }
}

In the next section we will walk through a much more complex example using the canonical Hashicups example.

Hashicups Example

Our Hashicups repo 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 in order to create a functional provider.