### Configure Pod Lifecycle Hooks

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/configuration.md

Specify lifecycle hooks for the n8n pods, such as postStart or preStop commands. This example shows how to install a package after the container starts.

```yaml
main:
  lifecycle:
    postStart:
      exec:
        command: ["/bin/sh", "-c", "apk add mysql-client"]
```

--------------------------------

### Install Apache Bench for Load Testing

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Installs the Apache Bench (ab) tool, commonly used for load testing web applications.

```bash
apt-get install apache2-utils
```

--------------------------------

### Configure Database Connection

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Example of configuring the database connection details in the Helm chart's values. Ensure host and port match your database setup.

```yaml
main:
  config:
    db:
      postgresdb:
        host: postgres.default.svc
        port: 5432
```

--------------------------------

### Example Init Container Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

An example of how to configure an init container for data directory initialization. Ensure the image repository and tag are correctly set.

```yaml
- name: init-data-dir
  image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
  command: [ "/bin/sh", "-c", "mkdir -p /home/node/.n8n/" ]
  volumeMounts:
    - name: data
      mountPath: /home/node/.n8n
```

--------------------------------

### Configure Lifecycle Hooks

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

Enables the definition of lifecycle hooks for containers, such as `postStart`, to execute commands after container startup. Useful for installing packages or performing initial setup.

```yaml
lifecycle: {}
  #  here's the sample configuration to add mysql-client to the container
  # lifecycle:
  #  postStart:
  #    exec:
  #      command: ["/bin/sh", "-c", "apk add mysql-client"]
```

--------------------------------

### Install n8n via OCI Registry

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Install the n8n Helm chart directly from an OCI registry. This is the recommended method for pre-built and tested deployments.

```bash
helm install my-n8n oci://8gears.container-registry.com/library/n8n \
  --version 2.0.1 \
  --namespace n8n \
  --create-namespace
```

--------------------------------

### Install Traefik Helm Chart

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Installs the Traefik Helm chart to manage ingress traffic.

```bash
helm repo add traefik https://traefik.github.io/charts
helm install traefik traefik/traefik
```

--------------------------------

### Install NGINX Ingress Controller

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Installs the NGINX Ingress controller using Helm. Required for using NGINX-specific Ingress annotations.

```bash
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install nginx-ingress ingress-nginx/ingress-nginx
```

--------------------------------

### Get Helm Installation Notes

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Retrieve installation notes for a deployed Helm release. This is useful for post-installation steps or configuration details.

```bash
helm get notes my-n8n -n n8n
```

--------------------------------

### Install n8n Development Deployment

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Installs the n8n Helm chart with development-specific values. After installation, use kubectl port-forward to access n8n locally.

```bash
helm install n8n-dev ./charts/n8n -f values-dev.yaml

# Access via NodePort
kubectl port-forward service/n8n-dev-n8n 5678:5678
# Then open http://localhost:5678
```

--------------------------------

### Example Output for n8n.labels

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

Illustrates the common labels applied to Kubernetes resources when using the `n8n.labels` helper.

```yaml
helm.sh/chart: n8n-2.0.1
app.kubernetes.io/name: n8n
app.kubernetes.io/instance: my-n8n
app.kubernetes.io/version: "1.122.4"
app.kubernetes.io/managed-by: Helm
```

--------------------------------

### Install n8n from GitHub Repository

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Clone the n8n Helm chart repository from GitHub and install it locally. This method allows for direct access to the source code and local modifications.

```bash
git clone https://github.com/8gears/n8n-helm-chart
cd n8n-helm-chart

helm install my-n8n charts/n8n \
  --namespace n8n \
  --create-namespace
```

--------------------------------

### Example Output for n8n.selectorLabels

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

Shows the minimal labels generated by the `n8n.selectorLabels` helper, suitable for Kubernetes pod selectors.

```yaml
app.kubernetes.io/name: n8n
app.kubernetes.io/instance: my-n8n
```

--------------------------------

### Install Cert-Manager and Create ClusterIssuer

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Installs cert-manager and configures a ClusterIssuer for automatic certificate provisioning.

```bash
# Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Create cluster issuer
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
EOF
```

--------------------------------

### Install n8n using Helm Repo

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Install the n8n Helm chart by adding its repository to your Helm configuration. Ensure the repository URL is correct if using a private or custom repository.

```bash
helm repo add n8n https://charts.example.com
helm repo update

helm install my-n8n n8n/n8n \
  --namespace n8n \
  --create-namespace
```

--------------------------------

### Database Configuration Conversion Example

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/environment-variables.md

Shows the conversion of nested database configuration from YAML to multiple environment variables, including sensitive ones.

