Terraform Registry

6 minute read

Terraform Registry Overview

The Terraform Registry is the central repository for discovering and using Terraform providers, modules, and policy libraries.

Registry Benefits

For Provider Authors

  • Distribution: Automatic hosting and distribution
  • Documentation: Integrated documentation hosting
  • Versioning: Semantic version management
  • Analytics: Usage metrics and download statistics
  • Verification: Verified publisher badge
  • Discovery: Search and categorization

For Users

  • Easy Installation: terraform init automatically downloads providers
  • Version Management: Flexible version constraints
  • Trusted Sources: Verified publishers
  • Documentation: Integrated provider documentation
  • Examples: Ready-to-use example configurations

Provider Tiers

Official Providers

Maintained by HashiCorp:

  • AWS, Azure, Google Cloud
  • Kubernetes
  • Helm, Consul, Vault
  • Highest trust level
  • Namespace: hashicorp/

Partner Providers

Maintained by verified partners:

  • Technology vendors
  • Cloud providers
  • SaaS companies
  • Verified badge
  • Namespace: {organization}/

Community Providers

Maintained by community:

  • Open source maintainers
  • Individual contributors
  • No verification required
  • Namespace: {namespace}/

Registry Requirements

Repository Requirements

  1. GitHub Repository
    • Must be public
    • Naming convention: terraform-provider-{NAME}
    • Example: terraform-provider-cachecloud
  2. Repository Structure 
    terraform-provider-cachecloud/
├── .github/workflows/      # CI/CD
├── docs/                   # Documentation
│   ├── index.md
│   ├── resources/
│   └── data-sources/
├── examples/               # Examples
├── internal/provider/      # Provider code
├── .goreleaser.yml         # Release config
├── LICENSE                 # Open source license
├── README.md               # Project overview
├── CHANGELOG.md            # Version history
├── main.go                 # Entry point
└── go.mod                  # Go module
  3. Licensing
    • Must use OSI-approved license
    • Recommended: Mozilla Public License 2.0 (MPL-2.0)
    • License file must be present

