Sankofa/gitops

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:

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:

kubectl apply -f apps/argocd/root-application.yaml

Deploy to Specific Environment

# 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:

kubectl apply -f infrastructure/claims/vm-claim-example.yaml

2. Monitor the resource:

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

# Check ArgoCD application status
kubectl get applications -n argocd

# View sync logs
argocd app logs <app-name> --tail=100

Crossplane Issues

# Check provider status
kubectl get providerconfig -n crossplane-system

# View resource events
kubectl describe proxmoxvm <vm-name>

Related Documentation

• ArgoCD Documentation
• Crossplane Documentation
• Kustomize Documentation