```yaml
main:
  config:
    db:
      type: postgresdb
      postgresdb:
        host: postgres.default.svc
        user: n8n
        pool:
          size: 10
```

--------------------------------

### Render Helm Chart Example

Source: https://github.com/8gears/n8n-helm-chart/blob/main/examples/README.md

Renders the n8n Helm chart with a specified values file to generate Kubernetes manifests.

```shell
helm template n8n charts/n8n -f examples/values_full.yaml > manifests.yaml
```

--------------------------------

### Install AWS ALB Ingress Controller

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Installs the AWS ALB Ingress controller using Helm. Required for using ALB-specific Ingress annotations.

```bash
helm repo add eks https://aws.github.io/eks-charts
helm install aws-load-balancer-controller eks/aws-load-balancer-controller
```

--------------------------------

### Install CloudNativePG and Deploy N8n

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

These bash commands install the CloudNativePG operator, wait for it to be ready, create necessary Kubernetes secrets for database credentials and certificates, and finally deploy n8n using Helm with the production values file.

```bash
# First ensure CloudNativePG is installed
kubectl apply -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.27/releases/cnpg-1.27.1.yaml

# Wait for CNPG controller
kubectl rollout status deployment -n cnpg-system cnpg-controller-manager

# Create database credentials secret
kubectl create secret generic postgres-credentials \
  --from-literal=password=your-secure-password

# Create certificate
kubectl create secret generic postgres-ca-cert \
  --from-file=ca.crt=/path/to/ca.crt

# Deploy n8n
helm install n8n ./charts/n8n -f values-prod.yaml
```

--------------------------------

### Configure Liveness and Readiness Probes

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Example of configuring liveness and readiness probe settings in the Helm chart. Adjust `initialDelaySeconds`, `periodSeconds`, `timeoutSeconds`, and `failureThreshold` as needed.

```yaml
main:
  livenessProbe:
    httpGet:
      path: /healthz
      port: http
    initialDelaySeconds: 30
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 6

  readinessProbe:
    httpGet:
      path: /healthz
      port: http
    initialDelaySeconds: 30
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 3
```

--------------------------------

### Example Small Deployment Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

A sample configuration for a small n8n deployment using NodePort for local testing. It includes basic n8n settings, encryption key, and resource limits.

```yaml
#small deployment with nodeport for local testing or small deployments
main:
  config:
    n8n:
      hide_usage_page: true
  secret:
    n8n:
      encryption_key: "<your-secure-encryption-key>"
  resources:
    limits:
      memory: 2048Mi
    requests:
      memory: 512Mi
  service:
    type: NodePort
    port: 5678
```

--------------------------------

### Helmfile Configuration for n8n

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Example `helmfile.yaml` configuration to manage the n8n Helm chart deployment. This is useful for declarative Helm deployments.

```yaml
repos:
  - name: n8n
    url: oci://8gears.container-registry.com/library/n8n

releases:
  - name: my-n8n
    namespace: n8n
    createNamespace: true
    chart: n8n/n8n
    version: 2.0.1
    values:
      - values.yaml
```

--------------------------------

### Extra Kubernetes Manifests Example

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/configuration.md

Deploy additional Kubernetes resources like ConfigMaps. Supports templating for dynamic values.

```yaml
extraManifests:
  - apiVersion: v1
    kind: ConfigMap
    metadata:
      name: custom-config
    data:
      key: value

extraTemplateManifests:
  - |
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: dynamic-config
    data:
      image: {{ .Values.image.repository }}
```

--------------------------------

### Configure Resource Requests

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Example of setting resource requests for CPU and memory in the Helm chart's values. This is a solution for pods failing due to insufficient resources.

```yaml
main:
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
```

--------------------------------

### DNS Record Setup for LoadBalancer

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Configure a CNAME record for ingress hostname when using a LoadBalancer.

```dns
n8n.example.com  IN  CNAME  elb-1234567890.us-east-1.elb.amazonaws.com
```

--------------------------------

### DNS Record Setup for NodePort (Development)

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Configure an A record for ingress hostname when using NodePort for development.

```dns
n8n.local  IN  A  192.168.1.100
```

--------------------------------

### Initial n8n Database Schema Setup

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Configuration snippet showing how n8n automatically creates its database schema (tables, indexes, constraints) on the first connection to a PostgreSQL database.

```yaml
main:
  config:
    db:
      type: postgresdb
      postgresdb:
        host: postgres

```

--------------------------------

### Database Connection Pooling Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/scaling-and-architecture.md

Example of configuring the database connection pool size for the postgresdb within the main deployment configuration.

```yaml
db:
  postgresdb:
    pool:
      size: 20
```

--------------------------------

