development-best-practices.md

Development Best Practices

Table of Contents

• Creating New Resource and Data Sources

  • Scaffolding Initial Code and File Structure
  • Scaffolding Schema and Model Definitions

• 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 using advancedcluster.FunctionName.

Creating New Resource and Data Sources

A set of commands have been defined with the intention of speeding up development process, while also preserving common conventions throughout our codebase.

Scaffolding Initial Code and File Structure

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.

Scaffolding Schema and Model Definitions

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.

Running the command

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.

Considerations over generated schema and types

• 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).