vgui-cicd/Documentation/ArgoCD.md

# ArgoCD Configuration Documentation

## Overview
This directory contains the ArgoCD application manifests for deploying the VorgabenUI application and its dependencies to Kubernetes.

## Files

### Application Manifests

#### `001_pvc.yaml`
- **Purpose**: PersistentVolumeClaim for Django application data
- **Storage**: 2Gi storage with ReadWriteMany access mode
- **Storage Class**: Uses NFS storage class for shared storage across multiple pods
- **Namespace**: vorgabenui

#### `configmap.yaml`
- **Purpose**: Django application configuration
- **Contains**: Environment variables, application settings, version information
- **Namespace**: vorgabenui
- **Version**: 0.990

#### `deployment.yaml`
- **Purpose**: Main application deployment configuration
- **Contains**: Django application container, environment variables, resource limits
- **Replicas**: Configurable replica count for high availability
- **Version**: 0.990

#### `ingress.yaml`
- **Purpose**: External access configuration
- **Host**: Configurable hostname for the application
- **TLS**: SSL/TLS termination configuration
- **Backend**: Routes traffic to the Django application service
- **Ingress Class**: traefik

#### `nfs-pv.yaml`
- **Purpose**: PersistentVolume definition for NFS storage
- **Server**: 192.168.17.199
- **Path**: /mnt/user/kubernetesdata/vorgabenui
- **Access**: ReadWriteMany for multi-pod access
- **Reclaim Policy**: Retain (data preserved after PVC deletion)

#### `nfs-storageclass.yaml`
- **Purpose**: StorageClass definition for NFS volumes
- **Provisioner**: kubernetes.io/no-provisioner (static provisioning)
- **Volume Expansion**: Enabled for growing storage capacity
- **Binding Mode**: Immediate (binds PV to PVC as soon as possible)

#### `diagrammer.yaml`
- **Purpose**: Deployment configuration for the diagram generation service
- **Function**: Handles diagram creation and caching for the application
- **Version**: 0.026

#### `secret.yaml` (Template)
- **Purpose**: Template for Django SECRET_KEY secret
- **Contains**: Secret key configuration for cryptographic operations
- **Namespace**: vorgabenui
- **Generated by**: `deploy-argocd-secret.sh` script
- **Version**: 0.026

#### `secret.yaml` (Template)
- **Purpose**: Template for Django SECRET_KEY secret
- **Contains**: Secret key configuration for cryptographic operations
- **Namespace**: vorgabenui
- **Generated by**: `deploy-argocd-secret.sh` script
- **Version**: 0.026

## MicroK8s Addons Required

### Required Addons
Enable the following MicroK8s addons before deployment:

```bash
# Enable storage and NFS support
sudo microk8s enable storage
sudo microk8s enable nfs

# Enable ingress for external access
sudo microk8s enable ingress

# Enable DNS for service discovery
sudo microk8s enable dns

# Optional: Enable metrics for monitoring
sudo microk8s enable metrics-server
```

### Addon Descriptions

#### `storage`
- **Purpose**: Provides default storage class for persistent volumes
- **Required for**: Basic PVC functionality
- **Note**: Works alongside our custom NFS storage class

#### `nfs`
- **Purpose**: Installs NFS client utilities on all MicroK8s nodes
- **Required for**: Mounting NFS volumes in pods
- **Components**: Installs `nfs-common` package with mount helpers

#### `ingress`
- **Purpose**: Provides Ingress controller for external HTTP/HTTPS access
- **Required for**: `ingress.yaml` to function properly
- **Implementation**: Uses NGINX Ingress Controller

#### `dns`
- **Purpose**: Provides DNS service for service discovery within cluster
- **Required for**: Inter-service communication
- **Note**: Usually enabled by default in MicroK8s

#### `metrics-server` (Optional)
- **Purpose**: Enables resource usage monitoring
- **Required for**: `kubectl top` commands and HPA (Horizontal Pod Autoscaling)
- **Recommended for**: Production monitoring