### Automated Cluster Backup using Velero

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Installs Velero for cluster-wide backups and creates a schedule for daily backups of the default namespace. Requires Velero installation and AWS provider configuration.

```bash
# Install Velero
velero install --provider aws \
  --bucket velero-backups \
  --secret-file ./credentials-velero

# Create backup schedule
velero schedule create n8n-daily \
  --schedule="0 2 * * *" \
  --include-namespaces default

```

--------------------------------

### Enable Verbose Output for Helm and Kubectl

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Enables verbose output for Helm installations and kubectl logs to aid in debugging.

```bash
helm install my-n8n ./charts/n8n --debug
```

```bash
kubectl logs deployment/my-n8n-n8n -v=4
```

--------------------------------

### Local Development Configuration for n8n Helm Chart

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/configuration.md

This snippet illustrates a configuration for local development using Kind or K3s. It simplifies the setup by disabling persistence and workers, and hiding the usage page. Note that the encryption key is set to a development value and should be changed for production.

```yaml
main:
  service:
    type: NodePort
  persistence:
    enabled: false
  config:
    n8n:
      hide_usage_page: true
  secret:
    n8n:
      encryption_key: "dev-key-change-in-prod"

worker:
  enabled: false

webhook:
  enabled: false

```

--------------------------------

### DNS Record Setup for ClusterIP + Ingress

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Configure a CNAME record for ingress hostname when using ClusterIP.

```dns
n8n.example.com  IN  CNAME  ingress.cluster.example.com
```

--------------------------------

### Conditional Resource Creation Example

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

Conditionally create Kubernetes resources like Services based on Helm values. This allows for disabling resources by setting a corresponding 'enabled' flag to false.

```go-template
{{- if .Values.main.service.enabled }}
apiVersion: v1
kind: Service
...
{{- end }}

```

--------------------------------

### Define Initialization Containers

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

Specifies initialization containers that run in order before the main application containers. Useful for setup tasks, such as data seeding or dependency checks.

```yaml
# List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started.
  # See https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
```

--------------------------------

### Helmfile Configuration for n8n Deployment

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Example Helmfile configuration to manage n8n deployments using GitOps principles. This specifies the chart, version, namespace, and values file for the release.

```yaml
releases:
  - name: my-n8n
    namespace: workflow
    chart: oci://8gears.container-registry.com/library/n8n
    version: 1.0.0
    values:
      - values.yaml
```

--------------------------------

### Horizontal Scaling Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Example YAML snippet to adjust replica counts for main, worker, and webhook deployments to achieve horizontal scaling.

```yaml
main:
  replicaCount: 5      # Increase from 2

worker:
  replicaCount: 10     # More workers for queue processing
  concurrency: 10      # Each worker handles 10 jobs

webhook:
  replicaCount: 3      # More webhook handlers
```

--------------------------------

### Vertical Scaling Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Example YAML snippet to increase pod resource requests and limits for vertical scaling of the N8n main deployment.

```yaml
main:
  resources:
    requests:
      cpu: 2000m      # Increased from 500m
      memory: 2Gi     # Increased from 1Gi
    limits:
      cpu: 4000m
      memory: 4Gi
```

--------------------------------

### Check Service Endpoints

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/scaling-and-architecture.md

Use kubectl to get the endpoints for a service to verify load balancing distribution.

```bash
kubectl get endpoints my-n8n-n8n
```

--------------------------------

### Dynamic Port Mapping Example

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

Dynamically reference service ports in Ingress backends. This allows for custom service ports defined in values, defaulting to port 80 if not specified.

```go-template
backend:
  service:
    name: {{ $fullName }}
    port:
      number: {{ $.Values.main.service.port | default 80 }}

```

--------------------------------

### Update Helm Dependencies

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Use this command to download the necessary chart dependencies, such as the Valkey Helm chart, before installing or upgrading the n8n chart.

```bash
helm dependency update charts/n8n
```

--------------------------------

### Configure Dynamic Persistent Volume with AWS GP3

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Example of configuring a dynamic persistent volume using the AWS `gp3` storage class with a size of 100Gi and `ReadWriteOnce` access mode.

```yaml
main:
  persistence:
    enabled: true
    type: dynamic
    size: 100Gi
    storageClass: gp3
    accessModes:
      - ReadWriteOnce
```

--------------------------------

### Configure n8n to Use Spot Instances (AWS Example)

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/scaling-and-architecture.md

Assigns n8n main and worker pods to nodes with the 'spot' capacity type using node selectors, typically for cost savings on cloud platforms like AWS via Karpenter.

```yaml
main:
  nodeSelector:
    karpenter.sh/capacity-type: spot

worker:
  nodeSelector:
    karpenter.sh/capacity-type: spot
```

