feat(opentofu-agent): add OpenTofu Agent support

Add OpenTofu agent to Distr, enabling infrastructure provisioning
alongside container deployments. Vendors can manage the full deployment
lifecycle — applications and infrastructure — through a single workflow.

- Database schema (migrations 84-85): opentofu deployment type, tofu
  columns on applicationversion/deploymentrevision, opentofu_state
  table for lock management
- Agent manifest & connect: OpenTofu branch in connect flow
- HTTP state backend: GET/POST state with S3 storage, POST lock/unlock
  with PostgreSQL locking, Basic Auth middleware
- Agent binary (cmd/agent/opentofu): polling loop, reconciliation, OCI
  artifact pull, tofu init/plan/apply/destroy via terraform-exec SDK
- Dockerfile: multi-stage build for the OpenTofu agent container
- DEP document: full design proposal

Closes #1946

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: waveywaves

DEP-terraform-agent.md

@@ -0,0 +1,32 @@
+FROM golang:1.26 AS builder
+ARG TARGETOS
+ARG TARGETARCH
+ARG VERSION
+ARG COMMIT
+
+WORKDIR /workspace
+COPY go.mod go.mod
+COPY go.sum go.sum
+RUN go mod download
+
+COPY api/ api/
+COPY cmd/agent/opentofu/ cmd/agent/opentofu/
+# doesn't exist (yet?)
+# COPY pkg/ pkg/
+COPY internal/ internal/
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} \
+  go build -a -o agent \
+  -ldflags="-s -w -X github.com/distr-sh/distr/internal/buildconfig.version=${VERSION:-snapshot} -X github.com/distr-sh/distr/internal/buildconfig.commit=${COMMIT}" \
+  ./cmd/agent/opentofu/
+
+FROM alpine:3.21
+COPY --from=ghcr.io/opentofu/opentofu:1.9 /usr/local/bin/tofu /usr/local/bin/tofu
+WORKDIR /
+COPY --from=builder /workspace/agent .
+RUN addgroup -S agent && adduser -S agent -G agent && \
+    mkdir -p /scratch && chown agent:agent /scratch
+USER agent
+ENV TF_IN_AUTOMATION=1
+ENV TF_INPUT=0
+ENV TF_PLUGIN_CACHE_DIR=/scratch/plugin-cache
+ENTRYPOINT ["/agent"]

Dockerfile.opentofu-agent

@@ -39,6 +39,14 @@ type AgentDeployment struct {
 	Values             map[string]any `json:"values"`
 	IgnoreRevisionSkew bool           `json:"ignoreRevisionSkew"`
 	HelmOptions        *HelmOptions   `json:"helmOptions,omitempty"`
+
+	// OpenTofu specific data
+
+	TofuConfigURL     string            `json:"tofuConfigUrl,omitempty"`
+	TofuConfigVersion string            `json:"tofuConfigVersion,omitempty"`
+	TofuVars          map[string]any    `json:"tofuVars,omitempty"`
+	TofuBackendConfig map[string]string `json:"tofuBackendConfig,omitempty"`
+	TofuVersion       string            `json:"tofuVersion,omitempty"`
 }
 
 type AgentDeploymentStatus struct {

api/agent.go

@@ -0,0 +1,113 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path"
+	"sync"
+
+	"github.com/distr-sh/distr/api"
+	"github.com/google/uuid"
+)
+
+type State string
+
+const (
+	StateUnspecified State = ""
+	StateInstalling  State = "installing"
+	StateInstalled   State = "installed"
+	StateFailed      State = "failed"
+)
+
+type AgentDeployment struct {
+	ID                uuid.UUID `json:"id"`
+	RevisionID        uuid.UUID `json:"revisionId"`
+	TofuConfigURL     string    `json:"tofuConfigUrl"`
+	TofuConfigVersion string    `json:"tofuConfigVersion"`
+	State             State     `json:"phase"`
+}
+
+func (d AgentDeployment) GetDeploymentID() uuid.UUID {
+	return d.ID
+}
+
+func (d AgentDeployment) GetDeploymentRevisionID() uuid.UUID {
+	return d.RevisionID
+}
+
+func (d *AgentDeployment) FileName() string {
+	return path.Join(DeploymentsDir(), d.ID.String())
+}
+
+func NewAgentDeployment(deployment api.AgentDeployment) *AgentDeployment {
+	return &AgentDeployment{
+		ID:                deployment.ID,
+		RevisionID:        deployment.RevisionID,
+		TofuConfigURL:     deployment.TofuConfigURL,
+		TofuConfigVersion: deployment.TofuConfigVersion,
+	}
+}
+
+var agentDeploymentMutex = sync.RWMutex{}
+
+func GetExistingDeployments() (map[uuid.UUID]AgentDeployment, error) {
+	agentDeploymentMutex.RLock()
+	defer agentDeploymentMutex.RUnlock()
+
+	if entries, err := os.ReadDir(DeploymentsDir()); err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, nil
+		}
+		return nil, err
+	} else {
+		fn := func(name string) (*AgentDeployment, error) {
+			if file, err := os.Open(path.Join(DeploymentsDir(), name)); err != nil {
+				return nil, err
+			} else {
+				defer file.Close()
+				var d AgentDeployment
+				if err := json.NewDecoder(file).Decode(&d); err != nil {
+					return nil, err
+				}
+				return &d, nil
+			}
+		}
+		result := make(map[uuid.UUID]AgentDeployment, len(entries))
+		for _, entry := range entries {
+			if !entry.IsDir() {
+				if d, err := fn(entry.Name()); err != nil {
+					return nil, err
+				} else {
+					result[d.ID] = *d
+				}
+			}
+		}
+		return result, nil
+	}
+}
+
+func SaveDeployment(deployment AgentDeployment) error {
+	agentDeploymentMutex.Lock()
+	defer agentDeploymentMutex.Unlock()
+
+	if err := os.MkdirAll(path.Dir(deployment.FileName()), 0o700); err != nil {
+		return err
+	}
+
+	file, err := os.Create(deployment.FileName())
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	if err := json.NewEncoder(file).Encode(deployment); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func DeleteDeployment(deployment AgentDeployment) error {
+	return os.Remove(deployment.FileName())
+}

cmd/agent/opentofu/agent_deployment.go

@@ -0,0 +1,23 @@
+package main
+
+import (
+	"os"
+	"path"
+
+	"github.com/google/uuid"
+)
+
+func ScratchDir() string {
+	if dir := os.Getenv("DISTR_AGENT_SCRATCH_DIR"); dir != "" {
+		return dir
+	}
+	return "./scratch"
+}
+
+func WorkspaceDir(deploymentID uuid.UUID) string {
+	return path.Join(ScratchDir(), "ws", deploymentID.String())
+}
+
+func DeploymentsDir() string {
+	return path.Join(ScratchDir(), "deployments")
+}