### Addon Verification
After enabling addons, verify they are running:

```bash
# Check addon status
microk8s status

# Check pods in kube-system namespace
microk8s kubectl get pods -n kube-system

# Check storage classes
microk8s kubectl get storageclass

# Check ingress controller
microk8s kubectl get pods -n ingress
```

### Troubleshooting Addons

#### NFS Addon Issues
```bash
# Check if NFS utilities are installed
which mount.nfs

# Manually install if addon fails
sudo apt update && sudo apt install nfs-common

# Restart MicroK8s after manual installation
sudo microk8s restart
```

#### Ingress Issues
```bash
# Check ingress controller pods
microk8s kubectl get pods -n ingress

# Check ingress services
microk8s kubectl get svc -n ingress

# Test ingress connectivity
curl -k https://vorgabenportal.knowyoursecurity.com
```

#### Storage Issues
```bash
# List available storage classes
microk8s kubectl get storageclass

# Check default storage class
microk8s kubectl get storageclass -o yaml
```

### Storage Architecture
- **Storage Class**: `nfs` - Static provisioning for NFS shares
- **Persistent Volume**: Pre-provisioned PV pointing to NFS server
- **Persistent Volume Claim**: Claims the NFS storage for application use
- **Access Mode**: ReadWriteMany allows multiple pods to access the same data

### NFS Server Setup
On the NFS server (192.168.17.199), ensure the following:

```bash
# Create the shared directory
sudo mkdir -p /mnt/user/kubernetesdata/vorgabenui
sudo chmod 755 /mnt/user/kubernetesdata/vorgabenui

# Add to /etc/exports
echo "/mnt/user/kubernetesdata/vorgabenui *(rw,sync,no_subtree_check,no_root_squash)" | sudo tee -a /etc/exports

# Export the directory
sudo exportfs -a
sudo systemctl restart nfs-kernel-server
```

## Configuration Management

### ConfigMap Deployment

The Django application uses a ConfigMap for application configuration. The ConfigMap contains environment variables and settings for the Django application.

#### ConfigMap File
- **File**: `configmap.yaml`
- **Name**: `django-config`
- **Namespace**: `vorgabenui`
- **Version**: 0.990

#### Configuration Contents
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: django-config
  namespace: vorgabenui
data:
  # Django Configuration
  DEBUG: "false"
  DJANGO_ALLOWED_HOSTS: "vorgabenportal.knowyoursecurity.com,localhost,127.0.0.1,*"
  DJANGO_SETTINGS_MODULE: "VorgabenUI.settings"
  
  # Application Configuration
  LANGUAGE_CODE: "de-ch"
  TIME_ZONE: "UTC"
  
  # Static and Media Configuration
  STATIC_URL: "/static/"
  MEDIA_URL: "/media/"
  
  # Application Version
  VERSION: "0.990"
  
  # Database Configuration (for future use)
  # DATABASE_ENGINE: "django.db.backends.sqlite3"
  # DATABASE_NAME: "/app/data/db.sqlite3"
  
  # Security Configuration
  # CSRF_TRUSTED_ORIGINS: "https://vorgabenportal.knowyoursecurity.com"
```

#### Deployment Script
The ConfigMap is deployed using the `deploy-argocd-configmap.sh` script located in the `scripts/` directory.

**Script Usage**:
```bash
# Deploy ConfigMap
./scripts/deploy-argocd-configmap.sh

# Verify ConfigMap only (no deployment)
./scripts/deploy-argocd-configmap.sh --verify-only