--------------------------------

### Check Probe Status and Details

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Inspect probe details using `kubectl describe pod` and monitor status changes with `kubectl get pods -w`. This is essential for diagnosing 'Pod Running But Not Ready' issues.

```bash
kubectl describe pod my-n8n-n8n-xxxxx
```

```bash
kubectl get pods -w
```

```bash
kubectl exec deployment/my-n8n-n8n -- curl -v http://localhost:3100/healthz
```

--------------------------------

### Auto-Scaling Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Example YAML snippet to enable and configure Horizontal Pod Autoscaler for N8n main and worker deployments based on CPU utilization.

```yaml
main:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 20
    targetCPUUtilizationPercentage: 60

worker:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 50
    targetCPUUtilizationPercentage: 70
```

--------------------------------

### Merge Configuration Example

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

Merge configuration from ConfigMaps and Secrets conditionally. This pattern avoids creating resource references if the corresponding values (main.config or main.secret) are not provided.

```go-template
envFrom:
  {{- if .Values.main.config }}
  - configMapRef:
      name: {{ include "n8n.fullname" . }}-app-config
  {{- end }}
  {{- if .Values.main.secret }}
  - secretRef:
      name: {{ include "n8n.fullname" . }}-app-secret
  {{- end }}

```

--------------------------------

### Database Connection Troubleshooting

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Troubleshoot database connection issues by adding a sidecar container or command to test connectivity before starting the main n8n process. Ensure database host and port are correctly set in environment variables.

```yaml
main:
  extraVolumes:
    - name: debug
      emptyDir: {}
  command:
    - /bin/sh
    - -c
    - |
      echo "Testing database connection..."
      nc -zv $DB_POSTGRESDB_HOST $DB_POSTGRESDB_PORT
      exec node /usr/local/bin/n8n
```

--------------------------------

### Get PostgreSQL Database Size

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Use kubectl to run a temporary pod with the postgres image and psql to query the size of the n8n database.

```bash
# Size of database
kubectl run -it --rm db-check \
  --image=postgres:15 \
  --restart=Never \
  -- psql -h postgres.default.svc -U n8n -d n8n \
    -c "SELECT pg_database.datname, pg_size_pretty(pg_database_size(pg_database.datname)) FROM pg_database;"
```

--------------------------------

### Override Container Command

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

Allows overriding the default command executed by the main container. This can be used to modify startup scripts or install additional software before n8n starts.

```yaml
command: []
  # sample configuration that overrides starting script and solves above issue (also it runs n8n as root, so be careful):
  # command:
  #  - tini
  #  - --
  #  - /bin/sh
  #  - -c
  #  - chmod o+rx /root; chown -R node /root/.n8n || true; chown -R node /root/.n8n; ln -s /root/.n8n /home/node; chown -R node /home/node || true; node /usr/local/bin/n8n
```

--------------------------------

### Convert YAML to Environment Variables (Non-Secret)

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

Example input for the `toEnvVars` template when `isSecret` is false, demonstrating conversion of nested YAML to environment variables with string quoting.

```yaml
values:
  db:
    postgresdb:
      host: localhost
      port: 5432
prefix: ""
isSecret: false
```

--------------------------------

### Create PersistentVolumeClaim using kubectl

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Demonstrates how to create a PersistentVolumeClaim named `my-n8n-storage` with `ReadWriteOnce` access, using the `fast-ssd` storage class and requesting 10Gi of storage.

```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-n8n-storage
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: fast-ssd
  resources:
    requests:
      storage: 10Gi
EOF
```

--------------------------------

### Valkey/Redis Configuration for Queueing

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/configuration.md

Enable Valkey as a dependency and configure n8n to use it for queue communication via environment variables.

```yaml
main:
  config:
    queue:
      bull:
        redis:
          host: n8n-valkey
          port: 6379
```

--------------------------------

### Get Application URL with NodePort Service

Source: https://github.com/8gears/n8n-helm-chart/blob/main/charts/n8n/templates/NOTES.txt

This snippet retrieves the NodePort and Node IP to construct the application URL when the service type is NodePort. It uses kubectl commands to get the necessary information.

```bash
export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "n8n.fullname" . }})
export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT
```

--------------------------------

### Dry Run n8n Helm Installation

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Perform a dry run of the Helm installation to simulate the process and check for errors without actually deploying resources. The --debug flag provides more detailed output.

```bash
helm install my-n8n charts/n8n \
  --dry-run \
  --debug \
  -f values.yaml
```

--------------------------------

### Get NodePort Value

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Retrieves the dynamically assigned NodePort for a service.

