infrapuzzle/AGENTS.md

AGENTS.md

Note

Infrapuzzle is the monorepo for my personal infrastructure, encompassing Kubernetes cluster provisioning, workload deployment, DNS management, and IoT monitoring.

Repository Structure & Documentation

This repository is divided into distinct domains, each with its own AGENTS.md or specialized documentation.

1. Bootstrap (bootstrap/)

• Purpose: Provisioning the single-node Kubernetes cluster (Haumdaucher).
• Tool: Kubespray (Ansible).
• Key File: init.sh (Source of Truth for versioning).
• Read: bootstrap/AGENTS.md

2. Kubernetes Workloads (k8s/)

• Purpose: Deploying applications and services to the cluster.
• Method: GitOps-style directory structure (Namespace = Folder).
• Constraints: Enforces ingress-nginx, cert-manager (Let's Encrypt), and git-crypt for secrets.
• Read: k8s/AGENTS.md

3. Terraform (terraform/)

• Purpose: Infrastructure as Code for external resources, primarily DNS.
• Provider: OVH (ovh/ovh).
• Scope:
  • DNS Zones: haumdaucher.de, moritzgraf.de, ameliegraf.de, and others.
  • Mail Config: Google Workspace MX/SPF/DKIM records.
  • Cluster IP: Points domains to the Haumdaucher node IP (136.243.23.215).
• Usage:

  cd terraform
  terraform init
  terraform apply
  

4. Monitoring (monitoring/)

• Purpose: IoT and physical device monitoring, separate from K8s metrics.
• Tool: ESPHome.
• Devices: Temperature sensors, plant monitors (Xiaomi/BLE), ESP32 bridges.
• Usage:

  cd monitoring
  # Flash or update a device
  esphome run config/<device>.secret.yml
  

• Network: Devices typically operate on static IPs in the 192.168.x.x range.

5. Knowledge Wiki & OpenClaw Tasks (knowledge-wiki/)

• Purpose: Shared personal knowledge wiki and task dispatch between OpenClaw (mobile/Telegram concierge) and Antigravity (local pair programming agent).
• Location: Native subfolder knowledge-wiki/ inside infrapuzzle (Git: git.moritzgraf.de/moritz/infrapuzzle.git, branch master).
• Queue File: knowledge-wiki/tasks/antigravity.md.
• Workflow for Antigravity:
  • When the user asks to check tasks or pick up work from OpenClaw:
    1. Pull latest: git pull --rebase origin master
    2. Read knowledge-wiki/tasks/antigravity.md to see pending items.
    3. Implement the chosen task in the appropriate repository files.
    4. Move the task to ## ✅ Completed Tasks with completion details and commit info.
    5. Push back: git commit -am "chore(tasks): complete <task>" && git push origin master.
  • When Antigravity needs knowledge about family, home, servers, or setup:
    • Read notes in knowledge-wiki/concepts/ and knowledge-wiki/entities/.

Global Constraints

• Secrets: git-crypt is used extensively. Ensure you have the unlock key before editing *.secret files.
• Identity:
  • Cluster: haumdaucher
  • Primary Domain: haumdaucher.de
  • User Identity: moritzgraf.de