How do I set up a private Terraform registry with GitHub?

Use the GitHub store by applying specific topics to your repositories, configure authentication with GITHUB_TOKEN or a GitHub app, and set command-line arguments like -github-owner-filter. The registry will automatically discover modules and providers based on these topics, as detailed in the GitHub Store section.

What's the difference between this and Terraform Cloud's private registry?

This is a self-hosted, open-source solution that gives full control over infrastructure and costs, while Terraform Cloud is a managed service with additional features like state management, but requires a subscription and less customization.

Can I host Terraform providers using an S3 backend?

No, the S3 store currently only supports modules, not providers, as indicated in the stores table. For provider hosting, you must use the GitHub store, which implements providers.v1 with specific release requirements.

How to secure module downloads with authentication?

Enable HTTP bearer token authentication by setting -auth-disabled false and providing a -auth-tokens-file. Additionally, use the ASSET_DOWNLOAD_AUTH_SECRET environment variable to sign JWTs for protecting download routes, as explained in the configuration section.

Is this compatible with Terraform v0.12?

Module registry might work, but provider registry support is only for Terraform CLI v0.13 and later, as stated in the README, so for providers, it's not compatible with v0.12 and could cause issues.

What are the limitations compared to HashiCorp's public registry?

It lacks protocols like login.v1, has unstable APIs pre-v1, and requires manual setup for stores and authentication. However, it offers full control and private hosting for internal use without external dependencies.

Open-Awesome

terraform-registry

NOASSERTIONGov0.20.1

A private Terraform registry implementation with modular backends for hosting modules and providers.

GitHub

118 stars8 forks0 contributors

What is terraform-registry?

Terraform Registry is an open-source implementation of the Terraform registry protocol that allows organizations to host their own private registry for Terraform modules and providers. It solves the problem of securely distributing and managing internal Terraform modules and providers without relying on public registries. The project supports modular store backends like GitHub and S3 for flexible integration with existing infrastructure.

Target Audience

DevOps engineers, platform teams, and organizations using Terraform who need to maintain private module and provider registries for internal infrastructure code.

Value Proposition

It provides a fully customizable private registry that integrates with existing version control and storage systems, offering greater control and security over infrastructure code distribution compared to public registries.

Overview

A private Terraform registry with modular store backends.

Use Cases

Best For

Hosting private Terraform modules within an organization
Distributing internal Terraform providers securely
Integrating module discovery with GitHub repositories using topics
Storing Terraform modules in S3 buckets for private access
Implementing authentication for private module registries
Running a lightweight registry via Docker containers

Not Ideal For

Organizations seeking a fully managed, no-maintenance private registry solution
Teams locked into Terraform CLI versions earlier than v0.13 for provider management
Projects requiring the login.v1 protocol for integrated authentication flows
Use cases where distributing Terraform providers via S3 storage is a hard requirement

Pros & Cons

Pros

Modular Backend Flexibility

Supports GitHub and S3 stores, enabling seamless integration with existing infrastructure like version control and cloud storage, as detailed in the README's store configurations.

Provider Registry Support

Implements the full providers.v1 protocol, allowing private hosting of Terraform providers compatible with CLI v0.13+, including verification steps for GitHub releases.

Configurable Authentication

Offers optional HTTP bearer token authentication for securing endpoints, with additional store-specific auth schemes and environment variable controls for downloads.

Docker and Native Deployment

Can be run natively or via Docker, with extensive configuration options for logging, TLS, and environment variables, making deployment flexible across environments.

Cons

Missing Login Protocol

The login.v1 protocol is marked as not implemented in the features list, limiting advanced authentication integrations that some teams might need for seamless workflows.

API Instability

APIs are not stable and may introduce breaking changes in minor versions before v1, as noted in the README warning, posing a risk for production deployments.

Limited S3 Provider Support

S3 store only supports modules.v1, not providers.v1, as shown in the stores table, making it unsuitable for provider distribution via S3 without additional workarounds.

No Built-in Module Verification

Stores do not verify if repositories or S3 objects contain valid Terraform modules, relying entirely on client-side validation, which could lead to deployment errors.

Frequently Asked Questions

Related Projects

citizen

A Private Terraform Module/Provider Registry

Stars654

Forks82

Last commit1 year ago

terralist

Terraform Private Registry for modules and providers manageable from a REST API

Stars516

Forks55

Last commit3 days ago

terrareg

Open source Terraform module registry with UI, optional Git integration and deep analysis. Demo: https://terrareg-main.gitlab-pr.dockstudios.co.uk

Stars347

Forks39

Last commit3 months ago

Terrareg