How to Configure Gemini CLI Kubernetes Credentials

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up gemini cli kubernetes credentials by linking a local config file to a cluster role. The command line agent then uses those local keys to run cluster commands from your shell. Many teams start by giving the agent the same broad admin role that human builders use. That fast setup works at first, but it exposes every namespace when the agent runs a bad command. How gemini cli kubernetes credentials work with cluster roles The agent runs in your local shell and reads the active cluster

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 gemini cli kubernetes credentials by linking a local config file to a cluster role. The command line agent then uses those local keys to run cluster commands from your shell. Many teams start by giving the agent the same broad admin role that human builders use. That fast setup works at first, but it exposes every namespace when the agent runs a bad command.

How gemini cli kubernetes credentials work with cluster roles

The agent runs in your local shell and reads the active cluster keys on your machine. When you ask the agent to check pods, it sends requests to the cluster API server. The API server checks those requests against its built-in role system. In Kubernetes, a Role sets rules within one namespace. A ClusterRole sets rules across the whole cluster, including nodes and all namespaces. You link a user or service identity to those rules with a RoleBinding or a ClusterRoleBinding.

Permissions in this system are additive only. There are no deny rules in native Kubernetes roles. You must list every resource and action that the agent needs to use. Some cluster actions target subresources, like reading pod logs or running commands inside a pod. You must grant these subresources by name in the role rules so the agent can read logs.

Scoping local keys for terminal agents

A safe setup starts with a dedicated service identity for the terminal agent. Do not let the agent reuse a personal admin key stored on a laptop. Create a Role that covers one namespace instead of a ClusterRole that spans the whole cluster. Grant read actions like get and list on pods and events in that single namespace. Leave out write actions like delete or create unless the task needs them.

Be careful with subresources that run commands inside containers or read stored secret objects. If a role allows reading secrets in a namespace, the agent can pull raw database keys into its context. Once those keys enter the prompt history, they leave the cluster boundary. Keep secret rules out of the agent role whenever you can. Review the role bindings often to make sure test rules do not stay active in prod.

Ephemeral Credentials + Kubernetes RBAC: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native roles solve and what they miss

Native cluster roles do a great job of deciding who can log in to the API server. They also restrict which resource types a given key can read or change inside a namespace. If an agent tries to delete a deployment without the right role, the API server blocks the call.

Still, static setup files leave a large gap during daily work. First, local config files sit on developer laptops, where any local process or shell tool can read them. Second, native roles check the resource type, not the exact command or data in flight. If an agent has permission to run commands inside a pod, RBAC cannot check which shell command runs inside. Likewise, if an agent reads pod logs, native roles cannot mask emails, phone numbers, or card numbers in the output. Teams need a way to approve risky actions per command and rewrite sensitive fields in results.

Add request guardrails and response masking beside Kubernetes

Cluster roles and service accounts govern who reaches the Kubernetes API. Still, a broad role or agent can delete workloads or print sensitive values from ConfigMaps and logs. In practice, hoop.dev sits inline beside the API server as a sidecar for your Kubernetes API. For every production API call an agent or human sends, hoop.dev decides whether to pass, mask, block, or escalate it for review alongside RBAC.

With hoop.dev Kubernetes controls, guardrails allow listing Secret names while refusing reads of Secret data before execution, and data masking redacts matched keys in returned JSON responses and log streams in memory. Furthermore, hoop.dev holds SOC 2 Type II and is MIT licensed on GitHub.

Frequently asked questions

Can I use deny rules to block my terminal agent from one namespace?

No, native Kubernetes role rules are additive only and do not support deny rules. To keep an agent out of a namespace, use a RoleBinding in only the allowed namespaces instead of a ClusterRoleBinding.

Why should I avoid giving the agent pod exec permissions?

Granting pod exec rules lets the agent run arbitrary shell commands inside a running container. Native role checks only verify that the identity can start the exec call, not which commands run inside the pod.

How do I let the agent read pod logs without giving full pod access?

Pod logs are a subresource in the cluster API. You can create a Role that grants read rules specifically on the pod log subresource within a single namespace.

The query runs. The emails stay hidden.