Create Your Terraform Provider

What Are Terraform Providers and 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 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?

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.

What You'll Need

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

TIP

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

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

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).

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:

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
…

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 = ["https://example.com/example.jpg"]
 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.