375 lines
11 KiB
Markdown
375 lines
11 KiB
Markdown
# 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 |