```bash
kubectl get svc my-n8n-n8n -o jsonpath='{.spec.ports[0].nodePort}'
```

--------------------------------

### EmptyDir Volume Definition

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

An example of an emptyDir volume definition for pod data storage.

```yaml
emptyDir: {}
```

--------------------------------

### Get LoadBalancer External IP

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Retrieves the external IP address or hostname assigned to a LoadBalancer service.

```bash
kubectl get svc my-n8n-n8n -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
```

--------------------------------

### Troubleshoot Connection Timeout

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Commands to check network policies, test connectivity to the service, and inspect pod logs.

```bash
# Check network policies
kubectl get networkpolicies

# Test connectivity
kubectl run -it --rm debug --image=busybox --restart=Never -- wget -O- http://my-n8n-n8n

# Check pod logs
kubectl logs deployment/my-n8n-n8n
```

--------------------------------

### Existing PVC Volume Definition

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

An example of a persistentVolumeClaim definition using an existing PVC for pod data storage.

```yaml
persistentVolumeClaim:
  claimName: my-existing-pvc
```

--------------------------------

### View and Watch Kubernetes Events

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Commands to retrieve all cluster events, events for a specific namespace, or watch events in real-time. Also shows how to describe events for a specific pod.

```bash
kubectl get events
```

```bash
kubectl get events -n default
```

```bash
kubectl get events -w
```

```bash
kubectl describe pod my-n8n-n8n-xxxxx | grep -A 20 "Events:"
```

--------------------------------

### Troubleshoot Service Not Found

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Commands to verify service existence, check endpoints, and test DNS resolution.

```bash
# Verify service exists
kubectl get svc my-n8n-n8n

# Check endpoints
kubectl get endpoints my-n8n-n8n

# Check DNS resolution
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup my-n8n-n8n
```

--------------------------------

### Verify n8n Installation Status

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Commands to check the status of the deployed n8n Helm release and its associated Kubernetes resources.

```bash
# Check release status
helm status my-n8n -n n8n

# Check pod status
kubectl get pods -n n8n -l app.kubernetes.io/name=n8n

# Check services
kubectl get svc -n n8n

# Check ingress
kubectl get ingress -n n8n
```

--------------------------------

### Check Webhook Pods and Test Endpoint

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Verify webhook pods are running and test the webhook endpoint by port-forwarding the service and sending a POST request. Examine webhook logs for errors.

```bash
# Check webhook pods
kubectl get pods -l app.kubernetes.io/type=webhook

# Test webhook endpoint
kubectl port-forward service/my-n8n-n8n-webhook 8080:80
curl -X POST http://localhost:8080/webhook/test -d '{"test": "data"}' -H "Content-Type: application/json"

# Check webhook logs
kubectl logs deployment/my-n8n-n8n-webhook
```

--------------------------------

### Dynamic PVC Volume Definition

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/templates-and-helpers.md

An example of a persistentVolumeClaim definition for dynamically provisioning a new PVC for pod data storage.

```yaml
persistentVolumeClaim:
  claimName: my-n8n-n8n
```

--------------------------------

### Test PostgreSQL Database Connection

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Use kubectl to run a temporary pod with the postgres image to test the connection to the database using pg_isready.

```bash
# Connection test
kubectl run -it --rm db-check \
  --image=postgres:15 \
  --restart=Never \
  -- pg_isready -h postgres.default.svc -U n8n
```

--------------------------------

### Deploy CloudNativePG Operator

Source: https://github.com/8gears/n8n-helm-chart/blob/main/examples/README.md

Applies the CloudNativePG operator manifest and checks its deployment status. This is recommended for testing examples with PostgreSQL.

```shell
kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.27/releases/cnpg-1.27.1.yaml
kubectl rollout status deployment \
  -n cnpg-system cnpg-controller-manager
```

--------------------------------

### Local Development DNS Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Edit the /etc/hosts file to map a local domain to localhost for development.

```bash
127.0.0.1       n8n.local
::1             n8n.local
```

--------------------------------

### Describe a Persistent Volume Claim (PVC)

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Use kubectl to get detailed information about a specific Persistent Volume Claim.

```bash
# Describe PVC
kubectl describe pvc my-n8n-n8n
```

--------------------------------

### Check Webhook and Database Metrics

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Monitor webhook pod resource usage with `kubectl top pods`. Check the database connection count for queries related to webhooks to identify performance bottlenecks.

```bash
# Check webhook pod metrics
kubectl top pods -l app.kubernetes.io/type=webhook

# Check database connection count
kubectl exec pod/postgres-0 -- \
  psql -U n8n -d n8n -c "SELECT count(*) FROM pg_stat_activity WHERE query LIKE '%webhook%';"
```

