How to Configure n8n Kubernetes Connect

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up an n8n kubernetes connect flow by linking n8n to the Kubernetes API. You give n8n a service account token and map its permissions with RBAC roles. Teams often start by binding broad cluster roles so their workflows can run right away. When those roles are too wide, any workflow or AI agent can change live pods. A weak setup lets automated steps delete workloads or read secret keys across namespaces. How the native n8n kubernetes connect setup works In n8n, workflows and AI Agent no

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up an n8n kubernetes connect flow by linking n8n to the Kubernetes API. You give n8n a service account token and map its permissions with RBAC roles. Teams often start by binding broad cluster roles so their workflows can run right away. When those roles are too wide, any workflow or AI agent can change live pods. A weak setup lets automated steps delete workloads or read secret keys across namespaces.

How the native n8n kubernetes connect setup works

In n8n, workflows and AI Agent nodes talk to external systems through tool sub-nodes. The n8n AI Agent node pairs a chat model with one or more connected tools. During a run, the agent decides which tools to call to finish its task. You can attach an HTTP Request Tool or a Call n8n Workflow Tool to it. You can also connect a Custom Code Tool or pick from a registry of MCP servers. The workflow sends API calls to your Kubernetes API server using your stored token.

On the cluster side, Kubernetes checks those calls using Role-Based Access Control. In Kubernetes RBAC, a Role or ClusterRole holds a set of permission rules. All rules in Kubernetes RBAC are additive, and there are no deny rules at all. A standard Role always sets permissions inside a single namespace for your workloads. A ClusterRole is not tied to one namespace and can cover the whole cluster. It can control cluster resources like nodes or namespaced items across every namespace.

To make the rules active, you create a RoleBinding or a ClusterRoleBinding in Kubernetes. A RoleBinding grants permissions inside one namespace and can reference a Role or ClusterRole. A ClusterRoleBinding grants access across the entire cluster at once. Kubernetes also uses slash names for subresources in the API URL, like pod logs. If an n8n tool needs pod logs or exec access, RBAC checks those subresources.

What native RBAC solves and what it leaves open

Native Kubernetes RBAC is great at deciding which user or token can call an API. By using a RoleBinding in one namespace, you stop n8n from touching other teams. You can limit a workflow token so it only reads pods in a test namespace. This stops a broken workflow from wiping out nodes or changing cluster settings.

Kubernetes RBAC + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Still, static RBAC rules only check the resource type and the API verb at login. They do not inspect what happens inside an active pod command or data response. If a role allows pod exec or log reads, n8n gets full subresource access. An AI Agent node decides on its own which tool to call during a task. If a prompt tricks the agent, it can run risky commands inside an allowed pod. It can also pull sensitive data from pod logs, like emails or phone numbers. Static cluster roles cannot rewrite card numbers or national IDs inside API responses. They also cannot pause a single risky delete call for a human team check.

Best practices for safer cluster workflows

Start by scoping every n8n token to a single namespace with a standard Role. Avoid using a ClusterRoleBinding unless the workflow truly needs to read every namespace. Split your workflows so read tasks and write tasks use separate Kubernetes service accounts. Give your AI Agent nodes read-only tools when they only need to check pod status. Only grant subresource rules like pod exec or pod logs when a task requires them. Keep your service account tokens rotated and audit which n8n workflows use each role.

Check Kubernetes API requests and responses on the wire

Kubernetes RBAC decides who may call the API server. RBAC does not check response payloads or split listing Secret names from reading Secret values when a role grants get access. With hoop.dev, you run an open-source HTTP proxy, a sidecar for your Kubernetes API. The kubectl client changes only the server address it talks to while RBAC stays in place.

On each call, hoop.dev guardrails read the method, normalized path, and headers to refuse bad deletes or full Secret reads with a 403 error. On the way back, hoop.dev data masking walks JSON responses by key and masks matched values in Secrets, ConfigMaps, and pod logs. Every request and verdict is logged without storing bearer tokens. View the project on GitHub.

Frequently asked questions

How does an n8n AI Agent node talk to a Kubernetes cluster?

You attach an HTTP Request Tool or Custom Code Tool to the AI Agent node. The agent decides when to call that tool, which then sends requests to Kubernetes.

Should I use a Role or a ClusterRole for n8n workflows?

Use a Role with a RoleBinding whenever your workflow works in one namespace. Only use a ClusterRoleBinding if n8n must manage resources across the entire cluster.

Can Kubernetes RBAC block specific commands inside a pod exec call?

No, Kubernetes RBAC only checks if the token can call the pod exec subresource. It cannot read or block the specific shell commands that run inside the container.

The query runs. The emails stay hidden.