Circle CI Kubernetes

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a circle ci kubernetes workflow by linking your build runner to a cluster role. The build job uses a token to log in and apply changes to your pods. Many teams start by giving the build runner broad cluster permissions to avoid failed runs. This fast setup leaves your cluster open to big mistakes if a script or token goes wrong. How circle ci kubernetes permissions work A build job needs a way to talk to the cluster API server. Teams create a service identity inside the cluster for

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 circle ci kubernetes workflow by linking your build runner to a cluster role. The build job uses a token to log in and apply changes to your pods. Many teams start by giving the build runner broad cluster permissions to avoid failed runs. This fast setup leaves your cluster open to big mistakes if a script or token goes wrong.

How circle ci kubernetes permissions work

A build job needs a way to talk to the cluster API server. Teams create a service identity inside the cluster for the build tool. Then they use the native role system to grant specific actions. In this system, a Role or ClusterRole holds rules that represent a set of permissions. All permissions are purely additive, which means there are no deny rules.

A Role always sets permissions within one single namespace. A ClusterRole is not tied to one namespace. It can cover cluster-wide items like nodes, or resources across every namespace. To connect the build identity to these rules, you create a binding. A RoleBinding grants permissions inside one specific namespace. It can point to a Role in that same namespace or a global ClusterRole.

A ClusterRoleBinding grants access across the entire cluster at once. If a build runner only deploys to one app space, use a RoleBinding. Giving a runner a ClusterRoleBinding lets a bad job break other apps on the same nodes. You also need to watch subresources in the API. The role system names subresources with a slash, such as pod logs or pod exec.

What native cluster roles solve and what they miss

Native roles and bindings do a good job of limiting which API paths a runner can hit. They stop a build job for team A from deleting pods owned by team B. You can restrict a runner so it only updates deployments in its own namespace. You can also leave out pod exec rules so the runner cannot open a shell.

Still, static roles only check who logs in and which API resource they call. They do not inspect what individual commands or changes do while in flight. Once a build job or engineer gets pod exec permissions, the cluster allows any shell command inside. The role system cannot pause a dangerous command or ask a human to approve a production change.

Kubernetes RBAC + GitLab CI Security: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Static tokens stored in your build settings also create a long-term risk. If someone copies that key, they get the exact same cluster permissions from anywhere. Native role checks also lack field-level data masking for sensitive output. If a pod log prints customer emails, phone numbers, or card numbers, the raw text flows right into the build log.

How to tighten your deployment workflow

Start by auditing every binding linked to your build runners and human users. Replace broad ClusterRoleBindings with tight RoleBindings in one namespace whenever you can. Remove subresource rules like pod exec from automated build roles that only apply manifests. Keep human debug tasks separate from automated pipeline keys so you can track every action clearly.

Next, look at how engineers and runners interact with live pods during an incident. When someone needs to run a command or check data, static roles are too blunt. Teams need a way to check each command, require quick approvals, 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 runs beside the API server as a sidecar for your Kubernetes API and checks every request and response alongside RBAC.

With hoop.dev Kubernetes controls, guardrails can allow listing Secret names while refusing reads of Secret data before execution. 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

Should a CircleCI runner use a Role or a ClusterRole?

Use a Role and a RoleBinding when the job only updates one namespace. Use a ClusterRole only if the job must manage cluster-wide items like nodes or namespaces.

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

No, native RBAC only checks if the user can call the pod exec subresource. Once the session starts, RBAC cannot filter or block individual shell commands inside the container.

How do I stop a build job from reading secrets in other namespaces?

Do not grant the runner a ClusterRoleBinding that includes secret read rules. Instead, bind a Role inside the single target namespace so permissions stay isolated.

The query runs. The emails stay hidden.