# Dry-run (show what would be deployed)
./scripts/deploy-argocd-configmap.sh --dry-run
```

**Script Features**:
- Validates kubectl availability
- Checks if ConfigMap file exists
- Creates namespace if it doesn't exist
- Applies ConfigMap configuration
- Verifies successful deployment
- Provides detailed logging and error handling

### Secret Deployment

The Django application requires a secure SECRET_KEY for cryptographic signing. This is managed through a Kubernetes Secret.

#### Secret Configuration
- **Secret Name**: `vorgabenui-secrets`
- **Secret Key**: `vorgabenui_secret`
- **Namespace**: `vorgabenui`

#### Secret Generation
The secret is automatically generated using the `deploy-argocd-secret.sh` script, which creates a secure Django-style SECRET_KEY.

**Script Usage**:
```bash
# Generate and deploy new secret
./scripts/deploy-argocd-secret.sh

# Verify existing secret only (no new generation)
./scripts/deploy-argocd-secret.sh --verify-only

# Dry-run (show what would be done)
./scripts/deploy-argocd-secret.sh --dry-run
```

**Secret Generation Features**:
- Generates secure 50-character SECRET_KEY using Python
- Uses Django-style character set (letters, digits, special characters)
- Creates or updates the secret in the vorgabenui namespace
- Verifies secret deployment and accessibility
- Tests secret accessibility in Django pods

#### Environment Variable Reference
The deployment.yaml references the secret through environment variables:

```yaml
env:
  # Secret configuration
  - name: VORGABENUI_SECRET
    valueFrom:
      secretKeyRef:
        name: vorgabenui-secrets
        key: vorgabenui_secret
```

#### Security Notes
- The SECRET_KEY is never logged or displayed in full
- Only the first 10 characters are shown during generation for verification
- The secret is stored securely in Kubernetes and only accessible to authorized pods
- Regular secret rotation is recommended for production environments

## Deployment Order

1. **StorageClass** (`nfs-storageclass.yaml`) - Defines NFS storage class
2. **PersistentVolume** (`nfs-pv.yaml`) - Creates the NFS volume
3. **PersistentVolumeClaim** (`001_pvc.yaml`) - Claims storage for application
4. **ConfigMap** (`configmap.yaml`) - Deploy Django configuration
5. **Secret** (`secret.yaml`) - Generate and deploy Django SECRET_KEY
6. **Application Deployments** (`deployment.yaml`, `diagrammer.yaml`) - Deploy application services
7. **Ingress** (`ingress.yaml`) - Configure external access

## Configuration Notes

### Namespace
All resources are deployed to the `vorgabenui` namespace.

### Storage Sizing
- Current allocation: 2Gi
- Volume expansion is enabled through the StorageClass
- Monitor usage and adjust PVC size as needed

### Access Control
- NFS export uses `no_root_squash` for container root access
- Ensure proper network security between Kubernetes nodes and NFS server
- Consider implementing network policies for additional security

## Troubleshooting

### Common Issues

#### Mount Failures
- **Error**: "bad option; for several filesystems you might need a /sbin/mount.<type> helper program"
- **Solution**: Install NFS client utilities or enable NFS addon in MicroK8s

#### Permission Issues
- **Error**: Permission denied when accessing mounted volume
- **Solution**: Check NFS export permissions and ensure `no_root_squash` is set

#### Network Connectivity
- **Error**: Connection timeout to NFS server
- **Solution**: Verify network connectivity and firewall rules between nodes and NFS server

### Debug Commands
```bash
# Check PVC status
kubectl get pvc -n vorgabenui

# Check PV status
kubectl get pv

# Describe PVC for detailed information
kubectl describe pvc django-data-pvc -n vorgabenui

# Check pod mount status
kubectl describe pod <pod-name> -n vorgabenui
```

## Maintenance

### Backup Strategy
- The NFS server should have regular backups of `/mnt/user/kubernetesdata/vorgabenui`
- Consider snapshot capabilities if using enterprise NFS solutions

### Monitoring
- Monitor NFS server performance and connectivity
- Track storage usage and plan capacity upgrades
- Monitor pod restarts related to storage issues

### Updates
- When updating storage configuration, update PV first, then PVC
- Test changes in non-production environment first
- Ensure backward compatibility when modifying NFS exports