infra/.planning/codebase/INTEGRATIONS.md

External Integrations

Analysis Date: 2026-02-23

APIs & External Services

Cloudflare:

• DNS management (public domain viktorbarzin.me)
• Tunnel for public HTTPS access
• Account ID: cloudflare_account_id in tfvars
• SDK/Client: cloudflare/cloudflare Terraform provider v4.52.5
• Auth: API token stored in cloudflare_api_key, email in cloudflare_email, zone ID in cloudflare_zone_id, tunnel ID in cloudflare_tunnel_id
• Implementation: stacks/platform/modules/cloudflared/ deploys Cloudflare tunnel daemon

GitHub:

• Git repository hosting and CI/CD webhook source
• Webhook endpoint: https://webhook.viktorbarzin.me/ (handled by stacks/webhook_handler/)
• Auth: Git token in webhook_handler_git_token (terraform.tfvars)
• User: webhook_handler_git_user (terraform.tfvars)
• SSH key: webhook_handler_ssh_key for Git operations (secret in K8s)

Facebook Messenger:

• Chatbot integration via webhook
• Webhook endpoint: https://webhook.viktorbarzin.me/ (receives webhook_handler_fb_*)
• Auth tokens: webhook_handler_fb_verify_token, webhook_handler_fb_page_token, webhook_handler_fb_app_secret (all in tfvars)

Slack:

• Alert routing and notifications
• Webhook URL: alertmanager_slack_api_url (terraform.tfvars)
• Integration: Alertmanager alerts from stacks/platform/modules/monitoring/ sent to Slack
• CrowdSec integration: Security events to Slack via stacks/platform/modules/crowdsec/

Hetrix Tools:

• Uptime monitoring service
• Status page redirects: https://hetrixtools.com/r/38981b548b5d38b052aca8d01285a3f3/ and https://hetrixtools.com/r/2ba9d7a5e017794db0fd91f0115a8b3b/
• Implementation: Traefik middleware redirect in stacks/platform/modules/monitoring/main.tf

Tiny Tuya:

• Smart device control via tuya-bridge
• Auth: tiny_tuya_service_secret (terraform.tfvars)

Mailgun:

• SMTP relay for outgoing mail (primary relay host)
• Relay: [smtp.eu.mailgun.org]:587 (Postfix DEFAULT_RELAY_HOST)
• Auth: SASL credentials in sasl_passwd (mailserver config)
• Alternative: SendGrid (commented out, previously used)

Home Assistant:

• Home automation integration
• API token: haos_api_token (terraform.tfvars)
• Access: https://ha-london.viktorbarzin.me, https://ha-sofia.viktorbarzin.me

Proxmox:

• Virtualization platform for VM provisioning
• Host: 192.168.1.127:8006 (proxmox_pm_api_url)
• Auth: API token ID terraform-prov@pve!terrform-prov, secret in tfvars
• Provider: telmate/proxmox v3.0.2-rc07
• Access: IDRAC credentials for physical server monitoring (idrac_host, idrac_username, idrac_password)

Data Storage

Databases:

• MySQL 9.2.0

  • Connection: mysql.dbaas.svc.cluster.local:3306 (K8s internal)
  • Client: Direct port access (no ORM in core infrastructure)
  • Root password: dbaas_root_password (tfvars)
  • Storage: NFS PV at /mnt/main/mysql

• PostgreSQL 16.4-bullseye (with PostGIS + PGVector)

  • Connection: postgresql.dbaas:5432 (K8s internal)
  • Connection via PgBouncer: pgbouncer.authentik:6432 (Authentik only)
  • Root password: dbaas_postgresql_root_password (tfvars)
  • Root password for pgbouncer: pgbouncer_root_password (tfvars)
  • Admin UI: PgAdmin at pma.viktorbarzin.me
  • PgAdmin password: dbaas_pgadmin_password (tfvars)
  • Storage: NFS PV at /mnt/main/postgresql

File Storage:

• NFS (Primary)
  • Host: 10.0.10.15 (TrueNAS)
  • Mount path: /mnt/main/
  • Subdirectories: per-service (e.g., /mnt/main/immich/, /mnt/main/affine/, /mnt/main/mailserver/, etc.)
  • Configuration: secrets/nfs_directories.txt (git-crypt encrypted)
  • Export script: secrets/nfs_exports.sh (updates TrueNAS exports)

Caching:

• Redis/redis-stack:latest
  • Connection: redis.redis.svc.cluster.local (K8s internal, no explicit port in code)
  • Databases: DB 2 (Gramps Web broker), DB 3 (Gramps Web rate limiting)
  • Storage: Persistent volume for data durability
  • Implementation: stacks/platform/modules/redis/main.tf

Authentication & Identity

Auth Provider:

• Authentik (self-hosted OIDC/OAuth2 identity provider)
  • URL: https://authentik.viktorbarzin.me
  • API: /api/v3/ endpoint
  • Token: authentik_api_token (terraform.tfvars)
  • Database: PostgreSQL via postgresql.dbaas:5432 (also PgBouncer at pgbouncer.authentik:6432)
  • Secret key: authentik_secret_key (terraform.tfvars)
  • Postgres password: authentik_postgres_password (terraform.tfvars)
  • K8s OIDC: Issuer https://authentik.viktorbarzin.me/application/o/kubernetes/, client kubernetes (public)
  • Implementation: stacks/platform/modules/authentik/main.tf + Helm chart
  • Traefik integration: Forward auth via protected = true in ingress_factory

