AGENTS.md
Rama main · réplica de lectura del repositorio original.
# AGENTS.md - H8s Development Guide
This repository is H8s (Homernetes), a home Kubernetes infrastructure project using Talos OS.
## Project Overview
This is a **Kubernetes infrastructure-as-code repository** containing:
- Kubernetes manifests (YAML) for cluster configuration
- Kustomize overlays for environment-specific configurations
- Containerfiles/Dockerfiles for custom images
- Nix flake for development environment
- Taskfile for build automation
## Internet Usage is Key
It is **extremely** important that you use the internet. Kubernetes projects change frequently and you will likely implement the wrong thing if you do not utilise it.
## Build Commands
### Development Environment
```bash
# Enter shell with all dependencies (Nix flakes required)
nix shell
# List available tasks
task
```
Always run infrastructure tooling inside this repository's Nix environment (`nix develop` also sets `INFRA_ROOT`).
Bootstrap secrets are SOPS-encrypted in the separate private `h8s-secrets` repo.
Never copy their decrypted values into this public repo.
That repo has its own Nix shell for editing secrets.
### Kubernetes Operations
```bash
# Apply configurations (from nix shell)
kubectl apply -k <directory>
# Apply specific file
kubectl apply -f <file.yaml>
# Dry-run to validate
kubectl apply -k <directory> --dry-run=server
```
## Testing
There are no traditional unit tests in this repository. Validation is done via:
- `kubectl --dry-run=server` - Server-side validation
- Kustomize build validation: `kubectl kustomize <directory>`
- Container build validation: Ensure Containerfile/Dockerfile builds successfully
## Code Style Guidelines
### YAML/Kubernetes Manifests
**File Organization:**
- Use Kustomize for environment-specific configurations
- Structure: `base/` for common resources, `environments/<env>/` for overrides
- Each component should have its own directory with `kustomization.yaml`
**Naming Conventions:**
- Files: kebab-case (e.g., `deployment.yaml`, `corefile-configmap.yaml`)
- Resources: kebab-case matching file names
- Namespaces: lowercase with hyphens (e.g., `coredns-lan`, `monitoring`)
**Required Fields:**
```yaml
apiVersion: <api-group>/v1 # Always specify apiVersion
kind: <ResourceType> # Required
metadata:
name: <resource-name> # Required
namespace: <namespace> # Required for namespaced resources
labels: # Always include app/component labels
app.kubernetes.io/name: <name>
app.kubernetes.io/part-of: <app>
```
**Best Practices:**
- Always set `imagePullPolicy: IfNotPresent` or `Always`
- Include resource limits and requests for all containers
- Use security contexts: `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true`
- Define liveness and readiness probes
- Use pod anti-affinity for high availability
### Secrets Handling
- Store secrets in `environments/prod/secrets/` directory
- Use External Secrets Operator to sync from Vault
- Never commit plain secrets; use SealedSecrets or ESO
- Base64 encode secret values in YAML
### GitOps/ArgoCD
**IMPORTANT**: Remember that if you are applying files locally, that there is a strong chance that ArgoCD will "heal" the manifests back.
When wanting to do this, prompt the user to git commit and push. Never Git commit yourself.
- Applications defined in `ci-cd/argocd/environments/prod/apps/`
- Use Helm charts where possible for upstream resources
- Override values via `values.yaml` in environment overlays
### Container Images
**Dockerfile/Containerfile Conventions:**
- Use specific tags, never `latest` in production
- Multi-stage builds to minimize size
- Run as non-root user
- Include health checks where applicable
**Image Publishing:**
- Images pushed to Harbor (`harbor.okwilkins.dev`)
- Use Cosign for signing
- Use multi-arch builds (linux/amd64, linux/arm64)
## Directory Structure
```text
├── applications
│ ├── bookorbit | Self-hosted library and reading platform.
│ ├── chhoto-url | Self-hosted URL shortener.
│ ├── excalidraw | Self-hosted Excalidraw.
│ ├── forgejo | Self-hosted Git hosting.
│ ├── mazanoke | Browser-based image optimizer.
│ ├── personal-website | My website at okwilkins.dev.
│ └── searxng | Privacy-focused metasearch engine.
├── ci-cd
│ ├── argo-workflows | CI/CD pipelines (WIP).
│ ├── argocd | GitOps CD for Kubernetes resources.
│ └── renovate | Automated dependency updates.
├── images
│ ├── coredns
│ ├── image-buildah
│ └── terraform
├── infrastructure | 8-stage Terraform pipeline for cluster bootstrapping from bare metal via Proxmox and Talos + platform configuration.
├── namespaces | Holds all namespaces for the cluster.
├── networking
│ ├── cert-manager | Certificate controller for the self-hosted certificate authority.
│ ├── cilium | The cluster's eBPF CNI.
│ ├── cloudflared | Allows Cloudflare to ingress internet traffic in.
│ ├── coredns | Home-wide DNS services and ad-blocking.
│ └── gateways | Ingress and networking routing management.
├── observability
│ ├── fluent-bit | Metrics/logs/traces collection, processing and forwarding.
│ ├── grafana | Metrics and log observability.
│ ├── prometheus | Metrics collection.
│ └── victoria-logs | Log storage and query engine.
├── security
│ ├── authelia | Authentication and authorisation server with SSO and MFA.
│ ├── cosign | Secrets to sign containers and binaries going to Harbor.
│ ├── external-secrets-operator | Syncs secrets from Vault into the cluster.
│ ├── trivy-operator | Kubernetes vulnerability and configuration scanning.
│ └── vault | Secrets storage and certificate authority.
└── storage
├── cloudnative-pg | PostgreSQL database management for applications.
├── harbor | Container and binary registry.
└── longhorn | Cluster CSI.
```
It's important to node that if you make changes to this structure that you change both AGENTS.md and README.md to reflect this.
## Common Patterns
### Kustomize Overlay
```yaml
# environments/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
patches:
- path: values-patch.yaml
configMapGenerator:
- behavior: replace
files:
- values.yaml
```
### Adding a New Application
1. Create directory under appropriate component
2. Add `base/` with base manifests and `kustomization.yaml`
3. Add `environments/prod/` with environment-specific overrides
4. Create ArgoCD Application in `ci-cd/argocd/environments/prod/apps/`
## Dependencies
Tools available in nix shell:
- kubectl
- kubernetes-helm
- talosctl
- argocd
- cilium-cli
- task
- jq
- terraform