Framework Code Generator
Note
Code Generation is currently in tech preview.The Framework Code Generator is a CLI tool that generates Terraform Plugin Framework code from a provider code specification. This section contains usage documentation and examples for using the generator.
Overview
The Framework Code Generator has two commands: generate
and scaffold
.
The primary command is generate
, which receives a Provider Code Specification as input and creates Terraform Plugin Framework Go code as output. These generated Go files will have a suffix of _gen.go
and are marked with a "DO NOT EDIT" comment at the top of each file.
The scaffold
command creates Terraform Plugin Framework Go code from pre-defined templates. These Go files are not marked as generated code and are intended to be edited by the provider developer after running the command.
Usage
Installation
The CLI tool can be installed with the Go toolchain, via go install
:
Generate command
Note
Currently, the Framework Code Generator creates Plugin Framework schemas and helper functions for nested attributes.The generate
command uses a specification as input and generates Terraform Provider code as output.
For example:
More detailed examples of input/output can be found in the Examples.
Subcommands
The specification defines the schema for the provider, data sources, and resources.
A subcommand is required to inform the generate
command whether to generate code for all data sources, resources and the provider, or whether to specifically generate code for only data sources, or resources or the provider.
The subcommands that are available are all
, data-sources
, provider
and resources
.
Flags
The available flags for the generate <all|data-sources|provider|resources>
command:
Flag | Required? | Default | Description |
---|---|---|---|
input | No | Uses stdin as input | String path of a file containing the specification |
output | No | ./output | String path of the destination directory for the generated code |
package | No | A package will be generated per data source, provider, and resource | String that represents a single Go package name to be used for all generated code |
If the input
flag is not supplied then the generate
command requires that the specification is provided through stdin
, for example by piping into the generate
command (e.g., cat provider_code_spec.json | tfplugingen-framework generate all ...
).
Scaffold command
The scaffold
command generates starter code for a data source, provider, or resource.
For example:
Subcommands
A subcommand is required to inform the scaffold
command whether to generate starter code for a data source, provider, or resource.
The subcommands that are available are data-source
, provider
and resource
.
Flags
The available flags for the scaffold <data-source|provider|resource>
command:
Flag | Required? | Default | Description |
---|---|---|---|
name | Yes | String name of data source, provider, or resource in snake_case; without the provider type prefix. | |
force | No | If present, forces recreation overwriting preexisting file. | |
output-dir | No | Current working directory | String path to destination directory for the scaffolded code file. |
output-file | No | Uses name flag with suffix _<data_source/provider/resource>.go | String file name and extension for the scaffolded code file. |
package | No | provider | String representing the Go package name to be used for the scaffolded code file. |
Example
Executing this command generates the following scaffold code in ./output/scaffold/data_source/example_data_source.go
:
Examples
The following sections detail how Provider Code Specification map to Plugin Framework code for the generate
command.
Primitive Attributes
The primitive attributes BoolAttribute
, Float64Attribute
, Int64Attribute
, NumberAttribute
and StringAttribute
are defined using the bool
, float64
, int64
, number
and string
types, respectively in the specification.
For example:
Using this specification with the following generate command:
Creates the following Go code in output/datasource_example/example_data_source_gen.go
:
Collection Attributes
The collection attributes ListAttribute
, MapAttribute
, and SetAttribute
are defined using the list
, map
, and set
types, respectively in the specification.
For example:
Using this specification with the following generate command:
Creates the following Go code in output/datasource_example/example_data_source_gen.go
:
Object Attributes
The ObjectAttribute
is defined using the object
type in the specification.
For example:
Using this specification with the following generate command:
Creates the following Go code in output/datasource_example/example_data_source_gen.go
:
Nested Attributes
The nested attributes ListNestedAttribute
, MapNestedAttribute
, SetNestedAttribute
, and SingleNestedAttribute
are defined using the list_nested
, map_nested
, set_nested
, and single_nested
types, respectively in the specification.
For example:
Using this specification with the following generate command:
Creates the following schema and model Go code in output/datasource_example/example_data_source_gen.go
:
For nested attributes, the ObjectTypable type that is used as the CustomType within the schema is also generated along with the corresponding ObjectValuable type.
For List, Map, and Set nested attributes, the ObjectTypable type is assigned to the CustomType field of the NestedObject field.
For Single nested attributes, the ObjectTypable type is assigned directly to the CustomType field.
Developing Custom Types provides details concerning the methods that need to be overridden for custom types, but the generated code provides a full implementation of all methods.
The generator outputs the following for ListNestedAttributeType
type:
The generator outputs the following for ListNestedAttributeValue
type:
Nested Blocks
The nested blocks ListNestedBlock
, SetNestedBlock
, and SingleNestedBlock
are defined using the list_nested
, set_nested
, and single_nested
types, respectively in the specification.
For example:
Using this specification with the following generate command:
Creates the following schema and model Go code in output/datasource_example/example_data_source_gen.go
:
For nested blocks, the ObjectTypable type that is used as the CustomType within the schema is also generated along with the corresponding ObjectValuable type.
For List, and Set nested blockss, the ObjectTypable type is assigned to the CustomType field of the NestedObject field.
For Single nested blocks, the ObjectTypable type is assigned directly to the CustomType field.
Developing Custom Types provides details concerning the methods that need to be overridden for custom types, but the generated code provides a full implementation of all methods.
The generator outputs the following for SingleNestedBlockType
type:
The generator outputs the following for SingleNestedBlockValue
type: