Overview
n8n is a workflow automation platform used to connect APIs, databases, SaaS tools, and internal systems with low-code workflows.
In a Shakudo environment, n8n sits at the automation layer. It is useful for scheduled jobs, webhook-driven integrations, operational workflows, and lightweight automations that should not require a full application deployment.
This page is written for onboarding and deployment calls. It focuses on what customers need to understand, provide, validate, and troubleshoot in a real environment.
Where it fits in the stack
- Primary role: n8n provides a reusable platform capability rather than a one-off application.
- Typical deployment model: Kubernetes + Helm, with customer-specific values and secrets.
- Typical access model: private internal endpoint or customer-approved external route.
- Typical support model: validate deployment health first, then validate user workflow and integrations.
What is n8n used for?
n8n is primarily used for:
1. Automating repetitive tasks across different tools
2. Building complex data pipelines
3. Creating custom integrations between applications
4. Developing AI-powered workflows by incorporating LLM chains
Is n8n no code?
n8n is considered a "low-code" platform. While it offers a visual interface for creating workflows without coding, it also provides the flexibility to add custom JavaScript code for more advanced use cases. This hybrid approach caters to users with varying technical expertise.
Is n8n self-hosted free?
Yes, n8n offers a free, self-hosted version. This allows organizations to run n8n on their own infrastructure, maintaining full control over their data and workflows. However, n8n also provides cloud-hosted options for those preferring a managed solution.
How does Shakudo enhance n8n's capabilities in a data science workflow?
Shakudo integrates n8n into its comprehensive data platform, amplifying its potential in data science workflows. By combining n8n's automation capabilities with Shakudo's managed infrastructure and tool interoperability, data scientists can create sophisticated, AI-driven pipelines. This integration streamlines the process of connecting data sources, preprocessing steps, and model deployment, all within a cohesive, scalable environment.
Getting Started
Start with one safe workflow in n8n before enabling production usage. The goal is to prove connectivity, permissions, and operational ownership.
What the customer needs to provide
- workflow owners and intended automation use cases
- external API credentials and callback/webhook URLs
- PostgreSQL database credentials for durable workflow storage
- encryption key for stored credentials
- domain name used for webhook callbacks
First workflow
- Open n8n and create or import a workflow
- Add a trigger such as schedule, webhook, or manual trigger
- Add actions such as HTTP Request, Postgres, Slack, or custom code
- Create credentials in n8n and test each node
- Run the workflow manually before activating it
- Check execution history after the first scheduled or webhook run
Deployment Runbook
📌 Command-first runbook for customer deployment calls. Replace placeholders before running. For production environments, run changes through the customer-approved change process.
Step 1 — Confirm cluster access
Run:
export KUBECONFIG=/path/to/customer-kubeconfig
export KUBE_CONTEXT=<customer-context>
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" config current-context
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" get nodes
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" get namespace hyperplane-n8n || kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" create namespace hyperplane-n8n
Step 2 — Clone the Shakudo chart
Run:
git clone --depth=1 --branch <release-branch> <https://github.com/devsentient/monorepo.git> /tmp/monorepo
cd /tmp/monorepo/stack-components/n8n/helm
helm dependency update .
Step 3 — Create required secrets
Run:
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" create secret generic n8n-secrets -n hyperplane-n8n --from-literal=N8N_ENCRYPTION_KEY='<32+ char key>' --from-literal=DB_POSTGRESDB_PASSWORD='<postgres-password>'
Step 4 — Prepare values.yaml
Run:
cat > /tmp/n8n-values.yaml <<'EOF_VALUES'
n8n:
main:
config:
n8n:
host: n8n.<customer-domain>
protocol: https
db:
type: postgresdb
postgresdb:
host: <postgres-host>
database: n8n
user: n8n
executions:
mode: regular
secret:
existingSecret: n8n-secrets
worker:
enabled: false
persistence:
enabled: true
size: 10Gi
ingress:
enabled: true
host: n8n.<customer-domain>
EOF_VALUES
Step 5 — Deploy or upgrade
Run:
helm --kubeconfig "$KUBECONFIG" --kube-context "$KUBE_CONTEXT" upgrade --install n8n /tmp/monorepo/stack-components/n8n/helm \\
--namespace hyperplane-n8n \\
--create-namespace \\
--values /tmp/n8n-values.yaml \\
--timeout 15m \\
--wait
Step 6 — Validate Kubernetes resources
Run:
helm --kubeconfig "$KUBECONFIG" --kube-context "$KUBE_CONTEXT" status n8n -n hyperplane-n8n
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" get pods,svc,pvc,ingress,virtualservice -n hyperplane-n8n
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" get events -n hyperplane-n8n --sort-by=.lastTimestamp | tail -n 60
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" logs -n hyperplane-n8n -l app.kubernetes.io/instance=n8n --tail=100
Step 7 — Smoke test the service
Run:
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" port-forward -n hyperplane-n8n svc/n8n 5678:5678
# In another terminal:
curl <http://localhost:5678/healthz>
Rollback
Run:
helm --kubeconfig "$KUBECONFIG" --kube-context "$KUBE_CONTEXT" history n8n -n hyperplane-n8nhelm --kubeconfig "$KUBECONFIG" --kube-context "$KUBE_CONTEXT" rollback n8n <REVISION> -n hyperplane-n8nkubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" rollout status deployment/n8n -n hyperplane-n8n || true
Administration and Best Practices
Use these practices to keep n8n reliable after the initial deployment.
- Always set and preserve N8N_ENCRYPTION_KEY; losing it breaks stored credentials
- Use PostgreSQL for production rather than SQLite
- Use separate credentials per integration owner
- Keep high-risk workflows inactive until manually tested
- Review failed executions and retry settings
- For high volume, move to queue/worker mode with Redis
Troubleshooting & FAQ
Use this section during customer debugging calls. Format: Problem → What to check → Fix.
Webhook does not trigger
- What to check: Check WEBHOOK_URL, ingress route, workflow active status, and HTTP method
- Fix: Set the external URL correctly and activate the workflow
Credentials stop working
- What to check: Check API token expiry, OAuth callback URL, and n8n encryption key
- Fix: Refresh credentials in n8n; do not rotate encryption key unless planned
Workflow runs manually but not on schedule
- What to check: Check timezone, trigger configuration, and whether the workflow is active
- Fix: Activate workflow and set timezone explicitly
Executions pile up or timeout
- What to check: Check node latency, external API rate limits, and n8n pod resources
- Fix: Add retries/backoff, reduce concurrency, or move to queue mode
