n8n on Azure Kubernetes Service (AKS)

This repository contains Kubernetes manifests and instructions for deploying n8n workflow automation tool on Azure Kubernetes Service (AKS) with scalability features.

Prerequisites

• Azure subscription
• Azure CLI installed and configured
• kubectl installed and configured
• Helm installed (for cert-manager and nginx-ingress)
• A domain name and ability to configure DNS records

Architecture

The deployment consists of:

• n8n application with horizontal pod autoscaling (2-5 replicas)
• PostgreSQL database for persistence
• Nginx Ingress Controller for routing
• Cert-manager for SSL/TLS certificates
• Persistent volumes for data storage
• Automated cleanup jobs for binary data

Available Scripts

The repository includes several utility scripts to help with deployment and maintenance:

1. scripts/generate-secrets.sh

   • Generates necessary Kubernetes secrets for n8n and PostgreSQL
   • Creates random passwords and encryption keys
   • Outputs secrets in a format ready for kubectl apply

2. scripts/setup-certificates.sh <namespace> <domain> <email> <environment>

   • Sets up SSL/TLS certificates using cert-manager
   • Installs cert-manager if not present
   • Creates Let's Encrypt ClusterIssuer
   • Generates certificates for your domain

3. scripts/validate-deployment.sh <namespace> <environment>

   • Validates the n8n deployment
   • Checks all required resources
   • Verifies pod status and configurations
   • Reports any issues found

4. scripts/collect-diagnostics.sh <namespace>

   • Collects diagnostic information for troubleshooting
   • Gathers logs, events, and resource configurations
   • Creates a compressed archive of all diagnostics

Make all scripts executable after cloning the repository:

chmod +x scripts/*.sh

Quick Start

1. Clone this repository:

   git clone https://github.com/yourusername/n8n-azure-kubernetes.git
   cd n8n-azure-kubernetes

2. Make scripts executable:

   # Make all scripts executable
   chmod +x scripts/*.sh

3. Generate secrets:

   cd scripts
   ./generate-secrets.sh

   Save the generated credentials securely.

4. Update configuration:

   • Edit kubernetes/base/n8n-deployment.yaml to set your domain in N8N_HOST and WEBHOOK_URL
   • Edit kubernetes/base/n8n-ingress.yaml to set your domain in the host field

5. Install prerequisites:

   # Install nginx-ingress controller
   helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
   helm repo update
   helm install nginx-ingress ingress-nginx/ingress-nginx
   
   # Install cert-manager
   helm repo add jetstack https://charts.jetstack.io
   helm repo update
   helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set installCRDs=true

6. Deploy n8n:

   # Create namespace
   kubectl apply -f kubernetes/base/namespace.yaml
   
   # Apply secrets
   kubectl apply -f kubernetes/secrets/generated/
   
   # Apply all other resources
   kubectl apply -f kubernetes/base/

7. Configure DNS:

   • Get the external IP of your ingress controller:

     kubectl get service nginx-ingress-controller

   • Create an A record pointing your domain to this IP address

Scaling

The deployment includes horizontal pod autoscaling based on CPU and memory utilization:

• Minimum replicas: 2
• Maximum replicas: 5
• CPU target utilization: 70%
• Memory target utilization: 80%

Scale up/down behavior is controlled by the HPA configuration in kubernetes/base/n8n-hpa.yaml.

Storage

The deployment uses Azure managed disks with the following configurations:

• PostgreSQL data: 100GB Premium SSD
• n8n data: 50GB Premium SSD
• n8n files: 10GB Premium SSD

Maintenance

A cleanup cronjob runs hourly to remove old binary data files, keeping the most recent 30 files in each directory.

Monitoring

Monitor your deployment using:

# Check n8n pods
kubectl get pods -n n8n

# Check HPA status
kubectl get hpa -n n8n

# View n8n logs
kubectl logs -f -l service=n8n -n n8n

# Check PostgreSQL status
kubectl get pods -l app=postgres -n n8n

Security

• All sensitive data is stored in Kubernetes secrets
• TLS encryption is enabled by default
• PostgreSQL uses separate users for root and application access
• Service account permissions are limited to required operations

Troubleshooting

1. If pods are not starting, check the logs:

   kubectl describe pod <pod-name> -n n8n
   kubectl logs <pod-name> -n n8n

2. If database connection fails:

   kubectl exec -it <postgres-pod-name> -n n8n -- psql -U postgres

3. If ingress is not working:

   kubectl describe ingress n8n-ingress -n n8n

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.