forked from roger/k3s-cluster
fix argocd rbac and create agents.md
This commit is contained in:
Roger Oriol
246
AGENTS.md
Normal file
246
AGENTS.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# AGENTS.md - Guide for Coding Agents
|
||||
|
||||
This file provides essential information for AI coding agents working with this Kubernetes cluster project.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This repository contains Kubernetes manifests for a K3s cluster running self-hosted services on the `rogi.casa` domain. The cluster is managed via **GitOps using ArgoCD** - all changes to the cluster are deployed automatically from this Git repository.
|
||||
|
||||
**⚠️ CRITICAL: Permission Model**
|
||||
|
||||
You **DO NOT** have permission to push changes to this repository. Before applying any changes to the cluster:
|
||||
1. Make the necessary code changes to the manifests
|
||||
2. Clearly present the changes to the user
|
||||
3. Ask the user to review and push the changes
|
||||
4. Wait for confirmation that changes have been pushed
|
||||
5. Only then will ArgoCD automatically deploy the changes to the cluster
|
||||
|
||||
## Architecture & GitOps Workflow
|
||||
|
||||
### ArgoCD App-of-Apps Pattern
|
||||
|
||||
This project uses ArgoCD's "app-of-apps" pattern:
|
||||
|
||||
```
|
||||
argocd-bootstrap.yaml (root Application)
|
||||
↓
|
||||
argocd/apps/ (directory containing all Application manifests)
|
||||
↓
|
||||
Individual Applications (one per service directory)
|
||||
↓
|
||||
Kubernetes manifests in each service directory (e.g., pihole/, homeassistant/)
|
||||
```
|
||||
|
||||
### Deployment Flow
|
||||
|
||||
1. You make changes to Kubernetes manifests in the repository
|
||||
2. User reviews and pushes changes to the `main` branch
|
||||
3. ArgoCD detects changes (automatically or on sync)
|
||||
4. ArgoCD applies changes to the cluster with `prune: true` and `selfHeal: true`
|
||||
5. Cluster state converges to match the Git state
|
||||
|
||||
### Key Files
|
||||
|
||||
- **`argocd-bootstrap.yaml`**: The root Application that bootstraps ArgoCD. Points to `argocd/apps/` directory. This is the only file that needs manual `kubectl apply` during initial setup.
|
||||
- **`argocd/apps/project.yaml`**: ArgoCD AppProject defining permissions for all applications
|
||||
- **`argocd/apps/*.yaml`**: Individual ArgoCD Application manifests (one per service)
|
||||
- **`argocd/gen-apps.sh`**: Script to regenerate all ArgoCD manifests from the `APPS` array
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
k3s-cluster/
|
||||
├── argocd-bootstrap.yaml # Root ArgoCD Application (app-of-apps)
|
||||
├── argocd/
|
||||
│ ├── apps/ # Individual ArgoCD Application manifests
|
||||
│ │ ├── project.yaml # AppProject definition
|
||||
│ │ ├── pihole.yaml # Application for pihole/
|
||||
│ │ ├── homeassistant.yaml # Application for homeassistant/
|
||||
│ │ └── ... # One per service
|
||||
│ ├── gen-apps.sh # Generates argocd/apps/* manifests
|
||||
│ └── ingress.yaml # ArgoCD's own ingress
|
||||
├── <service-name>/ # Each service has its own directory
|
||||
│ ├── namespace.yaml # (Optional) Namespace definition
|
||||
│ ├── deployment.yaml # Main deployment/statefulset
|
||||
│ ├── service.yaml # Service definition
|
||||
│ ├── ingress.yaml # Ingress configuration
|
||||
│ ├── configmap.yaml # (Optional) ConfigMaps
|
||||
│ ├── pvc.yaml # (Optional) PersistentVolumeClaims
|
||||
│ └── secret.yaml # (Optional) Secrets (rarely committed)
|
||||
├── cert-manager/ # cert-manager installation manifests
|
||||
├── nas/ # External NAS service configuration
|
||||
├── monitoring/ # Prometheus + Grafana stack
|
||||
└── README.md # Comprehensive project documentation
|
||||
```
|
||||
|
||||
## Current Services
|
||||
|
||||
The cluster runs these services (each in its own directory):
|
||||
|
||||
- **argocd** - GitOps continuous delivery platform
|
||||
- **cert-manager** - SSL certificate management (Let's Encrypt)
|
||||
- **fava** - Beancount accounting web interface
|
||||
- **gitea** - Self-hosted Git server
|
||||
- **glance** - Personal dashboard
|
||||
- **gym-tracker** - Workout tracking application
|
||||
- **homeassistant** - Home automation
|
||||
- **jellyfin** - Media server
|
||||
- **litellm** - LLM proxy
|
||||
- **minecraft-server** - Minecraft server
|
||||
- **monitoring** - Prometheus + Grafana
|
||||
- **myorg-assistant** - Organization assistant
|
||||
- **n8n** - Workflow automation
|
||||
- **nas** - External NAS proxy
|
||||
- **openwebui** - Web UI for LLMs
|
||||
- **phoenix** - AI observability platform
|
||||
- **pihole** - Network-wide ad blocking
|
||||
- **platform-engineer** - Platform engineering tools
|
||||
- **qbittorrent** - Torrent client
|
||||
- **searxng** - Meta search engine
|
||||
- **vaultwarden** - Password manager (Bitwarden compatible)
|
||||
|
||||
## How to Make Changes
|
||||
|
||||
### Adding a New Service
|
||||
|
||||
1. Create a new directory: `mkdir new-service`
|
||||
2. Create Kubernetes manifests in `new-service/`:
|
||||
- `namespace.yaml` (if dedicated namespace needed)
|
||||
- `deployment.yaml` or `statefulset.yaml`
|
||||
- `service.yaml`
|
||||
- `ingress.yaml`
|
||||
- Any ConfigMaps, Secrets, PVCs needed
|
||||
3. Add the service to `argocd/gen-apps.sh`:
|
||||
- Add a line to the `APPS` array: `"new-service|namespace|new-service|true|true"`
|
||||
- Format: `name|namespace|path|recurse|validate`
|
||||
4. Run `./argocd/gen-apps.sh` to regenerate ArgoCD manifests
|
||||
5. **Present changes to user for review and push**
|
||||
|
||||
### Modifying an Existing Service
|
||||
|
||||
1. Edit the relevant manifest(s) in the service directory
|
||||
2. If changing ArgoCD configuration, also update `argocd/gen-apps.sh` and regenerate
|
||||
3. **Present changes to user for review and push**
|
||||
|
||||
### Removing a Service
|
||||
|
||||
1. Remove the service directory: `rm -rf service-name/`
|
||||
2. Remove from `APPS` array in `argocd/gen-apps.sh`
|
||||
3. Run `./argocd/gen-apps.sh` to regenerate
|
||||
4. **Present changes to user for review and push**
|
||||
5. ArgoCD will automatically prune the resources from the cluster
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Ingress Configuration
|
||||
|
||||
Each service has its own `ingress.yaml` with:
|
||||
- `ingressClassName: traefik` (K3s default)
|
||||
- TLS configured with `cert-manager.io/cluster-issuer: letsencrypt-prod`
|
||||
- Host-based routing (e.g., `pihole.rogi.casa`)
|
||||
|
||||
Example:
|
||||
```yaml
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: pihole
|
||||
namespace: pihole
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: letsencrypt-prod
|
||||
spec:
|
||||
ingressClassName: traefik
|
||||
tls:
|
||||
- hosts:
|
||||
- pihole.rogi.casa
|
||||
secretName: pihole-tls
|
||||
rules:
|
||||
- host: pihole.rogi.casa
|
||||
http:
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: pihole-web
|
||||
port:
|
||||
number: 80
|
||||
```
|
||||
|
||||
### Resource Management
|
||||
|
||||
- Each service typically has its own namespace
|
||||
- Use ResourceRequests and Limits for all containers
|
||||
- PVCs for persistent data
|
||||
- ConfigMaps for configuration files
|
||||
|
||||
## Important Notes
|
||||
|
||||
### What You CAN Do
|
||||
|
||||
- Read and understand all manifests
|
||||
- Create new manifest files
|
||||
- Modify existing manifest files
|
||||
- Run `./argocd/gen-apps.sh` to regenerate ArgoCD manifests
|
||||
- Explain how the cluster works
|
||||
- Troubleshoot issues by reading manifests
|
||||
|
||||
### What You CANNOT Do
|
||||
|
||||
- Push changes to the Git repository (no push permissions)
|
||||
- Directly apply manifests with `kubectl apply` (unless explicitly asked)
|
||||
- Access the Kubernetes cluster directly (unless explicitly configured)
|
||||
- Create secrets that should remain private (those are managed manually)
|
||||
|
||||
### Secrets Management
|
||||
|
||||
Secrets are generally **not committed to the repository**. They must be created manually in the cluster:
|
||||
```bash
|
||||
kubectl create secret docker-registry gitea-registry \
|
||||
--docker-server=gitea.rogi.casa \
|
||||
--docker-username=<user> \
|
||||
--docker-password=<token> \
|
||||
-n <namespace>
|
||||
```
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
When asked to make changes:
|
||||
|
||||
1. **Understand** the current state by reading relevant files
|
||||
2. **Modify** the manifests (create/edit files)
|
||||
3. **Regenerate** ArgoCD manifests if needed (`./argocd/gen-apps.sh`)
|
||||
4. **Present** the changes clearly to the user:
|
||||
```
|
||||
I've made the following changes:
|
||||
- Modified pihole/deployment.yaml to update image version
|
||||
- Regenerated argocd/apps/pihole.yaml
|
||||
|
||||
Please review and push these changes to deploy them.
|
||||
```
|
||||
5. **Wait** for user confirmation that changes are pushed
|
||||
6. **Verify** (if possible) that ArgoCD has synced the changes
|
||||
|
||||
## Useful Commands (for reference)
|
||||
|
||||
```bash
|
||||
# Regenerate ArgoCD manifests after modifying gen-apps.sh
|
||||
./argocd/gen-apps.sh
|
||||
|
||||
# Check ArgoCD applications status (requires kubectl access)
|
||||
kubectl get applications -n argocd
|
||||
|
||||
# View logs of a pod (requires kubectl access)
|
||||
kubectl logs -n <namespace> <pod-name>
|
||||
|
||||
# Check ingress status (requires kubectl access)
|
||||
kubectl get ingress -n <namespace>
|
||||
```
|
||||
|
||||
## Questions?
|
||||
|
||||
If you're unsure about anything:
|
||||
1. Read the comprehensive `README.md` in the repository root
|
||||
2. Check existing service directories for examples
|
||||
3. Ask the user for clarification before making changes
|
||||
4. Remember: **never push without explicit user review and approval**
|
||||
Reference in New Issue
Block a user