--------------------------------

### Increase Probe Initial Delay

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Solution for probe timeouts: increase `initialDelaySeconds` in the probe configuration if the application takes longer to start.

```yaml
main:
  readinessProbe:
    initialDelaySeconds: 60  # Increase from 30
```

--------------------------------

### Simple YAML to Environment Variable Conversion

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/environment-variables.md

Demonstrates the conversion of a simple key-value pair from YAML to an uppercase environment variable.

```yaml
main:
  config:
    key: value
```

--------------------------------

### Connecting to PostgreSQL Database

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Command to establish an interactive psql client session to the n8n PostgreSQL database for direct querying.

```bash
# Connect to PostgreSQL
kubectl run -it --rm postgres-client \
  --image=postgres:15 \
  --restart=Never \
  -- psql -h postgres.default.svc -U n8n -d n8n

```

--------------------------------

### Configure MySQL/MariaDB Database

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Sets up connection parameters for a MySQL or MariaDB database, including host, port, database name, and user. Compatible with MySQL 8.0+ and MariaDB 10.5+.

```yaml
main:
  config:
    db:
      type: mysql
      mysql:
        host: mysql.default.svc
        port: 3306
        database: n8n
        user: n8n
  
  secret:
    db:
      mysql:
        password: "secure-password"
```

--------------------------------

### CPU Optimization Settings

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/scaling-and-architecture.md

Configure CPU requests and limits for the main pod, and allow all built-in nodes.

```yaml
main:
  resources:
    requests:
      cpu: 1000m
    limits:
      cpu: 2000m
  config:
    node:
      function_allow_builtin: "*"
```

--------------------------------

### Enable Webhook Service

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Enable the webhook service and set the replica count in the Helm values. Ensure Redis is also enabled as it is a dependency.

```yaml
webhook:
  enabled: true
  replicaCount: 1

# Also requires Redis
valkey:
  enabled: true
```

--------------------------------

### Querying n8n Execution Data

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

SQL query to retrieve the ID, workflow ID, status, and start time of n8n executions from the database.

```sql
SELECT id, workflow_id, status, started_at FROM execution;

```

--------------------------------

### Ingress Path Type: Prefix

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Configures an Ingress path to match any URL starting with the specified path. Recommended for main n8n routes.

```yaml
pathType: Prefix
path: /
```

--------------------------------

### Webhook Deployment Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/environment-variables.md

Webhook deployments inherit main configuration and can override or augment it with webhook-specific settings. This example demonstrates overriding the webhook URL.

```yaml
main:
  config:
    webhook_url: https://n8n.example.com

webhook:
  config:
    # These override/augment main config
    webhook_url: https://webhooks.example.com
```

--------------------------------

### Check PostgreSQL Pod Status

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Verify that the PostgreSQL pods are running using `kubectl get pods`. This is a basic step to ensure the database is available.

```bash
kubectl get pods -l app=postgres
```

--------------------------------

### Resource Dependency Chain Visualization

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/kubernetes-resources.md

This diagram illustrates the order in which Kubernetes resources are created and their dependencies within the n8n Helm chart.

```text
ConfigMaps, Secrets ─────┐
                         ├──→ ServiceAccounts ─────┐
PersistentVolumeClaims ──┤                         ├──→ Deployments ─┐
                         ├──→ Ingress (optional)   │                │
Extra Manifests ─────────┴──→ Services ◄──────────┤                │
                                                   ├──→ HPAs (optional)
                         ┌──→ Valkey StatefulSet ──┘
                         │
                    (dependency)
```

--------------------------------

### Troubleshoot Certificate Issues

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Commands to check certificate status, describe certificates, verify secret existence, and inspect certificate validity.

```bash
# Check certificate status
kubectl get certificate

# Describe certificate
kubectl describe certificate n8n-tls-cert

# Check secret exists
kubectl get secret n8n-tls-cert -o yaml

# Verify certificate validity
kubectl get secret n8n-tls-cert -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -text -noout
```

--------------------------------

### Inspect Kubernetes Network Policies

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Commands to view, describe, and test network policies within a Kubernetes cluster.

```bash
kubectl get networkpolicies
```

```bash
kubectl describe networkpolicy my-policy
```

```bash
kubectl run -it --rm debug \
  --image=busybox \
  --restart=Never \
  -- nc -zv service 80
```

--------------------------------

### Kubernetes Secret Encoding Example

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/environment-variables.md

Illustrates how values in `main.secret` are automatically base64-encoded when stored in Kubernetes Secrets. The container automatically decodes these when mounted as environment variables.

```yaml
main:
  secret:
    db:
      postgresdb:
        password: "my_secret"
```

