generate-terraform-provider

Files (2)

• SKILL.md
• customization.md · content/

SKILL.md (first lines)

# generate-terraform-provider

Generate a Terraform provider from an OpenAPI specification using the Speakeasy CLI. This skill covers the full lifecycle: annotating your spec with entity metadata, mapping CRUD operations, generating the provider, configuring workflows, and publishing to the Terraform Registry.

## Content Guides

| Topic | Guide |
|-------|-------|
| Advanced Customization | [content/customization.md](content/customization.md) |

The customization guide covers entity mapping placement, multi-operation resources, async polling, property customization, plan modification, validation, and state upgraders.

## When to Use

- Generating a new Terraform provider from an OpenAPI spec
- Annotating an OpenAPI spec with `x-speakeasy-entity` and `x-speakeasy-entity-operation`
- Mapping API operations to Terraform CRUD methods
- Understanding Terraform type inference from OpenAPI schemas
- Configuring `workflow.yaml` for Terraform provider generation
- Publishing a provider to the Terraform Registry
- User says: "terraform provider", "generate terraform", "create terraform provider", "CRUD mapping", "x-speakeasy-entity", "terraform resource", "terraform registry"

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| OpenAPI spec | Yes | OpenAPI 3.0 or 3.1 specification (local file, URL, or registry source) |
| Provider name | Yes | PascalCase name for the provider (e.g., `Petstore`) |
| Package name | Yes | Lowercase package identifier (e.g., `petstore`) |
| Entity annotations | Yes | `x-speakeasy-entity` on schemas, `x-speakeasy-entity-operation` on operations |

## Outputs

| Output | Location |
|--------|----------|
| Workflow config | `.speakeasy/workflow.yaml` |
| Generation config | `gen.yaml` |
| Generated Go provider | Output directory (default: current dir) |
| Terraform examples | `examples/` directory |

## Prerequisites

1. **Speakeasy CLI** installed and authenticated
2. **OpenAPI 3.0 or 3.1** specification with entity annotations
3. **Go** installed (Terraform providers are written in Go)
4. **Authentication**: Set `SPEAKEASY_API_KEY` env var or run `speakeasy auth login`

```bash
export SPEAKEASY_API_KEY="<your-api-key>"
```

Run `speakeasy auth login` to authenticate interactively, or set the `SPEAKEASY_API_KEY` environment variable.

## Command

### First-time generation (quickstart)

```bash
speakeasy quickstart --skip-interactive --output console \
  -s <spec-path> \
  -t terraform \
  -n <ProviderName> \
  -p <package-name>
```

### Regenerate after changes

```bash
speakeasy run --output console
```

### Regenerate a specific target

```bash
speakeasy run -t <target-name> --output console
```

## Entity Annotations

Before generating, annotate your OpenAPI spec with two extensions:

### 1. Mark schemas as entities

Add `x-speakeasy-entity` to component schemas that should become Terraform resources:

```yaml
components:
  schemas:
    Pet:
      x-speakeasy-entity: Pet
      type: object
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
        price:
          type: number
      required:
        - name
        - price
```

### 2. Map operations to CRUD methods

Add `x-speakeasy-entity-operation` to each API operation:

```yaml
paths:
  /pets:
    post:
      x-speakeasy-entity-operation: Pet#create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"

From speakeasy-api/sdk-generation-skills, Apache-2.0.

More from speakeasy-api/sdk-generation-skills