From 1b016c49f227a96438dd92f23d297b8b1fcf3805 Mon Sep 17 00:00:00 2001 From: "Adrian A. Baumann" Date: Mon, 24 Nov 2025 15:55:27 +0100 Subject: [PATCH] ArgoCD-Documentation added --- Documentation/ArgoCD.md | 241 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 Documentation/ArgoCD.md diff --git a/Documentation/ArgoCD.md b/Documentation/ArgoCD.md new file mode 100644 index 0000000..7f879ec --- /dev/null +++ b/Documentation/ArgoCD.md @@ -0,0 +1,241 @@ +# 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 + +#### `deployment.yaml` +- **Purpose**: Main application deployment configuration +- **Contains**: Django application container, environment variables, resource limits +- **Replicas**: Configurable replica count for high availability + +#### `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 + +#### `nfs-pv.yaml` +- **Purpose**: PersistentVolume definition for NFS storage +- **Server**: 192.168.17.199 +- **Path**: /mnt/user/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 + +## NFS Storage Configuration + +### Prerequisites +1. NFS server must be running at 192.168.17.199 +2. The directory `/mnt/user/vorgabenui` must exist and be exported +3. Kubernetes nodes must have NFS client utilities installed +4. For MicroK8s: `microk8s enable nfs` + +## 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://your-domain.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/vorgabenui +sudo chmod 755 /mnt/user/vorgabenui + +# Add to /etc/exports +echo "/mnt/user/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 +``` + +## 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. **Application Deployments** (`deployment.yaml`, `diagrammer.yaml`) - Deploy application services +5. **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. 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 -n vorgabenui +``` + +## Maintenance + +### Backup Strategy +- The NFS server should have regular backups of `/mnt/user/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 \ No newline at end of file