--------------------------------

### Worker Deployment Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/environment-variables.md

Worker deployments inherit main configuration and can override or augment it with worker-specific settings. This example shows how to set the log level for workers.

```yaml
main:
  config:
    db:
      type: postgresdb
    queue:
      bull:
        redis:
          host: redis

worker:
  config:
    # These override/augment main config
    n8n:
      log:
        level: debug
```

--------------------------------

### Get n8n Helm Release Values

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/chart-reference.md

Retrieve the current configuration values for a deployed n8n Helm release. This helps in understanding the active settings and troubleshooting.

```bash
helm get values my-n8n -n n8n
```

--------------------------------

### Ingress Configuration with Automatic Webhook Routing

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/ingress-and-networking.md

Enables automatic routing of webhook traffic to the dedicated webhook service when `webhook.enabled` is true. Simplifies webhook setup.

```yaml
ingress:
  enabled: true
  hosts:
    - host: n8n.example.com
      paths:
        - path: /
          pathType: Prefix
webhook:
  enabled: true
```

--------------------------------

### Check CPU Usage and Profiling

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Monitor CPU usage with `kubectl top pods`. Use `kubectl exec` to run `top` within the container or enable Node.js profiling for detailed CPU usage analysis.

```bash
# Check CPU usage
kubectl top pods -l app.kubernetes.io/name=n8n

# Check what's using CPU
kubectl exec deployment/my-n8n-n8n -- top -n 1

# Profile CPU usage (requires tools in image)
kubectl exec -it deployment/my-n8n-n8n -- node --prof /usr/local/bin/n8n
```

--------------------------------

### Viewing Environment Variables in Main Deployment

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/environment-variables.md

Command to list all environment variables set for the main n8n deployment pod. Useful for debugging.

```bash
kubectl exec -it deployment/my-n8n-n8n -- env | sort
```

--------------------------------

### Development Values for n8n Helm Chart

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Minimal configuration for local development using Minikube or Kind. This disables persistence, sets replica count to 1, and uses NodePort for service access.

```yaml
# values-dev.yaml
image:
  pullPolicy: IfNotPresent

main:
  replicaCount: 1
  persistence:
    enabled: false
  config:
    n8n:
      hide_usage_page: true
  secret:
    n8n:
      encryption_key: "dev-key-12345"
  service:
    type: NodePort
    port: 5678
  resources:
    limits:
      memory: 1024Mi
    requests:
      memory: 512Mi

worker:
  enabled: false

webhook:
  enabled: false

ingress:
  enabled: false
```

--------------------------------

### Resource Limits and Requests

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

Optional configuration for CPU and memory limits and requests for pods. It's recommended to leave these commented out unless specific resource management is required.

```yaml
resources: {}
# We usually recommend not specifying default resources and to leave this as a conscious
# choice for the user. This also increases chances charts run on environments with little
# resources, such as Minikube. If you do want to specify resources, uncomment the following
# lines, adjust them as necessary, and remove the curly braces after 'resources:'.
# limits:
#   cpu: 100m
#   memory: 128Mi
# requests:
#   cpu: 100m
#   memory: 128Mi
```

--------------------------------

### Get Application URL with Ingress Hosts

Source: https://github.com/8gears/n8n-helm-chart/blob/main/charts/n8n/templates/NOTES.txt

This snippet iterates through configured Ingress hosts and paths to construct the application URL. It is used when ingress is enabled in the Helm chart values.

```go-template
{{- if .Values.ingress.enabled }}
{{- range $host := .Values.ingress.hosts }}
  {{- range .paths }}
  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }}
  {{- end }}
{{- end }}
{{- end }}
```

--------------------------------

### High Availability Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Configure for multi-zone deployment with pod anti-affinity to ensure high availability. This setup distributes pods across different zones and prevents them from being scheduled on the same node.

```yaml
main:
  replicaCount: 3
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchExpressions:
              - key: app.kubernetes.io/name
                operator: In
                values:
                  - n8n
              - key: app.kubernetes.io/type
                operator: In
                values:
                  - master
          topologyKey: topology.kubernetes.io/zone
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app.kubernetes.io/name: n8n
          app.kubernetes.io/type: master

worker:
  replicaCount: 3
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchExpressions:
              - key: app.kubernetes.io/name
                operator: In
                values:
                  - n8n
              - key: app.kubernetes.io/type
                operator: In
                values:
                  - worker
          topologyKey: topology.kubernetes.io/zone

webhook:
  replicaCount: 2
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - n8n
                - key: app.kubernetes.io/type
                  operator: In
                  values:
                    - webhook
            topologyKey: topology.kubernetes.io/zone

valkey:
  enabled: true
  replicaCount: 3
  dataStorage:
    enabled: true
    requestedSize: 20Gi
```

