tf-libsonnet/libgenerator is a code generator for Jsonnet Terraform libraries.
This binary generates the library source code using the schema definitions for resources and data sources provided by
the provider binaries (from the terraform providers schema command).
The list of supported providers as well as the destination repositories can be found in the cfg/managed.json config file.
Learn more about tf.libsonnet at docs.tflibsonnet.com.
If you are managing a new custom provider, or would like to tweak the generated output, you can run the binary directly to generate the libsonnet files on your local filesystem.
Compiled binaries for various platforms are available in the releases
page. Make sure to put it somewhere on your PATH, such as
/usr/local/bin.
You can also compile from source using go install if you have Go 1.19+ installed. E.g., to
get the latest version:
go install github.com/tf-libsonnet/libgenerator/cmd/libgenerator@latest
Once you have installed the binary, you can generate the libsonnet for a provider by passing in the desired provider
parameters with the --provider flag. For example, if you want to generate the libsonnet for the Doppler
provider:
libgenerator gen --provider 'src=DopplerHQ/doppler&version=~>1.0'
This will generate the libsonnet files in the out directory of the current working directory. You can then copy the
results into a repo you maintain, or as a vendored file in your main infrastructure repo where you are generating
Terraform code (e.g., infrastructure-live).
Due to limited bandwidth, we do not default to generating and maintaining a library for all providers. However, we are open to supporting any providers that will get active usage from the community.
You can request a new provider to be managed by the tf.libsonnet org by opening a pull request with the provider added
to the cfg/managed.json config. During the PR process, we will allocate a new repository to house
the generated code and run the generator through the CI job to generate the new library. From there, you can test the
generated code to verify the changes.
While the generator is capable of generating libsonnet code for arbitrary providers, it is difficult to maintain and test compatibility for all of them over time. This means that we can't guarantee that the generated code will work for all production environments and use cases, nor that all functions on resources and data sources work as intended. However, certain providers see active production usage from the community, and these providers are generally considered to be stable.
We define the following stability levels for the generated provider libraries:
- Stable: Actively used in production workloads. The target repository contains regression tests to maintain compatibility across versions and releases. Issues relating to these providers have the highest priority.
- Beta: Actively used in production workloads, but there is no regression testing. Issues relating to these providers will be prioritized.
- Alpha: While automated releases are configured, there is no known active production usage. Issues relating to these providers are addressed on a best effort basis.
The following table clarifies the current status of the providers according to the aforementioned stability levels:
| Provider | Status |
|---|---|
| azurerm | Beta |
| azuread | Beta |
| hcp | Beta |
| null | Beta |
| DopplerHQ/doppler | Beta |
| aws | Alpha |
| Alpha | |
| google-beta | Alpha |
Note that the stability levels within a provider library will vary across resources and data sources. That is, some resources within a provider may be considered Alpha level, while others may be Stable. In general, a Stable provider has a large enough community of users such that most resources and data sources are covered.
If you have any questions about how to use the tf.libsonnet libraries, ask in the Organization GitHub
Discussion.
Refer to the CONTRIBUTING.md document for information on how to contribute to tf.libsonnet.