tofu-api
v0.6 · earlyAny OpenTofu or Terraform provider, as a REST API.
tofu-api runs an OpenTofu or Terraform provider over the plugin protocol — without HCL, plan or state file — and generates the OpenAPI contract from its schemas. What is left to write is what is specific to your platform, in one YAML file per provider.
The problem
Why tofu-api
- An internal API in front of a product is mostly a client of that product’s API — and writing, then maintaining, that client is most of the work.
- A Terraform provider is that client, already written: maintained by the vendor or its community, tested daily by everyone who manages that product with Terraform.
- tofu-api gives callers that are not Terraform — a portal, a script, another service — a plain REST API on top of it.
No code per resource
The contract comes from the provider’s schemas. Bumping the provider and regenerating it is the API change.
Rules in YAML
Values the service sets, defaults, patterns, enums and hidden attributes, with CEL expressions.
Credentials per namespace
A provider process per namespace, configured from Vault, so a tenant reaches only what its credentials allow.
Contract enforced
Requests that do not match are a 400 before the provider is called. Errors are RFC 9457 problems.
Documentation
Find your way around
Getting started
Run tofu-api with the Foreman example to generate the contract, serve the API and call it with curl.
Install
Install tofu-api from release packages, lay out its files under /etc/tofu-api and install providers from a network mirror.
Configuration
The YAML file per provider, with the binary to run, its configuration, the resource types to expose and the rules over them.
Authentication
Bearer tokens checked by an authentication service, and RBAC decisions per verb, resource type and namespace.
Namespaces
The path's namespace, and a provider process per namespace configured with the namespace's own credentials from Vault.
Data sources
Expose provider data sources read only, with GET on their path and their arguments in the query.
Rules
Rules over the provider's schemas, error rules mapping provider failures to HTTP errors, and CEL expressions.
Mapping
How provider schema attributes map to the request and response schemas, and how resources are rebuilt from their id.
Operations
Inspecting the namespaces' provider processes and metrics, and how concurrent requests reach the provider.
Limits
Known limits of tofu-api, from inferred replacements to provider retries, and what it does not cover.
Testing
What tofu-api was tested with live, with the random provider, Grafana 13.3.0 and 11.3, namespaces with Vault and error rules.
Status
At a glance
Contribute to tofu-api
Issues, ideas and pull requests are welcome on GitHub.