hanzo-terraform

The Hanzo Terraform Provider is a generated Terraform SDK for managing Hanzo AI resources via Infrastructure as Code.

Hanzo Terraform Provider - Infrastructure as Code for Hanzo AI

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-operator.md, hanzo/go-sdk.md

Overview

The Hanzo Terraform Provider is a generated Terraform SDK for managing Hanzo AI resources via Infrastructure as Code. Built on the HashiCorp Terraform Plugin Framework, it wraps the Hanzo Go SDK (github.com/hanzoai/go-sdk) to provide declarative resource management through Terraform. Currently in early alpha with provider scaffolding and authentication -- resources and data sources are being generated from the Hanzo OpenAPI spec.

Why Hanzo Terraform Provider?

Generated: Auto-generated from the Hanzo OpenAPI spec -- stays in sync with the API
Terraform Plugin Framework: Modern provider architecture (not legacy SDKv2)
Dual environment: Supports production and sandbox environments
Release automation: GoReleaser + release-please for versioned binary distribution
Terraform Registry: Published at registry.terraform.io/hanzoai/terraform-provider-hanzo

Tech Stack

Language: Go 1.24
Framework: HashiCorp Terraform Plugin Framework v1.15.0
SDK: github.com/hanzoai/go-sdk v0.1.0-alpha.4
Code generation: openapi-generator (from OpenAPI spec)
Release: GoReleaser + release-please + GPG signing
Version: v0.1.0-alpha.2

Current State

The provider is in early alpha. The provider.go registers authentication (API key via config or HANZO_API_KEY env var), base URL configuration, and environment selection. The Resources() and DataSources() methods currently return empty slices -- resource implementations will be generated as the Hanzo OpenAPI spec stabilizes.

When to use

Managing Hanzo AI infrastructure via Terraform
Integrating Hanzo resources into existing Terraform-managed infrastructure
Automating Hanzo service provisioning in CI/CD pipelines

Hard requirements

Terraform CLI 1.0+
Hanzo API key (via api_key config or HANZO_API_KEY env var)

Quick reference

| Item | Value | |------|-------| | Provider source | hanzoai/terraform-provider-hanzo | | Version | v0.1.0-alpha.2 | | Language | Go 1.24 | | Go SDK | github.com/hanzoai/go-sdk v0.1.0-alpha.4 | | Registry | registry.terraform.io/hanzoai/terraform-provider-hanzo | | Repo | github.com/hanzoai/terraform-provider-hanzo | | Branch | main | | License | Apache 2.0 | | Generated by | openapi-generator |

Usage

terraform {
 required_providers {
 terraform-provider-hanzo = {
 source = "hanzoai/terraform-provider-hanzo"
 version = "~> 0.1.0-alpha.2"
 }
 }
}

provider "terraform-provider-hanzo" {
 api_key = "hk-..." # or set HANZO_API_KEY env var
}

Provider Configuration

| Property | Environment Variable | Required | Default | |----------|---------------------|----------|---------| | api_key | HANZO_API_KEY | Yes | -- | | base_url | HANZO_BASE_URL | No | Production URL | | environment | -- | No | "production" |

The environment attribute accepts "production" or "sandbox". Cannot be set simultaneously with base_url.

Repository Structure

main.go # Provider entry point (providerserver.Serve)
internal/
 provider.go # Provider config, auth, client initialization
 version.go # Version constant
 apiform/ # API form encoding utilities
 apijson/ # API JSON marshaling
 customfield/ # Custom Terraform field types
 customvalidator/ # Custom validators
 importpath/ # Import path utilities
 logging/ # Structured logging
 test_helpers/ # Test helpers
 types/ # Terraform type definitions
bin/ # Build scripts
docs/
 index.md # Terraform Registry docs
examples/ # Usage examples
scripts/ # CI/release scripts
tools/ # Development tools
.goreleaser.yml # GoReleaser config (multi-platform builds)
.release-please-manifest.json # Release automation
release-please-config.json # Release-please configuration
terraform-registry-manifest.json # Registry metadata
CHANGELOG.md # Versioned changelog

Build and Development

# Build the provider
go build -o terraform-provider-hanzo

# Run tests
go test ./...

# Format code
go fmt ./...

# Lint
golangci-lint run

# Generate docs
go generate ./...

# Run with debug mode
go run main.go -debug

Release Process

Releases use GoReleaser with GPG signing:

# Tag and push
git tag v0.1.0-alpha.3
git push origin v0.1.0-alpha.3
# GitHub Actions runs GoReleaser -> multi-platform binaries -> Terraform Registry

Platforms: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, freebsd/amd64

Environment Variables

HANZO_API_KEY=hk-... # API authentication (required)
HANZO_BASE_URL=https://... # Override API base URL

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Missing api_key | Not configured | Set HANZO_API_KEY env var or provider config | | Ambiguous URL error | Both base_url and environment set | Use only one | | Provider not found | Not in registry yet | Install from source: go install | | No resources available | Alpha state | Resources are being generated from OpenAPI |

Related Skills

hanzo/go-sdk.md - Go SDK (underlying client library)
hanzo/hanzo-operator.md - K8s operator (alternative for K8s-native infra)
hanzo/hanzo-charts.md - Helm charts (alternative for K8s deployments)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: terraform, iac, infrastructure, go, openapi Prerequisites: Terraform CLI 1.0+, Hanzo API key