Terraform Provider for SELECT - Development

This repository contains the source code for the SELECT Terraform Provider. This provider is mostly auto-generated from SELECT's public OpenAPI specification, enabling developers to manage SELECT platform resources through Terraform.

For usage documentation and examples, visit the official Terraform Registry documentation.

About SELECT

SELECT helps organizations optimize their Snowflake usage and costs. This Terraform provider enables Infrastructure as Code management of SELECT platform resources like usage groups and usage group sets.

Architecture Overview

This provider is built using:

• Terraform Plugin Framework - Modern Terraform provider development
• tfplugingen-openapi - OpenAPI to Terraform schema generation
• tfplugingen-framework - Framework code generation
• SELECT's Public OpenAPI Spec - Single source of truth hosted at https://api.select.dev/public_openapi

Code Generation Workflow

The provider code is generated from SELECT's public OpenAPI specification:

1. Fetch OpenAPI Spec: Downloads the latest spec from https://api.select.dev/public_openapi
2. Generate Schema: tfplugingen-openapi converts OpenAPI spec to Terraform schema definitions
3. Generate Code: tfplugingen-framework creates the final provider code
4. Manual Customization: Configuration in generator_config.yml allows for customizations and overrides

This ensures the provider stays in sync with SELECT's API automatically.

Development Requirements

• Go >= 1.24.4
• Terraform >= 1.7.0

Required Tools

The following tools are automatically installed during the build process:

# These are installed automatically by the Makefile
go install github.com/hashicorp/terraform-plugin-codegen-openapi/cmd/tfplugingen-openapi@latest
go install github.com/hashicorp/terraform-plugin-codegen-framework/cmd/tfplugingen-framework@latest

Quick Start

# Clone the repository
git clone https://github.com/get-select/terraform-provider-select
cd terraform-provider-select

# Generate provider code from OpenAPI spec and build
make reset

# Set up local development
make setup-dev-overrides

Development Commands

Command	Description
make help	Show all available commands
make codegen	Download OpenAPI spec and generate provider code
make build	Build the provider binary
make install	Install provider locally for testing
make setup-dev-overrides	Configure Terraform to use local provider
make test	Run provider tests
make clean	Remove all generated files and build artifacts
make reset	Full reset: clean, regenerate, and install

Development Workflow

1. Initial Setup:

   make reset                    # Generate code and build
   make setup-dev-overrides     # Configure local development overrides

2. Making Changes:

   # After modifying generator_config.yml or when API updates:
   make reset
   
   # For code-only changes (if manually editing generated code):
   make build install

Types from the API spec are added to internal/provider/. Some boilerplate is then needed to connect those types to the Api in a way that terraform understands. There is one of these per resource in internal/.

3. Testing:

Testign requires and API key and organization generated from teh SELECT backend you wish to test against. You can generate an API key in Settings -> API Keys and you can find your organization id in Settings -> Profile.

# Set required environment variables
export TF_VAR_select_api_key="your-api-key"
export TF_VAR_select_organization_id="your-org-id"

# Run tests
make test

Configuration Files

generator_config.yml

Configures the code generation process:

• Resource mappings (API endpoints to Terraform resources)
• Schema overrides and customizations
• Field descriptions and validation rules
• Ignored fields that don't map well to Terraform

example.terraformrc

Template for Terraform development overrides that allows using the locally built provider instead of downloading from the registry.

Project Structure

terraform-provider-select/
├── internal/                    # Hand-written provider core
│   ├── provider.go             # Provider configuration and setup
│   ├── api.go                  # HTTP client and API utilities
│   ├── usage_group_resource.go # Custom resource implementations
│   └── provider/               # Generated code (git-ignored)
├── tests/                      # Provider tests
├── docs/                       # Generated documentation
├── examples/                   # Usage examples
├── generator_config.yml        # Code generation configuration
├── Makefile                    # Development commands
└── main.go                     # Provider entry point

OpenAPI Dependency

Important: This provider is entirely dependent on SELECT's public OpenAPI specification. The specification is:

• Hosted at: https://api.select.dev/public_openapi
• Auto-fetched: Every make codegen downloads the latest spec
• Single Source of Truth: Changes to the API automatically reflect in the provider

If the OpenAPI endpoint is unavailable, the code generation will fail. For offline development, you can work with a previously downloaded openapi.public.json file.

Testing

The provider includes comprehensive tests that validate functionality against the live SELECT API:

# Run all tests
make test

# Run specific test files  
cd tests && terraform test provider.tftest.hcl

# Run specific test cases
cd tests && terraform test provider.tftest.hcl -filter=create_usage_group_set

Note: Tests require valid SELECT API credentials and will create/modify real resources.

Documentation Generation

Some documentation is semi auto-generated from the provider schema. Field descriptions are pulled from the Open API spec and should be changed in the backends endpoint metadata. Other parts of the documentation are maintained in templates/

make docs

This creates documentation in the docs/ directory that matches the format used in the Terraform Registry.

You can use this tool to preview a document file before releasing it https://registry.terraform.io/tools/doc-preview

Release Process

Releases are automated via GitHub Actions when tags are pushed, you can also create a new release via the github UI by creating a release with a new tag that objects the Semantic Versioning format, for example: v1.2.3.

1. Code is generated from the latest OpenAPI spec
2. Provider is built for multiple platforms
3. Binaries are signed and uploaded to GitHub releases
4. Terraform Registry is automatically updated

Contributing

1. Fork the repository
2. Create a feature branch from main
3. Make your changes to generator_config.yml or core provider files
4. Test your changes with make test
5. Submit a pull request

Common Development Tasks

Adding a new resource:

1. Update generator_config.yml with the new resource configuration
2. Run make reset to regenerate code
3. Add any custom logic in internal/
4. Add tests in tests/

Modifying existing resources:

1. Update the relevant section in generator_config.yml
2. Run make reset
3. Test changes with make test

Troubleshooting

"Provider not found" errors:

make setup-dev-overrides  # Ensure dev overrides are configured

Code generation failures:

# Check internet connection and try again
make clean && make codegen

Test failures:

# Ensure credentials are set
export TF_VAR_select_api_key="your-key"
export TF_VAR_select_organization_id="your-org-id"

# Clean test state
make test-clean && make test

Links

• Terraform Registry - Official provider documentation and usage examples
• SELECT Platform - SELECT platform documentation
• Provider Issues - Report bugs or request features
• Terraform Plugin Framework - Framework documentation

License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.