Changelog #14: Terraform Generation Alpha
Changes to the Speakeasy platform - December 21, 2022.
If you are interested in being an alpha user for our Terraform provider generator, please respond to this email to let us know!
Github’s 2022 annual review crowned HCL (hashicorp configuration language) as the fastest growing language (56%), even beating out developer darling, Rust, for the top spot. It is a testament to the establishment of infrastructure as code (IaC) as a leading development practice and the popularity of Terraform as the medium for infrastructure management.
The best developer companies meet their users where they already are, to flatten the learning curve and provide a great DevEx. For some API companies that increasingly means a terraform provider so that the resources exposed by the API can be managed in concert with any related infrastructure. However, like SDKs, a terraform provider becomes another artifact that needs ongoing investment & management. That’s why we’ve been working on a way to enable teams to auto-generate terraform providers from their OpenAPI definition.
Alpha Release
Terraform Provider Generation - Just add annotations to your OpenAPI specification’s entities and operations. Speakeasy will then process your spec to produce and maintain a terraform-registry compliant provider plugin, that will create, update and destroy persistent resources by interacting with your APIs. As an example, imagine the pet entity from the canonical petshop example:
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#createx-speakeasy-entity-operation: Pet#deletex-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" }}
Speakeasy will output this provider plugin to a github repository, annotating resources with Computed, ReadOnly, Required and ForceNew attributes based upon the semantics of how they’re used in Create/Update operations.
If you would like us to generate a terraform provider from your OpenAPI definition, please get in touch! We’re actively looking for design partners for whom we can generate/maintain terraform providers for your API.
New Features
SDK Retries - Every SDK should have retries. It’s one of the things that makes for a great DevEx. End-users shouldn’t be left to figure out what errors should trigger retries, which shouldn’t, and how long you should wait before resending. Nobody knows an API better than the builder, and that’s who should be determining when a retry is appropriate. That’s why we’ve added the ability for our users to extend their OpenAPI spec and configure retry logic for their SDKs.
x-speakeasy-retries: strategy: backoff backoff: initialInterval: 100 # 100 ms maxInterval: 30000 # 30s exponent: 2 # backoff delay doubles from 100ms until 30s maxElapsedTime: 300000 # After 5 minutes, returns a failure to the callee statusCodes: # a list of status codes to retry on (supports XX wildcards) - 429 - 5XX retryConnectionErrors: true # whether to retry connection errors
