Digger (OpenTaco) Documentation

Digger provides several key features for automating infrastructure Pull Requests:

• Plan Preview: Generate automated previews of proposed infrastructure changes.
• CommentOps: Operate PR workflows (like plan or apply) directly from PR comments.
• Layering: Manage stack ordering to handle dependencies between infrastructure layers.
• PR-level locks: Prevent unsafe concurrency by locking specific resources or stacks during a PR.
• Private runners: Configure dedicated runners for secure execution.
• FIPS 140: Configure compliance features such as FIPS 140 support.

OpenTaco State Management provides centralized Terraform/OpenTofu state management with built-in access controls, version history, and rollback support. It is designed to replace manual bucket-based state management (like S3) with a more secure and manageable interface.

Key features include:

• Centralized Storage: Centralized state storage with fine-grained RBAC and SSO integration.
• Version Control: Native version history and rollback support for state files.
• HCP Terraform Compatibility: Uses a TFE-compatible cloud backend pattern, allowing teams to use familiar terraform login or tofu login workflows for drop-in adoption.
• Simplified Configuration: Reduces Terraform backend configuration overhead by using TFE-compatible workflows.
• Secure Access: Uses a token-based access model to simplify cross-account CI access.

OpenTaco is designed around the following core principles:

• Self-hosting focus: Built to be self-hosted with ease.
• CLI-first UX: The primary interface is the CLI; the UI is reserved for infrequent administrative or configuration tasks.
• Pluggable compute: Designed to support multiple compute providers, starting with GitHub Actions (GHA).
• State management: Manages state within a user-provided S3 bucket.
• Security: Includes first-class RBAC (Role-Based Access Control) and SSO support.

An OpenTaco role is a named collection of permissions used for Role-Based Access Control (RBAC) within an organization. Roles define the specific actions a user can perform on specific resources.

When RBAC is first initialized for an organization, the following default roles are created:

• admin: Provides full control. The user who initializes RBAC is automatically assigned this role.
• default: A standard role for other users.

Roles are used to enforce least-privilege access, such as separating production access from development access or limiting engineers to scoped write access only for the units they manage.

The OpenTaco Statesman service acts as an intermediary between users/clients and S3-compatible storage. It provides a REST API to manage state files through a concept called a "unit" (a versioned statefile).

Core Capabilities:

• Unit Management: Create, Update, and Delete operations on state units.
• Permissions: Granular access control (e.g., allowing users to read state without write access).
• Version Control: List state version history and perform rollbacks.
• Storage: Uses S3-compatible storage (AWS S3, GCS, or Azure Blob Storage) to store state files and unit metadata.

Supported Clients:

• Taco CLI: Used for unit management operations.
• Terraform / OpenTofu CLI: Used for standard state operations like pull, push, and lock during plan or apply phases.
• Web UI: (Planned/Expansion point) for interacting with the service.

OpenTaco (formerly Digger) is an open-source, self-hostable platform for running Terraform and OpenTofu safely. It provides four core capabilities that can be used individually or as a complete platform:

• State management: Centralized state storage with access controls, version history, and an HCP Terraform-compatible interface.
• Remote runs (Beta): Remote execution of Terraform commands with log streaming (requires OpenTaco State Management).
• PR automation: Automated plan/apply workflows for pull requests in CI, supporting OpenTofu, Terraform, and Terragrunt.
• Drift detection + remediation: Scheduled drift detection with notifications (Slack/GitHub Issues) and remediation workflows.

A unit is an OpenTaco workspace representing the smallest managed state boundary. It includes the state file, its lock, and its version history.

Key characteristics of a unit:

• State Management: Tracks exactly one state file.
• Concurrency Control: Supports explicit lock/unlock operations to prevent conflicting writes.
• Version History: Maintains a history of state snapshots to allow for rollbacks.
• Isolation: Used to isolate environments (e.g., app/prod) or services (e.g., network/shared).

This repository follows a specific organizational structure to maintain DRY (Don't Repeat Yourself) principles across accounts, regions, and environments:

• Account: Top-level folders for each AWS account (e.g., prod-account, non-prod).
• Region: Folders within an account for specific AWS regions (e.g., us-east-1). A _global folder may exist here for account-wide resources like IAM.
• Environment: Folders within a region for specific environments (e.g., qa, stage, prod). A _global folder may exist here for region-wide resources like Route 53 A records.
• Resource: The final level where specific resources (EC2, RDS, etc.) are defined using terragrunt.hcl files.