-
Each resource (and associated data sources) is in a package in
internal/service
. -
There can be multiple helper files and they can also be used from other resources, e.g.
common_advanced_cluster.go
defines functions that are also used from other resources usingadvancedcluster.FunctionName
.
A set of commands have been defined with the intention of speeding up development process, while also preserving common conventions throughout our codebase.
This command can be used the following way:
make scaffold resource_name=streamInstance type=resource
- resource_name: The name of the resource, which must be defined in camel case.
- type: Describes the type of resource being created. There are 3 different types:
resource
,data-source
,plural-data-source
.
This will generate resource/data source files and accompanying test files needed for starting the development, and will contain multiple comments with TODO:
statements which give guidance for the development.
As a follow up step, use Scaffolding Schema and Model Definitions to autogenerate the schema via the Open API specification. This will require making adjustments to the generated ./internal/service/<resource_name>/tfplugingen/generator_config.yml
file.
The generation command makes use of a configuration file defined under ./tools/codegen/config.yml
. The structure of this configuration file can be found under ./tools/codegen/config/config_model.go
.
The generation command takes a single optional argument resource_name
. If not provided, all resources defined in the configuration are generated.
make generate-schema resource_name=search_deployment
As a result, content of schemas will be written into the corresponding resource packages:
./internal/service/<resource-package>/resource_schema.go
Note: Data source schema generation is currently not supported.
Complementary to the scaffold
command, there is a command which generates the initial Terraform schema definition and associated Go types for a resource or data source. This processes leverages Code Generation Tools developed by HashiCorp, which in turn make use of the Atlas Admin API OpenAPI Specification.
Both tfplugingen-openapi
and tfplugingen-framework
must be installed. This can be done by running make tools
.
The command takes a single argument which specifies the resource or data source where the code generation is run, defined in camel case, e.g.:
make scaffold-schemas resource_name=streamInstance
As a pre-requiste, the relevant resource/data source directory must define a configuration file in the path ./internal/service/<resource_name>/tfplugingen/generator_config.yml
. The content of this file will define which resource and/or data source schemas will be generated by providing the API endpoints they are mapped to. See the Generator Config documentation for more information on configuration options. An example defined in our repository can be found in searchdeployment/tfplugingen/generator_config.yml.
As a result of the execution, the schema definitions and associated model types will be defined in separate files depending on the resources and data sources that were configured in the generator_config.yml file:
data_source_<resource_name>_schema.go
resource_<resource_name>_schema.go
Note: if the resulting file paths already exist the content will be stored in files with a _gen.go
postfix, and in this case any content will be overwritten. This can be useful for comparing the latest autogenerated schema against the existing implementation.
Note: you can override the Open API description of a field with a custom description via the overrides param. See this example.
- Generated Go type should include a TF prefix to follow the convention in our codebase, this will not be present in generated code.
- Some attribute names may need to be adjusted if there is a difference in how they are named in Terraform vs the API. An examples of this is
group_id
→project_id
. - Inferred characteristics of an attribute (computed, optional, required) may not always be an accurate representation and should be revised. Details of inference logic can be found in OAS Types to Provider Attributes.
- Missing sensitive field in attributes.
- Missing plan modifiers such as
RequiresReplace()
in attributes. - Terraform specific attributes such as timeouts need to be included manually.
- If nested attributes are defined a set of helper functions are generated for using the model. The usage of the generated functions can be considered optional as the current documentation is not very clear on the usage (More details in terraform-plugin-codegen-framework/issues/80).