Kubernetes Lab Setup: n8n

Lab Overview

This lab demonstrates installing Kubernetes applications using Helm on a local one node cluster deployed with Docker Desktop for macOS, deploying n8n, and troubleshooting issues encountered during the setup.

Setup Steps

1. Install kubectl and Helm

• Verified kubectl version. (Installed by Docker Desktop on cluster creation)
• Downloaded and installed Helm v4.0.4 for macOS ARM64:

tar -zxvf helm-v4.0.4-darwin-arm64.tar.gz
sudo mv darwin-arm64/helm /usr/local/bin/helm
helm --version

2. Helm Repository Configuration

• Added community charts repository for n8n:

helm repo add community-charts https://community-charts.github.io/helm-charts
helm repo update

• Added Traefik repository:

helm repo add traefik https://traefik.github.io/charts
helm repo update

• Added Secustor repo for Immich:

helm repo add secustor https://secustor.dev/helm-charts
helm repo update

3. Deploy n8n

• Installed n8n using Helm:

helm install n8n community-charts/n8n

• Monitored pods:

kubectl get pods -w
kubectl logs <POD_NAME>

• Port-forwarded for local access:

export POD_NAME=$(kubectl get pods -l "app.kubernetes.io/name=n8n,app.kubernetes.io/instance=n8n" -o jsonpath="{.items[0].metadata.name}")
export CONTAINER_PORT=$(kubectl get pod $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
kubectl port-forward $POD_NAME 8080:$CONTAINER_PORT

• Exported default values for customization:

helm show values community-charts/n8n > n8n-values.yml

• Upgraded deployment with custom values:

helm upgrade n8n community-charts/n8n --values n8n-values.yml

4. Deploy Traefik

• Installed Traefik ingress controller to manage traffic:

helm install traefik traefik/traefik

• Updated ingress resources for n8n to route traffic properly.

5. Deploy Immich

• Installed Immich in immich namespace:

helm install imchlc secustor/immich -n immich --create-namespace

• Checked all pods and deployments in the namespace:

kubectl get all -n immich

• Retrieved logs for troubleshooting:

kubectl logs -n immich <POD> -c main --previous

• Applied custom values for upgrade:

helm upgrade imchlc secustor/immich -n immich --values immich-values.yml

Issues Encountered and Fixes

1. Pod Crash or Pending State

• Problem: Pods were not starting or crashing.
• Fix: Checked logs and events using kubectl logs and kubectl describe pod. Adjusted resource limits and corrected configuration values in values.yml.

2. Port Forward Not Working

• Problem: Could not access the application locally.
• Fix: Verified pod name and container port. Corrected the kubectl port-forward command.

3. DNS Resolution Errors

• Problem: Could not resolve internal or external hostnames.
• Fix: Used nslookup and edited /etc/hosts for local testing. Confirmed cluster DNS service was running.

4. Ingress Not Routing Traffic

• Problem: n8n service not reachable via ingress.
• Fix: Installed Traefik and edited ingress resource. Verified using kubectl get ing and kubectl describe ing.

5. Persistent Storage Issues

• Problem: Immich required persistent volumes.
• Fix: Created PVCs and verified with kubectl get pvc. Docker volumes were mapped correctly.

Observations

• Helm is critical for simplifying application deployment.
• Always check logs for the previous container when debugging crashes.
• Namespaces help isolate apps and resources.
• Port-forwarding is essential for testing apps before ingress is configured.
• Regularly update repositories and Helm charts to prevent version mismatches.

References

• Kubernetes official documentation: https://kubernetes.io/docs/
• Helm documentation: https://helm.sh/docs/
• n8n Helm chart: https://github.com/community-charts/helm-charts
• Immich Helm chart: https://secustor.dev/helm-charts