# 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

1. **Terraform CLI** 1.0+
2. **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

```hcl
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

```bash
# 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:

```bash
# 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

```bash
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