Introduction: The Challenge of Infrastructure-as-Code Scaling

As DevOps organizations mature, Infrastructure as Code (IaC) inevitably scales from a few loose scripts into an ecosystem of reusable modules and custom providers. Managing these components efficiently becomes paramount for maintaining security, consistency, and deployment velocity. While public registries serve general open-source needs, enterprise environments demand a private, secure, and highly available registry to host proprietary infrastructure blueprints.

Traditionally, teams have relied on enterprise SaaS offerings like Terraform Cloud or expensive self-hosted artifact repositories. However, with the rise of OpenTofu—the open-source evolution of Terraform—the ecosystem has shifted toward community-driven, cost-effective alternatives. One of the most elegant, resilient, and virtually free solutions is self-hosting an OpenTofu Registry using Cloudflare R2 object storage. This guide provides an end-to-end blueprint for building a production-ready, serverless OpenTofu registry tailored for modern DevOps workflows.

Why Cloudflare R2 for OpenTofu Registry?

Before diving into the implementation details, it is crucial to understand why Cloudflare R2 is the ideal backend for this architecture compared to traditional cloud storage like AWS S3 or Google Cloud Storage:

Zero Egress Fees: Traditional cloud storage providers charge heavily for data transferred out of their network. Cloudflare R2 completely eliminates egress fees, making frequent module downloads across multiple CI/CD pipelines highly economical.
Global Performance via CDN: By integrating natively with Cloudflare’s global edge network, your registry benefits from ultra-low latency caching worldwide without complex infrastructure setup.
S3-Compatible API: R2 uses the standard S3 API protocol, allowing seamless integration with existing tools, custom scripts, and registry generation engines.

Understanding the OpenTofu Registry Protocol

The OpenTofu and Terraform CLI tools do not require a complex, dynamic backend application server to function as a registry. Instead, they rely on a simple, static service discovery and REST API layout known as the Registry Provider and Module Protocols.

When the OpenTofu CLI runs, it performs an initial service discovery look-up at a standardized path: /.well-known/terraform.json. This file instructs the CLI where to look for specific endpoints. Consequently, we can present a structured layout of static JSON files and compressed archive files (.tar.gz or .zip) inside a Cloudflare R2 bucket to serve as a fully functional registry. No running virtual machines or container clusters are required.

Step-by-Step Implementation Guide

Step 1: Set Up and Configure the Cloudflare R2 Bucket

First, log into your Cloudflare dashboard and navigate to the R2 section to create a new storage bucket. Name it logically, for instance, opentofu-private-registry.

Once created, you must connect this bucket to a custom domain or subdomain (e.g., registry.yourcompany.com). This domain will act as the base URL for your registry service discovery. Ensure that you generate an S3 API credential pair (Access Key ID and Secret Access Key) with read/write permissions for this specific bucket, which will be utilized by your CI/CD automation pipeline.

Step 2: Implement Service Discovery

To enable the OpenTofu CLI to recognize your domain as a valid registry, place the following JSON file at the root of your bucket configuration, precisely named .well-known/terraform.json:

{
  "modules.v1": "/modules/v1/",
  "providers.v1": "/providers/v1/"
}

This configuration defines the base path mapping for where your IaC engine will look for modules and providers respectively.

Step 3: Structuring Infrastructure Modules

For modules, the protocol expects a standardized endpoint pattern: /modules/v1/{namespace}/{name}/{system}/versions. When requested, this endpoint must return a list of available versions and their source locations. For example, a network module could have a JSON structure located at /modules/v1/devops/network/aws/versions containing:

{
  "modules": [
    {
      "version": "1.0.0",
      "targets": []
    }
  ]
}

When the CLI selects a version, it requests the download location. The registry responds via an HTTP header or direct payload indicating the secure download URL of the module zip file, which is also hosted directly inside your R2 bucket.

Automating the Registry Pipeline via CI/CD

Manually generating JSON files and uploading zip archives is error-prone and counterproductive. To maintain an agile DevOps workflow, this process should be entirely managed by a continuous integration pipeline, such as GitHub Actions or GitLab CI.

Automation Best Practice: Every time a new tag is pushed to a module git repository, the CI pipeline should automatically lint the code, package the directory into a compressed archive, calculate the SHA256 checksum, generate updated registry metadata JSON files, and synchronize the assets to Cloudflare R2 using the AWS CLI or specialized GitHub Actions.

Security and Authentication Mechanisms

Since this registry contains proprietary infrastructure definitions, safeguarding access is critical. Because Cloudflare R2 is sitting behind the Cloudflare network layer, you can easily secure your registry endpoints using Cloudflare Access (part of Cloudflare Zero Trust) or Cloudflare Worker-based Token Authentication.

By enforcing an API token verification layer using standard HTTP Bearer tokens, you can authorize your local developer machines and production CI/CD runners to seamlessly authenticate against the private registry using an .tofurc or .terraformrc configuration file locally:

credentials "registry.yourcompany.com" {
  token = "your-secure-ci-cd-token"
}

Conclusion and Next Steps

Self-hosting a private OpenTofu registry on Cloudflare R2 bridges the gap between infrastructure security and cost optimization. By treating your registry as a static site backed by resilient, globally-distributed object storage, your DevOps team eliminates unnecessary compute overhead, completely bypasses data egress fees, and retains absolute control over its proprietary cloud assets.

Transitioning to this architecture allows your engineering organization to scale indefinitely without scaling costs. Begin by mapping out your internal modules, setting up a dedicated R2 bucket, and configuring your first CI/CD publishing pipeline to unlock a robust, enterprise-grade IaC registry framework.

Self-Hosting a Private OpenTofu Registry on Cloudflare R2: A Cost-Effective Guide for DevOps Teams