Kubectl Tunnel

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a kubectl tunnel by forwarding a local port to a pod. This kubectl tunnel routes traffic from your workstation through the Kubernetes API server. Teams use this method to debug internal services or reach private databases. They do not need to expose those services to the public internet. Still, many teams grant broad cluster permissions just to make local testing work. When permissions are too wide, any developer can reach sensitive workloads across namespaces. How a kubectl tunnel

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 a kubectl tunnel by forwarding a local port to a pod. This kubectl tunnel routes traffic from your workstation through the Kubernetes API server.

Teams use this method to debug internal services or reach private databases. They do not need to expose those services to the public internet. Still, many teams grant broad cluster permissions just to make local testing work. When permissions are too wide, any developer can reach sensitive workloads across namespaces.

How a kubectl tunnel works with native RBAC

Kubernetes controls tunnel creation through its built-in role-based permission system. The API server checks permissions using the standard RBAC API group. In this system, all rules are additive, and there are no deny rules. You start with zero rights and gain them through specific role bindings.

A Role sets permissions inside one specific namespace. A ClusterRole sets permissions across the whole cluster for all namespaces. It can also cover cluster-scoped resources like nodes. You link a user to a Role with a RoleBinding in that namespace. If you use a ClusterRoleBinding, the user gets those permissions across every namespace.

To open a kubectl tunnel, a user needs permission for a specific subresource. Kubernetes RBAC names resources just like they appear in the API URL. Subresources use a slash to separate the main resource from the action. Just as log reading uses a log subresource, port forwarding uses a portforward subresource. The user must have permission to create this subresource on the target pod.

Teams often try to limit which pods a user can reach by name. Still, Kubernetes RBAC has a known rule limit on subresource creation. The resource name restriction on create actions applies only to top-level resources. It does not apply to subresources. If a user can create a tunnel in a namespace, any pod is reachable.

What native RBAC solves and what it misses

Native Kubernetes RBAC is great at deciding who can start a connection. You can restrict developers to one namespace using a standard RoleBinding. You can also stop them from modifying production workloads or reading cluster secrets. The API server blocks unauthorized requests before a tunnel ever opens.

Tunnel: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Yet native RBAC stops checking once the tunnel is open and active. The API server only checks if the user can start the port forward session. After that, raw bytes flow through the tunnel directly to the target pod. Kubernetes does not inspect the database queries or HTTP requests inside that stream.

This leaves a big gap for security and platform teams during daily work. If a developer tunnels into a database pod, Kubernetes logs the connection start. It does not log the SQL queries that run inside the session. It also cannot mask sensitive data like emails, phone numbers, or card numbers. Masking rewrites matched fields in results, which raw port forwarding cannot do.

Why teams struggle with broad namespace roles

Because RBAC cannot restrict subresource creation by pod name, teams face a hard choice. They can move sensitive pods into separate namespaces with strict RoleBindings. Or they can give developers access to the whole namespace and accept the risk. Most fast-moving teams put apps and data stores in the same namespace.

When an incident happens, responders need fast access to fix broken services. Teams often hand out wide ClusterRoleBindings during an outage to save time. Those bindings rarely get removed after the fix is done. Over time, too many people keep permanent tunnel rights to production pods. You need a way to control commands and data inside the session itself.

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 Kubernetes authorize a kubectl tunnel?

The API server checks your Role or ClusterRole for the pods portforward subresource. If a RoleBinding or ClusterRoleBinding grants create rights, the tunnel opens.

Can I limit a kubectl tunnel to one specific pod name?

No, native RBAC resource name limits on create actions only cover top-level resources. They do not filter subresources, so the rule applies to the whole namespace.

Does Kubernetes audit logging record traffic inside a kubectl tunnel?

No, the API server only logs that a user started a port forward connection. It does not read or record the queries or data sent inside the tunnel.

The query runs. The emails stay hidden.