Namespace-Scoped Agents

Scope a Pipekit Agent to a single namespace, and understand how agents map to Argo Workflows controllers rather than to Kubernetes clusters.

By default the Pipekit Agent watches every namespace in the cluster and holds cluster-wide RBAC. You can scope an agent to a single namespace instead, so that it sees only the workflows in that namespace and holds permissions only there.

Agents, controllers, and Pipekit clusters

A Pipekit cluster is one Argo Workflows controller, not one Kubernetes cluster. Each agent serves one controller and connects to one Pipekit cluster, with its own Cluster ID and Secret Access Key.

Most Kubernetes clusters run a single cluster-wide Argo Workflows controller, so the two are the same thing in practice. A cluster running two namespace-scoped controllers is different: it needs one agent per controller, each scoped to that controller's namespace, and each connected to its own Pipekit cluster.

Chart 7.x deploys one agent per release, and a second release of the chart in the same cluster fails because the operator's ClusterRoles use fixed names. If you need more than one agent on a cluster, contact us before you install or upgrade.

Scoping an agent to one namespace

Set features.workflows.namespace to the namespace where the controller manages workflows:

helm upgrade -i -n pipekit \
pipekit-agent pipekit/pipekit-agent \
--set secrets.pipekitSecretAccessKey="[provided Secret Access Key]" \
--set secrets.pipekitClusterId="[provided Cluster ID]" \
--set features.workflows.namespace="team-a"

Leave the key empty, which is the default, for a cluster-wide agent.

Two namespaces are involved, and they are not the same thing:

• The namespace you install into, set with Helm's --namespace, is where the agent's own Deployment, ServiceAccount, ConfigMap, and Service run.

• features.workflows.namespace is the namespace the agent watches.

They can be the same namespace, and often are when the agent runs alongside the controller it serves.

pipekit connect cluster does not set this key, so it always installs a cluster-wide agent. Its --namespace flag chooses where the agent runs, not what it watches. Install with Helm directly when you want a namespace-scoped agent.

What changes when you scope an agent

The operator creates namespaced RBAC in place of the cluster-wide RBAC, and places it in the watched namespace rather than in the agent's own namespace. These names derive from the Installation resource, which is pipekit-agent for a release of that name:

Agent scope	RBAC the operator creates
Cluster-wide, the default	pipekit-agent-k8s-cluster-role and pipekit-agent-argo-cluster-role, each with a ClusterRoleBinding
Scoped to one namespace	pipekit-agent-role and pipekit-agent-rolebinding, both created in the watched namespace

Three limits come with a namespace-scoped agent:

• ClusterWorkflowTemplate is unavailable. The namespaced Role covers workflows, cronworkflows, and workflowtemplates only, because a cluster-scoped resource cannot be granted namespace by namespace. The agent validates a workflow before submitting it, so a workflow that references a ClusterWorkflowTemplate is rejected rather than reaching the controller.

• Cluster metrics are turned off. Setting features.workflows.namespace forces features.metrics.scrapeCluster off, because reading nodes and pods across the cluster needs the cluster-wide access this setting exists to avoid. The metrics collector still runs, but it sends no cluster telemetry, so the Workflow Metrics dashboard and the instance type in pipekit get workflow-node stay empty for this agent.

• Vector is not scoped with the agent. You can still enable it, and log collection works, but the DaemonSet collects Argo Workflows pod logs from every namespace and keeps cluster-wide read on pods, namespaces, and nodes. Only pods carrying Pipekit's run labels are shipped, so a single scoped agent does not send you other namespaces' logs, but the cluster-wide permission remains. Leave Vector disabled if you scoped the agent to limit its RBAC. Refer to Vector Log Collection.

Verifying the scope

Check the value the agent is running with, and that the namespaced RBAC landed where you expect:

kubectl -n pipekit get cm pipekit-agent-config -o jsonpath='{.data.SINGLE_NAMESPACE}'
kubectl -n team-a get role,rolebinding -l app.kubernetes.io/managed-by=pipekit-agent-operator

An empty first result means the agent is cluster-wide. The agent also logs its scope on startup, as either Agent for all namespaces or Agent for specific namespace.