Mapping Entities

Brandon Croft,•apiterraform

This is part of a series of notes about code generating a Terraform Provider using OpenAPI

There are many details to remember when implementing attribute mapping and I need to keep track of them in this notebook. Three types of attribute entities that we have to consider:

The Terraform Resource Entity

These attributes ultimately define how the terraform state is shaped and we have to remember some important facets:

  1. It should be easy to know when a Terraform attribute is required: It will be required on the POST create request.

  2. These attributes can match exactly the API attributes in all their forms, but they can also simplify them or omit them. It's not adequate to use the same model to represent both the HTTP request attributes, the HTTP response attributes, and the Terraform resource.

  3. The "ForceNew" and "Computed" schema behavior needs to be bound by configuration. There's really no way to know from OpenAPI if a particular attribute should exhibit these behaviors and it's important for many APIs. If this is true, it probably means that all resource attributes need to be rebindable in the tfpgen.yml config.

The Request Parameters

These attributes must be defined in the query, path, header, or cookie. State values should flow into these based on their name OR a user-defined binding override.

  1. Required attributes are not always marked as required in OpenAPI. For example, a path parameter is probably always required but spec authors still have to manually set required: true and often don't. Another reason why it's important to allow users to define a Terraform <-> Request binding in configuration.

  2. From the spec: If "in" is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.

  3. If "in" is "path", the name will correspond to the parameter path template name. For example, '/policies/{policyID}/stuff' should contain a request parameter called 'policyID' that also is defined as "in" "path"

The Response

These attributes should take a priority when setting Terraform state. Most often, Terraform providers will read a resource as soon as it performs a write operation in order to refresh the state model to it's most accurate form, or because the response of create/update endpoints can be empty or vary.

Note to myself: What I mean by "priority" needs to be explored.

© Brandon Croft.