RBAC:

• Kubernetes API auth via Authentik OIDC
• SSH keys: ssh_private_key (terraform.tfvars)
• Implementation: stacks/platform/modules/rbac/ + stacks/platform/modules/k8s-portal/

Monitoring & Observability

Error Tracking:

• None detected - alerts routed to Slack instead

Metrics:

• Prometheus - Time series database
  • Scrape endpoints: cluster nodes, services, Proxmox IDRAC, Tuya devices, Home Assistant
  • Implementation: stacks/platform/modules/monitoring/
  • Health check: CronJob monitors prometheus-server pod and alerts to https://webhook.viktorbarzin.me/fb/message-viktor if down

Logs:

• Loki 3.6.5 (single binary) + Alloy v1.13.0 (DaemonSet collector)
  • Retention: 7 days
  • Storage: NFS PV at /mnt/main/loki/loki (15Gi), WAL on tmpfs (2Gi)
  • Alerting: HighErrorRate, PodCrashLoopBackOff, OOMKilled (ConfigMap loki-alert-rules)

Visualization:

• Grafana
  • Database: PostgreSQL via dbaas
  • Admin password: grafana_admin_password (tfvars)
  • DB password: grafana_db_password (tfvars)

Status Pages:

• Hetrix Tools (external uptime monitoring)
• Uptime Kuma (self-hosted, stacks/platform/modules/uptime-kuma/)

CI/CD & Deployment

Hosting:

• Proxmox 8.x (hypervisor)
• Kubernetes 1.34.2 (application platform)
• Cloudflare Tunnel (public ingress)

CI Pipeline:

• Woodpecker CI (self-hosted, stacks/woodpecker/)
  • Hosted at: https://ci.viktorbarzin.me
  • Config: .woodpecker/ in repo root
  • Triggers: Git push, scheduled jobs
  • Applies platform stack automatically on merge to master

GitOps:

• Webhook-handler service: receives GitHub webhooks, triggers deployments
  • Endpoint: https://webhook.viktorbarzin.me/
  • Auth: Secret token webhook_handler_secret (tfvars)
  • Can update K8s deployments via RBAC
  • Implementation: stacks/webhook_handler/main.tf, image viktorbarzin/webhook-handler:latest

Environment Configuration

Required env vars (terraform.tfvars - git-crypt encrypted):

• cloudflare_api_key, cloudflare_email, cloudflare_zone_id, cloudflare_tunnel_id, cloudflare_tunnel_token
• dbaas_root_password, dbaas_postgresql_root_password, dbaas_pgadmin_password
• authentik_secret_key, authentik_postgres_password, authentik_api_token
• proxmox_pm_api_url, proxmox_pm_api_token_id, proxmox_pm_api_token_secret
• alertmanager_slack_api_url, alertmanager_account_password
• webhook_handler_secret, webhook_handler_fb_verify_token, webhook_handler_fb_page_token, webhook_handler_fb_app_secret, webhook_handler_git_token, webhook_handler_git_user, webhook_handler_ssh_key
• vaultwarden_smtp_password, mailserver_accounts, postfix_account_aliases, sasl_passwd
• crowdsec_enroll_key, crowdsec_db_password, crowdsec_dash_api_key, crowdsec_dash_machine_id, crowdsec_dash_machine_password
• headscale_config, headscale_acl
• monitoring_idrac_username, monitoring_idrac_password, tiny_tuya_service_secret, haos_api_token, pve_password, grafana_admin_password, grafana_db_password
• k8s_users (map of SSH keys for K8s RBAC)

Secrets location:

• Primary: terraform.tfvars (git-crypt encrypted at rest, decrypted during terragrunt apply)
• K8s Secrets: Created by Terraform from tfvars into namespaces (see stacks/platform/modules/*/main.tf)
• TLS certificates: secrets/ directory (symlinked into stacks as secrets/ → ../../secrets)

Webhooks & Callbacks

Incoming (Webhook endpoints):

• GitHub webhooks: https://webhook.viktorbarzin.me/ (deployment triggers)
• Facebook Messenger webhooks: https://webhook.viktorbarzin.me/ (chatbot messages)
• Health alerts: CronJob sends to https://webhook.viktorbarzin.me/fb/message-viktor if Prometheus is down

Outgoing:

• Alertmanager → Slack webhook: alertmanager_slack_api_url
• CrowdSec → Slack webhook: same as alertmanager
• Hetrix Tools status pages: redirect middleware instead of direct integration

Integration Patterns

Terraform Secrets Injection:

• Template pattern: templatefile("${path.module}/values.yaml", { var1 = var.value1, ... })
• Direct env injection: K8s ConfigMap/Secret created from tfvars variables
• Example: stacks/platform/modules/crowdsec/main.tf renders Helm values with interpolated secrets

Internal Service Discovery:

• DNS: Services accessible via <name>.<namespace>.svc.cluster.local
• Examples: mysql.dbaas.svc.cluster.local, redis.redis.svc.cluster.local, postgresql.dbaas.svc.cluster.local

External Service Access:

• Cloudflare Tunnel: Provides public HTTPS for services (no direct internet access needed)
• Traefik Ingress: Routes external traffic to internal K8s services
• Technitium (internal DNS) for .lan domain resolution

---

Integration audit: 2026-02-23