Initial Phoenix Sankofa Cloud setup

- Complete project structure with Next.js frontend - GraphQL API backend with Apollo Server - Portal application with NextAuth - Crossplane Proxmox provider - GitOps configurations - CI/CD pipelines - Testing infrastructure (Vitest, Jest, Go tests) - Error handling and monitoring - Security hardening - UI component library - Documentation
2025-11-28 12:54:33 -08:00
commit 6f28146ac3
229 changed files with 43136 additions and 0 deletions
--- a/gitops/README.md
+++ b/gitops/README.md
@@ -0,0 +1,138 @@
+# GitOps Repository
+
+This repository contains all infrastructure and application definitions managed via ArgoCD GitOps.
+
+## Structure
+
+```
+gitops/
+├── base/                    # Base Kubernetes resources
+│   ├── namespaces/         # Namespace definitions
+│   ├── rbac/               # RBAC roles and bindings
+│   └── kustomization.yaml  # Base kustomization
+├── overlays/               # Environment-specific overlays
+│   ├── dev/               # Development environment
+│   ├── staging/           # Staging environment
+│   └── prod/              # Production environment
+├── apps/                   # ArgoCD Application definitions
+│   ├── rancher/           # Rancher installation
+│   ├── crossplane/        # Crossplane installation
+│   ├── argocd/            # ArgoCD self-config
+│   ├── vault/             # Vault installation
+│   ├── monitoring/        # Prometheus, Grafana, Loki
+│   └── portal/            # Portal deployment
+├── infrastructure/         # Crossplane infrastructure definitions
+│   ├── xrds/              # Composite Resource Definitions
+│   ├── compositions/      # Composition templates
+│   └── claims/           # Example claims
+└── templates/             # Reusable templates
+    ├── vm/               # VM templates
+    ├── cluster/          # K8s cluster templates
+    └── network/          # Network templates
+```
+
+## Usage
+
+### Bootstrap ArgoCD
+
+1. Install ArgoCD on your cluster:
+```bash
+kubectl create namespace argocd
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+```
+
+2. Apply the root ArgoCD Application:
+```bash
+kubectl apply -f apps/argocd/root-application.yaml
+```
+
+### Deploy to Specific Environment
+
+```bash
+# Development
+kubectl apply -k overlays/dev/
+
+# Production
+kubectl apply -k overlays/prod/
+```
+
+## Environment Configuration
+
+Each overlay directory contains:
+- `kustomization.yaml` - Environment-specific patches
+- `config/` - ConfigMaps and Secrets
+- `patches/` - Strategic merge patches
+
+## Infrastructure as Code
+
+Crossplane XRDs and Compositions are defined in `infrastructure/`. These enable high-level resource provisioning through the portal.
+
+### Example: Creating a VM
+
+1. Create a claim:
+```bash
+kubectl apply -f infrastructure/claims/vm-claim-example.yaml
+```
+
+2. Monitor the resource:
+```bash
+kubectl get proxmoxvm web-server-01
+kubectl describe proxmoxvm web-server-01
+```
+
+### Compositions
+
+Compositions define reusable templates for common resources:
+
+- `vm-ubuntu.yaml` - Ubuntu VM template
+- Additional compositions can be added for other OS images
+
+### Claims
+
+Claims are user-facing resources that use compositions:
+
+- `vm-claim-example.yaml` - Example VM claim
+
+## GitOps Workflow
+
+1. **Developer** creates/modifies resources in this repository
+2. **Git** triggers ArgoCD sync (or manual sync)
+3. **ArgoCD** applies changes to the cluster
+4. **Crossplane** provisions infrastructure based on claims
+5. **Monitoring** tracks resource status
+
+## Best Practices
+
+- Always use overlays for environment-specific configurations
+- Keep base configurations generic and reusable
+- Use Kustomize for configuration management
+- Document all custom compositions
+- Version control all infrastructure changes
+
+## Troubleshooting
+
+### ArgoCD Sync Issues
+
+```bash
+# Check ArgoCD application status
+kubectl get applications -n argocd
+
+# View sync logs
+argocd app logs <app-name> --tail=100
+```
+
+### Crossplane Issues
+
+```bash
+# Check provider status
+kubectl get providerconfig -n crossplane-system
+
+# View resource events
+kubectl describe proxmoxvm <vm-name>
+```
+
+## Related Documentation
+
+- [ArgoCD Documentation](https://argo-cd.readthedocs.io/)
+- [Crossplane Documentation](https://crossplane.io/docs/)
+- [Kustomize Documentation](https://kustomize.io/)