How to Configure AKS Port Forward
You set up an aks port forward by granting pod and portforward subresource permissions in Kubernetes RBAC. Then your engineer opens a local tunnel to a specific pod or service port through the API server. Most teams start by handing out broad namespace roles so developers can debug apps fast. When those roles are too wide, anyone can reach internal databases or admin ports inside the cluster. How an aks port forward works under the hood Kubernetes does not open a direct network route from a l
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 aks port forward by granting pod and portforward subresource permissions in Kubernetes RBAC. Then your engineer opens a local tunnel to a specific pod or service port through the API server. Most teams start by handing out broad namespace roles so developers can debug apps fast. When those roles are too wide, anyone can reach internal databases or admin ports inside the cluster.
How an aks port forward works under the hood
Kubernetes does not open a direct network route from a laptop to a worker node. Instead, the client talks to the cluster API server over a secure connection. The API server checks who the user is and what RBAC rules apply to them. After the API server approves the request, it streams traffic between the local port and the target pod.
In Kubernetes RBAC, a Role sets permissions inside one single namespace. A ClusterRole sets permissions across the whole cluster and covers all namespaces. You link a Role to a user or group with a RoleBinding in that namespace. If you use a ClusterRoleBinding, the user gets those permissions in every namespace at once.
Permissions in Kubernetes RBAC are additive, which means there are no deny rules. To run a port forward, a user needs access to a specific subresource in the API. RBAC writes subresources with a slash after the main resource name, like pods and its portforward subresource. You must grant permissions on both the pod resource and the portforward subresource for the tunnel to work.
Scoping roles and avoiding broad cluster permissions
Many teams assign built-in edit or admin roles to save time during an incident. Those broad roles let engineers forward ports to any pod in the namespace or cluster. If a namespace holds both a web app and a payment service, both are exposed. A user who only needs to check a web pod can also reach the payment pod.
You can tighten this setup by creating a small Role in one namespace. That Role should only list the exact verbs needed for pods and the portforward subresource. Even with a tight Role, Kubernetes RBAC has a known quirk with resource names on subresources. You cannot always restrict create actions on a subresource to a single pod name.
Because pods get new names every time they restart, static pod names in RBAC break often. Teams So, fall back to namespace-wide port forward permissions for their engineers. That keeps daily debugging simple, but it leaves every pod in that namespace reachable.
AKS Managed Identity + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native RBAC solves and what it leaves open
Native Kubernetes RBAC is great at deciding who can start a tunnel to a namespace. The API server checks the RoleBinding before it opens the stream to the pod. It also writes an entry in the cluster audit log showing that the session started. This stops unauthorized users from reaching your cluster workloads from the outside.
Still, RBAC stops checking once the tunnel is open and bytes start flowing. The API server just passes raw traffic back and forth through the local port. If a pod runs a database or an internal admin API, the cluster cannot inspect those queries. Audit logs will show that a port forward happened, but not what commands ran inside the tunnel.
Also, native RBAC cannot rewrite sensitive data like emails, phone numbers, or card numbers in flight. Anyone with an active tunnel receives the full response sent by the pod. Teams that need command-level visibility or field masking must look beyond basic cluster roles.
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 proxy, a sidecar for your Kubernetes API, inline on the API connection. On every kubectl or API call an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.
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, or hold risky calls for approval. On the way back, hoop.dev data masking walks JSON responses by key and masks matched values in Secrets, ConfigMaps, and pod logs in memory. View the project on GitHub.
Frequently asked questions
What RBAC permissions are needed for aks port forward?
A user needs a Role or ClusterRole that allows access to pods and the portforward subresource. You then bind that role to the user or group with a RoleBinding in the target namespace.
Can I use deny rules in Kubernetes RBAC to block one pod?
No, Kubernetes RBAC permissions are purely additive and do not support deny rules. You must start with zero access and only grant roles for the namespaces a user needs.
Does the Kubernetes audit log record traffic inside a port forward tunnel?
No, the cluster API server only logs the request that opens the port forward session. It does not read or log the database queries or HTTP calls sent through the tunnel.
Related guides
In this post