Terraform Infrastructure-as-Code

Relevant source files

• infrastructure/terraform/authentik/applications.tf
• infrastructure/terraform/authentik/customization+mapping+scope.tf
• infrastructure/terraform/authentik/directory.tf
• infrastructure/terraform/authentik/expressions/openid-scope-nextcloud.py
• infrastructure/terraform/authentik/expressions/openid-scope-profile.py
• infrastructure/terraform/authentik/expressions/user-settings-authorization.py
• infrastructure/terraform/authentik/expressions/user-settings-avatar-authorization.py
• infrastructure/terraform/authentik/flows.tf
• infrastructure/terraform/authentik/main.tf
• infrastructure/terraform/authentik/oauth2_application/main.tf
• infrastructure/terraform/authentik/oauth2_application/variables.tf
• infrastructure/terraform/authentik/proxy_application/main.tf
• infrastructure/terraform/authentik/proxy_application/outputs.tf
• infrastructure/terraform/authentik/stages-prompt_fields.tf
• infrastructure/terraform/authentik/stages.tf
• infrastructure/terraform/authentik/system.tf
• infrastructure/terraform/authentik/variables.tf
• infrastructure/terraform/cloudflare/locals.tf
• infrastructure/terraform/cloudflare/main.tf
• infrastructure/terraform/cloudflare/providers.tf
• infrastructure/terraform/cloudflare/secret.sops.yaml
• infrastructure/terraform/cloudflare/variables.tf
• infrastructure/terraform/s3/garage/README.md
• infrastructure/terraform/s3/garage/main.tf
• infrastructure/terraform/s3/garage/modules/garage/main.tf
• infrastructure/terraform/s3/garage/modules/garage/outputs.tf
• infrastructure/terraform/s3/garage/modules/garage/variables.tf
• infrastructure/terraform/s3/garage/providers.tf
• infrastructure/terraform/s3/garage/variables.tf

This section covers the Terraform configurations used to provision external and internal infrastructure components beyond the Proxmox hypervisor. It details the management of Cloudflare DNS and networking, S3 object storage through Garage and Backblaze, and the complex identity provider setup for Authentik.

State Management and Backend

The repository utilizes Cloudflare R2 as the primary S3-compatible backend for Terraform state files. This pattern ensures that infrastructure state is stored off-site, enabling recovery even if the local Proxmox cluster or Garage S3 storage is unavailable.

R2 Backend Pattern

The backend is configured using the s3 block with custom endpoints pointing to Cloudflare’s R2 storage infrastructure/terraform/authentik/main.tf12-27 Key features include:

• Locking: Enabled via use_lockfile = trueinfrastructure/terraform/authentik/main.tf15
• Compatibility: Uses skip_credentials_validation and use_path_style to interface with the R2 API infrastructure/terraform/authentik/main.tf21-26
• Separation: Each infrastructure component (Cloudflare, Authentik, S3) maintains its own state file (e.g., authentik.terraform.tfstate, cloudflare.terraform.tfstate) infrastructure/terraform/authentik/main.tf14infrastructure/terraform/cloudflare/providers.tf17

Sources:infrastructure/terraform/authentik/main.tf12-27infrastructure/terraform/cloudflare/providers.tf15-31

---

Cloudflare DNS and Networking

The Cloudflare Terraform module manages public DNS records, mail configuration, and external ingress routing for services running outside the primary cluster or requiring public visibility.

DNS Record Architecture

Records are defined in a cloudflare_record local map infrastructure/terraform/cloudflare/locals.tf19-166

• Mail Services: Configures MX, SPF, DKIM, and DMARC records for domain email security infrastructure/terraform/cloudflare/locals.tf62-100
• External Resilience: Points to services like status (Gatus) and vw (Vaultwarden) which are hosted on Fly.io infrastructure/terraform/cloudflare/locals.tf131-159
• GitHub Pages: Manages CNAME and A/AAAA records for documentation and personal sites infrastructure/terraform/cloudflare/locals.tf114-119infrastructure/terraform/cloudflare/locals.tf168-179

Code-to-Cloud Mapping

The following diagram shows how Terraform local variables map to Cloudflare Provider resources.

Diagram: Cloudflare Resource Mapping

[Flowchart Diagram]

Sources:infrastructure/terraform/cloudflare/locals.tf19-180infrastructure/terraform/cloudflare/providers.tf33-36

---

Authentik Identity Provider

The Authentik configuration is the most complex Terraform module, managing the entire OIDC/SAML and Proxy lifecycle for the home-ops environment.

Application Provisioning

Authentik applications are categorized into two types:

1. Proxy Applications: Managed via a local module proxy_applicationinfrastructure/terraform/authentik/applications.tf75-91 These provide authentication headers to legacy applications or those without native OIDC support (e.g., echo-server, prometheus-ext) infrastructure/terraform/authentik/applications.tf12-72
2. OAuth2/OIDC Applications: Defined in a local map applicationsinfrastructure/terraform/authentik/applications.tf106-170 This includes grafana, headlamp, jellyfin, and forgejo.

Authentication Pipeline

The module configures the full Authentik “Flow” and “Stage” architecture:

• Stages: Individual steps like authentik_stage_identification for user lookup infrastructure/terraform/authentik/stages.tf25-35 and authentik_stage_authenticator_validate for MFA infrastructure/terraform/authentik/stages.tf43-53
• Flows: Chains of stages. For example, the authentication-flow binds identification, MFA validation, and login stages in a specific order infrastructure/terraform/authentik/flows.tf38-63
• Sources: Federated login via Google is configured as an OAuth source infrastructure/terraform/authentik/directory.tf82-97

Diagram: Authentik Authentication Flow Logic

[Flowchart Diagram]

Sources:infrastructure/terraform/authentik/stages.tf25-68infrastructure/terraform/authentik/flows.tf38-63

---

S3 Bucket Provisioning (Garage)

The s3/garage module manages object storage buckets within the local cluster’s Garage S3 deployment.

Module: garage

This submodule encapsulates the creation of a bucket, an access key, and the association between them.

• Resource garage_bucket: Creates the bucket and optionally configures it for static website hosting infrastructure/terraform/s3/garage/modules/garage/main.tf10-16
• Resource garage_key: Generates a unique S3 access key named after the bucket infrastructure/terraform/s3/garage/modules/garage/main.tf18-20
• Resource garage_bucket_key: Grants read, write, and owner permissions to the generated key and a master admin user infrastructure/terraform/s3/garage/modules/garage/main.tf29-43

Configuration Parameters

Variable	Description	Default
bucket_name	Name of the S3 bucket and alias	(Required)
admin_user	ID of the admin key to grant access	(Required)
website_access_enabled	Enables static site hosting	false

Sources:infrastructure/terraform/s3/garage/modules/garage/main.tf1-43infrastructure/terraform/s3/garage/modules/garage/variables.tf1-33