--------------------------------

### Check Database Pool Size Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Inspect the `DB_POSTGRESDB_POOL_SIZE` environment variable to check the current database connection pool settings for n8n.

```bash
kubectl exec deployment/my-n8n-n8n -- env | grep DB_POSTGRESDB_POOL_SIZE
```

--------------------------------

### Configure Readiness Probe

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

Configures the readiness probe for the n8n container, indicating when the container is ready to serve traffic. Allows customization of path, port, and timing parameters.

```yaml
readinessProbe:
    httpGet:
      path: /healthz
      port: http
    # initialDelaySeconds: 30
    # periodSeconds: 10
    # timeoutSeconds: 5
    # failureThreshold: 6
    # successThreshold: 1
```

--------------------------------

### Permission Issues Troubleshooting

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Resolve permission issues by configuring `podSecurityContext` and using an `initContainer` to set correct file permissions for the n8n data directory. This ensures the n8n process can read and write to its required volumes.

```yaml
main:
  podSecurityContext:
    runAsNonRoot: true
    runAsUser: 1000
    runAsGroup: 1000
    fsGroup: 1000
  initContainers:
    - name: permissions
      image: busybox
      command:
        - sh
        - -c
        - chmod -R 777 /home/node/.n8n
      volumeMounts:
        - name: data
          mountPath: /home/node/.n8n
```

--------------------------------

### Test Redis Connectivity

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/troubleshooting.md

Use `kubectl run` to launch a temporary Redis container and `redis-cli` to test connectivity to the specified Redis host and port. Verify Redis logs and configuration for troubleshooting.

```bash
# Test Redis connectivity
kubectl run -it --rm debug \
  --image=redis:7 \
  --restart=Never \
  -- redis-cli -h n8n-valkey-master ping

# Check Redis logs
kubectl logs pod/n8n-valkey-master

# Verify Redis config
main:
  config:
    queue:
      bull:
        redis:
          host: n8n-valkey-master  # Verify hostname
          port: 6379
```

--------------------------------

### Stateless Deployment Configuration

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/deployment-patterns.md

Configure for stateless, horizontally-scalable deployment on Kubernetes. This setup uses an external database and queue mode for asynchronous processing, ensuring no data loss on pod restarts.

```yaml
main:
  replicaCount: 1
  persistence:
    enabled: false  # No local state
  config:
    executions_mode: queue  # Decouple execution from request
    db:
      type: postgresdb
      postgresdb:
        host: postgres.default.svc
  secret:
    n8n:
      encryption_key: "your-encryption-key"

worker:
  enabled: true
  replicaCount: 1  # Scale independently
  concurrency: 20

webhook:
  enabled: true
  replicaCount: 1  # Scale independently

valkey:
  enabled: true
```

--------------------------------

### Enable Dedicated Webhook Instances

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

To create dedicated webhook instances, set `scaling.webhook.enabled` to true. This disables webhook processing on the main instance and starts a single webhook instance by default.

```yaml
scaling:
  webhook:
    enabled: true
```

--------------------------------

### Configure n8n Main and DB Settings

Source: https://github.com/8gears/n8n-helm-chart/blob/main/README.md

This snippet shows how to configure main n8n settings and database connection details within the values.yaml file. These settings are translated into environment variables for the n8n pods.

```yaml
main:
  config:
      n8n:
        encryption_key: "my_secret" # ==> turns into ENV: N8N_ENCRYPTION_KEY=my_secret
      db:
        type: postgresdb # ==> turns into ENV: DB_TYPE=postgresdb
        postgresdb:
          host: 192.168.0.52 # ==> turns into ENV: DB_POSTGRESDB_HOST=192.168.0.52
      node:
        function_allow_builtin: "*" # ==> turns into ENV: NODE_FUNCTION_ALLOW_BUILTIN="*"
```

--------------------------------

### Migrating n8n Data to New Storage Backend

Source: https://github.com/8gears/n8n-helm-chart/blob/main/_autodocs/persistence-and-data.md

Steps to migrate n8n data to a new storage backend by creating a new PersistentVolumeClaim, copying data, and updating the Helm release.

```bash
# 1. Create new PVC
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: n8n-new-storage
spec:
  storageClassName: fast-ssd
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
EOF

# 2. Copy data
kubectl cp pod-name:/home/node/.n8n ./local-backup
kubectl cp ./local-backup pod-name:/home/node/.n8n

# 3. Update values
helm upgrade my-n8n ./charts/n8n \
  --set main.persistence.existingClaim=n8n-new-storage

```