Terraform Overview¶
Terraform manages Authentik identity configuration, Cloudflare DNS/tunnels, Oracle Cloud compute, AWS services, Backblaze B2 storage, AdGuard Home configuration, and database user/grant management.
Modules¶
terraform/
├── authentik/ # Identity configuration, flows, providers, policies, and branding
├── adguard/ # AdGuard Home DNS rewrites, filters, and config
├── aws/ # AWS services and supporting identity resources
├── cloudflare/ # DNS records, tunnels, WAF, zone settings
├── mariadb/ # MariaDB databases, users, and grants
├── oci/ # Oracle Cloud instance (k3s-oci-m3) and networking
├── postgres/ # PostgreSQL databases, users, and grants
└── backblaze/ # B2 buckets and scoped application keys
aws¶
Manages AWS services and existing Alexa skill configuration with encrypted settings. Uses the AWS provider, and the REST provider.
authentik¶
Manages static Authentik configuration using goauthentik/authentik (~> 2026.0).
Existing object IDs, OAuth client credentials, signing material, MFA setup flows,
account lifecycle flows, access policies, and memberships are retained.
| File | Purpose |
|---|---|
applications.tf, mappings.tf |
OAuth2 providers, Uptime Kuma proxy, applications, and claims |
flows.tf, stages.tf, policies.tf, policy_bindings.tf |
Login, MFA, account lifecycle, and authorization |
notifications.tf, system.tf |
Event rules and certificate |
outposts.tf |
Proxy outpost configuration |
blueprints.tf |
Disable packaged reconciliation except system user attributes |
brand.tf |
Homelab title and login CSS |
secrets.sops.yaml |
Encrypted provider credentials, access-binding IDs, and private configuration with opaque keys |
Terraform owns static administrative settings. Authentik owns groups, group memberships, user accounts, their metadata, passwords, MFA devices, sessions, tokens, OAuth grants, event history, its built-in source, generated outpost accounts/permissions, and packaged system attribute definitions. User and group resources were forgotten from Terraform state without deleting accounts or groups or changing memberships. Existing user- and group-specific access bindings reference encrypted IDs. Tenant-level configuration is outside this module's ownership.
Use terraform plan -parallelism=1 -out=change.tfplan and review the saved plan
before applying. Keep plans, state snapshots, and API inventories outside Git;
they can contain credentials. Existing objects were imported directly into remote
state, and their Terraform addresses were renamed there. The module contains no
import blocks or one-time state-repair declarations.
The cleanup removes unused protocol mappings, obsolete setup/source configuration,
an unused email stage and test application, unreferenced groups, and the unused
Grafana OAuth integration. Retained flows, stages, policies, and mappings use
Homelab names; flow slugs use the homelab- prefix. Packaged blueprint controls
remain disabled, except the user-attribute schema, so
removed configuration is not recreated. The embedded outpost retains its
API-enforced system name.
ArgoCD, Mealie, Node-RED, and Uptime Kuma integrations remain. Node-RED uses its existing OpenID strategy in persistent settings; its consumer configuration still needs reconciliation with Git. Grafana has no configured OAuth consumer, so its unused Authentik application/provider are removed.
adguard¶
Manages AdGuard Home running on rpi-4b via the gmichels/adguard provider.
| File | Purpose |
|---|---|
config.tf |
Global AdGuard settings (DNS, filtering, stats, query log) |
dns_rewrites.tf |
Local DNS rewrites (LAN IPs + OCI public IP for Plex) |
filters_deny.tf |
Blocklists |
filters_allow.tf |
Allowlists |
user_rules.tf |
Custom user rules |
secrets.sops.yaml |
Encrypted: host, username, password, domain, OCI public IP |
Known provider bug
gmichels/adguard v1.7.0 returns unknown values for tls.* fields after apply, which taints adguard_config. A lifecycle { ignore_changes = [tls] } workaround is in place. If the resource becomes tainted, run terraform untaint adguard_config.main before applying.
mariadb¶
Manages MariaDB databases, users, and grants via the petoju/mysql provider.
| File | Purpose |
|---|---|
service_databases.tf |
Service databases, users, and grants — add names to local.service_databases |
mysqld_exporter_user.tf |
Monitoring user (mysqld_exporter) with PROCESS, BINLOG MONITOR, SELECT |
providers.tf |
MySQL provider config (reads from SOPS) |
secrets.sops.yaml |
Encrypted: endpoint, terraform credentials, per-user passwords |
Add a new database by appending its name to local.service_databases in service_databases.tf.
postgres¶
Manages PostgreSQL databases, roles, and grants via the cyrilgdn/postgresql provider.
| File | Purpose |
|---|---|
service_databases.tf |
Service roles, databases, and grants — add names to local.service_databases |
read_only_users.tf |
Read-only roles (e.g. grafana) granted pg_read_all_data |
providers.tf |
PostgreSQL provider config (reads host:port and credentials from SOPS) |
secrets.sops.yaml |
Encrypted: host:port, terraform credentials, per-user passwords |
Add a new service database by appending its name to local.service_databases in service_databases.tf. Read-only accounts go in read_only_users.tf.
Backend¶
State is stored in an S3-compatible backend (Backblaze B2, terraform bucket). The backend config is SOPS-encrypted:
# backend.sops.tfbackend contains bucket, endpoint, access_key, secret_key
sops -d ../backend.sops.tfbackend > ../.decrypted~backend.sops.tfbackend
terraform init -backend-config=../.decrypted~backend.sops.tfbackend
Decrypted intermediary
The .decrypted~backend.sops.tfbackend file is a temporary plaintext copy. It is gitignored (.decrypted~* pattern) and must never be committed.
Providers¶
| Provider | Version | Purpose |
|---|---|---|
carlpett/sops |
~> 1.1 |
Read SOPS-encrypted files as Terraform data sources |
goauthentik/authentik |
~> 2026.0 |
Identity configuration, flows, providers, and policies |
gmichels/adguard |
~> 1.7 |
AdGuard Home configuration |
cloudflare/cloudflare |
~> 5.0 |
Cloudflare resources |
oracle/oci |
8.10.0 |
Oracle Cloud Infrastructure resources |
Backblaze/b2 |
~> 0.14.0 |
Backblaze B2 buckets and application keys |
petoju/mysql |
~> 3.0 |
MariaDB databases, users, and grants |
cyrilgdn/postgresql |
~> 1.25 |
PostgreSQL databases, roles, and grants |
hashicorp/random |
~> 3.0 |
Random password generation |
Running Terraform¶
cd terraform/<module>
# Decrypt backend config (required once per session)
sops -d ../backend.sops.tfbackend > ../.decrypted~backend.sops.tfbackend
# Init, plan, apply
terraform init -backend-config=../.decrypted~backend.sops.tfbackend
terraform plan
terraform apply
# Clean up
rm ../.decrypted~backend.sops.tfbackend
Never commit .decrypted~* files
These files contain plaintext secrets. They are gitignored by default, but double-check before committing.