Documentation Requirements

  1. Provider Documentation (docs/index.md)
    • Provider overview
    • Configuration options
    • Authentication methods
    • Example usage
  2. Resource Documentation (docs/resources/*.md)
    • One file per resource
    • Schema documentation
    • Example configurations
    • Import instructions
  3. Data Source Documentation (docs/data-sources/*.md)
    • One file per data source
    • Query examples
    • Output attributes
  4. Examples (examples/)
    • Provider configuration
    • Resource examples
    • Data source examples

Release Requirements

  1. Versioning
    • Semantic versioning (SemVer)
    • Git tags for releases
    • Format: v1.2.3
  2. Signing
    • GPG-signed releases
    • Public key registered
    • Checksums signed
  3. Artifacts
    • Binary for each OS/architecture
    • SHA256 checksums
    • Signature file
  4. Changelog
    • Version history
    • Changes documented
    • Breaking changes highlighted

Account Setup

Create Registry Account

  1. Sign in to Registry 
    https://registry.terraform.io/
  2. Connect GitHub Account
    • OAuth authentication
    • Grant repository access
  3. Create Namespace (for organizations)
    • Choose unique namespace
    • Verify organization ownership

GPG Key Setup

Generate GPG key for signing:

# Generate GPG key
gpg --full-generate-key

# Select:
# - RSA and RSA (default)
# - 4096 bits
# - Key expires in 2 years
# - Your name and email
# - Passphrase

# List keys
gpg --list-secret-keys --keyid-format=long

# Output:
# /Users/you/.gnupg/secring.gpg
# -----------------------------
# sec   4096R/ABCD1234 2026-01-01 [expires: 2028-01-01]
# uid                  Your Name <your.email@example.com>
# ssb   4096R/EFGH5678 2026-01-01

# Export public key
gpg --armor --export ABCD1234 > public-key.asc

Register Public Key

# Upload to Registry
# 1. Go to https://registry.terraform.io/settings/gpg-keys
# 2. Click "Add GPG Key"
# 3. Paste contents of public-key.asc
# 4. Save

Provider Namespace

Choosing a Namespace

For Organizations:

source = "mycompany/cachecloud"

For Individuals:

source = "johndoe/cachecloud"

Registry URL:

https://registry.terraform.io/providers/mycompany/cachecloud

Namespace Verification

Organization Verification:

  1. Add TXT record to domain DNS
  2. Registry verifies ownership
  3. Verified badge displayed

Example DNS Record:

_terraform-registry-verify.example.com. TXT "registry-verify=abc123..."

Repository Configuration

README.md

# Terraform Provider CacheCloud

The CacheCloud provider allows Terraform to manage CacheCloud resources.

## Requirements

- Terraform 1.0+
- Go 1.21+ (for development)

## Using the Provider

```terraform
terraform {
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      version = "~> 1.0"
    }
  }
}

provider "cachecloud" {
  api_key = var.cachecloud_api_key
}

Documentation

Full documentation is available on the Terraform Registry.

Development

# Clone repository
git clone https://github.com/example/terraform-provider-cachecloud

# Build provider
make build

# Run tests
make test

# Run acceptance tests
make testacc

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

License

Mozilla Public License Version 2.0


### LICENSE

Mozilla Public License Version 2.0 ==================================

  1. Definitions

1.1. “Contributor” means each individual or legal entity that creates, contributes to the creation of, or owns Covered Software.

[Full MPL-2.0 license text]


### CHANGELOG.md

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2026-06-30

### Added
- Initial release
- Support for `cachecloud_cache` resource
- Support for `cachecloud_cache` data source
- Redis and Memcached engine support
- Multi-AZ deployment configuration
- Automatic backup configuration

### Documentation
- Provider configuration guide
- Resource documentation
- Getting started guide

[Unreleased]: https://github.com/example/terraform-provider-cachecloud/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/example/terraform-provider-cachecloud/releases/tag/v1.0.0

Terraform Protocol Version

Protocol Version Support

// main.go
package main

import (
    "context"
    "flag"
    "log"

    "github.com/hashicorp/terraform-plugin-framework/providerserver"
    "github.com/example/terraform-provider-cachecloud/internal/provider"
)

var (
    version string = "dev"
)

func main() {
    var debug bool

    flag.BoolVar(&debug, "debug", false, "set to true to run the provider with support for debuggers")
    flag.Parse()

    opts := providerserver.ServeOpts{
        Address: "registry.terraform.io/example/cachecloud",
        Debug:   debug,
    }

    err := providerserver.Serve(context.Background(), provider.New(version), opts)
    if err != nil {
        log.Fatal(err.Err())
    }
}

Manifest File

{
  "version": 1,
  "metadata": {
    "protocol_versions": ["6.0"]
  }
}

Pre-publication Checklist

Code Quality

  • ✅ All acceptance tests pass
  • ✅ Code follows Go best practices
  • ✅ No hardcoded credentials
  • ✅ Proper error handling
  • ✅ Comprehensive logging

Documentation

  • ✅ Provider documentation complete
  • ✅ All resources documented
  • ✅ All data sources documented
  • ✅ Examples provided
  • ✅ Guides created

Repository Setup

  • ✅ Repository name follows convention
  • ✅ LICENSE file present
  • ✅ README.md complete
  • ✅ CHANGELOG.md present
  • ✅ .goreleaser.yml configured

Security

  • ✅ GPG key generated
  • ✅ Public key registered
  • ✅ No secrets in repository
  • ✅ Security scanning enabled

Release Automation

  • ✅ GitHub Actions workflow configured
  • ✅ GoReleaser tested
  • ✅ Release process documented

Testing Registry Publication

Local Testing

# Build provider locally
make build

# Install to local plugins directory
mkdir -p ~/.terraform.d/plugins/registry.terraform.io/example/cachecloud/1.0.0/darwin_amd64
cp terraform-provider-cachecloud ~/.terraform.d/plugins/registry.terraform.io/example/cachecloud/1.0.0/darwin_amd64/

# Test with local provider
cat > test.tf <<EOF
terraform {
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      version = "1.0.0"
    }
  }
}

provider "cachecloud" {}
EOF

terraform init

Development Overrides

# ~/.terraformrc
provider_installation {
  dev_overrides {
    "example/cachecloud" = "/path/to/terraform-provider-cachecloud"
  }

  direct {}
}

Best Practices

1. Namespace Selection

# ✅ Good: Organization namespace
source = "mycompany/cachecloud"

# ✅ Good: Personal namespace (verified)
source = "johndoe/cachecloud"

# ❌ Bad: Generic namespace
source = "terraform/cachecloud"  # Reserved

2. Repository Naming

# ✅ Good: Follows convention
terraform-provider-cachecloud

# ❌ Bad: Doesn't follow convention
cachecloud-terraform-provider
tf-cachecloud

3. License Selection

# ✅ Good: OSI-approved licenses
- Mozilla Public License 2.0 (MPL-2.0) - Recommended
- Apache License 2.0
- MIT License
- BSD 3-Clause License

# ❌ Bad: Non-OSI or proprietary
- Custom proprietary license
- No license

Troubleshooting

Issue: Repository Not Found

Problem:

Provider not found on registry

Solution:

  1. Verify repository name follows convention
  2. Ensure repository is public
  3. Check GitHub account is linked
  4. Refresh registry connection

Issue: Documentation Not Displaying

Problem:

Documentation pages are blank

Solution:

  1. Verify docs/ directory structure
  2. Check markdown frontmatter format
  3. Run tfplugindocs validate
  4. Wait for registry to process (can take 5-10 minutes)

Issue: Version Not Available

Problem:

Version constraint not satisfied

Solution:

  1. Verify git tag exists
  2. Check tag format (must be v1.2.3)
  3. Ensure release is published
  4. Wait for registry sync (can take 10-15 minutes)

Key Takeaways

  • ✅ Registry provides centralized provider distribution
  • ✅ Repository must follow naming convention
  • ✅ Documentation must be comprehensive
  • ✅ Releases must be GPG-signed
  • ✅ Use semantic versioning
  • ✅ Choose appropriate namespace
  • ✅ Include OSI-approved license
  • ✅ Test locally before publishing
  • ✅ Follow pre-publication checklist
  • ✅ Maintain comprehensive changelog

What’s Next?

Learn about semantic versioning and release management for your provider.

Next: Versioning & Releases →

Previous: ← Publishing & Distribution
Next: Versioning & Releases →

Last updated: June 30, 2026

Updated:

You may also enjoy