glab(1)

📦
version 1.128.0 · 7 versions
, in arch rolling

🦋 glab cluster graph 💅

okay so this is a page straight out of the glab(1) manual, and bestie, it's a whole vibe. it's about poking at your Kubernetes object graph through the GitLab Agent, and yeah — it's EXPERIMENTAL, we'll get to that.

🌸 NAME 🌸

glab-cluster-graph — query the Kubernetes object graph using the GitLab Agent for Kubernetes. (EXPERIMENTAL) 🧪

✨ SYNOPSIS ✨

glab cluster graph [flags]

💖 DESCRIPTION 💖

So this command literally spins up a web server that shows you a live view of the Kubernetes object graph in your browser. slay. it pulls all of that through the GitLab Agent for Kubernetes that's already running in the cluster.

here's the checklist, no cap — it requires:

  • Version 18.1 or later of GitLab and the GitLab Agent.
  • At least the Developer role in the agent project.
  • A personal access token or project access token for authentication. the token must have the read_api and k8s_proxy scopes. both of them. don't skip one 🙈

got feedback? drop it in [issue 7900](https://gitlab.com/gitlab-org/cli/-/issues/7900) — they say "Leave feedback in issue 7900 ⟨https://gitlab.com/gitlab-org/cli/-/issues/7900⟩" and honestly yes, go tell them.

🎀 Resource filtering 🎀

To filter resources, namespaces, and select root objects, you use Common Expression Language (CEL) ⟨https://cel.dev/⟩. it's giving query-language main character energy.

object_selector_expression — filters objects. the expression must return a boolean. these are the variables you get to play with:

  • obj — the Kubernetes object being evaluated.
  • group — the group of the object.
  • version — the version of the object.
  • resource — the resource name of the object, like pods for the Pod kind.
  • namespace — the namespace of the object.
  • name — the name of the object.
  • labels — the labels of the object.
  • annotations — the annotations of the object.

resource_selector_expression — filters Kubernetes discovery information to include or exclude resources from the watch request. must also return a boolean. variables:

  • group — the group of the object.
  • version — the version of the object.
  • resource — the resource name of the object, like pods for the Pod kind.
  • namespaced — the scope of group, version, and resource. can be bool, true, or false.

To select root objects, use the --root-expression flag. when it's set, only objects that are directly or transitively reachable from root objects are shown. it uses the same variables as object_selector_expression, and it must return a boolean. multiple values are joined with OR statements — if any match, that object is used as root. 💫

want more on using label selectors ⟨https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors⟩ and field selectors ⟨https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/⟩ to select namespaces? the Kubernetes documentation has you covered.

🧚 Advanced usage 🧚

Besides the high-level ways to construct the query, this command also lets you construct and send the query using all the underlying API features. iconique. to understand what's possible and how to do it, see the technical design doc ⟨https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/graph_api.md⟩.

the user should have permission to access the agent project. for more info, see Grant users Kubernetes access ⟨https://docs.gitlab.com/user/clusters/agent/user_access/⟩.

⚠️ bestie, listen: this feature is an experiment and is not ready for production use. it might be unstable or removed at any time. like, at any time. for more information, see https://docs.gitlab.com/policy/development_stages_support/.

🔥 OPTIONS 🔥

  • -a, --agent=0 — the numeric agent ID to connect to.
  • --apps[=false] — watch deployments, replicasets, daemonsets, and statefulsets in the apps/v1 group.
  • --batch[=false] — watch jobs and cronjobs in the batch/v1 group.
  • --cluster-rbac[=false] — watch clusterroles and clusterrolebindings in the rbac.authorization.k8s.io/v1 group.
  • --core[=false] — watch pods, secrets, configmaps, and serviceaccounts in the core/v1 group.
  • --crd[=false] — watch customresourcedefinitions in the apiextensions.k8s.io/v1 group.
  • --ignore-arc-direction[=false] — ignore arc direction when evaluating root connectivity. requires GitLab and agent version 18.3 or later.
  • --listen-addr="localhost:0" — address to listen on.
  • --listen-net="tcp" — network on which to listen for connections.
  • --log-watch-request[=false] — log watch request to stdout. helpful for debugging. 🐛
  • -n, --namespace=[] — namespaces to watch. if not specified, all namespaces are watched with label and field selectors filtering.
  • --ns-expression="" — CEL expression to select namespaces. evaluated before a namespace is watched and on any updates for the namespace object.
  • --ns-field-selector="" — field selector to select namespaces.
  • --ns-label-selector="" — label selector to select namespaces.
  • --rbac[=false] — watch roles and rolebindings in the rbac.authorization.k8s.io/v1 group.
  • -r, --resource=[] — resources to watch. you can see the list of resources your cluster supports by running 'kubectl api-resources'.
  • --root-expression=[] — CEL expression to select root objects. requires GitLab and agent version 18.3 or later.
  • --stdin[=false] — read watch request from standard input.

👑 OPTIONS INHERITED FROM PARENT COMMANDS 👑

  • -h, --help[=false] — show help for this command.
  • -R, --repo="" — select another repository. you can use either OWNER/REPO or GROUP/NAMESPACE/REPO. the full URL or Git URL is also accepted. flexible queen 💅

🌈 EXAMPLE 🌈

# Run the default query for agent 123
glab cluster graph -R user/project -a 123

# Show common resources from the core and RBAC groups
glab cluster graph -R user/project -a 123 --core --rbac

# Show certain resources
glab cluster graph -R user/project -a 123 --resource=pods --resource=configmaps

# Same as above, but more compact
glab cluster graph -R user/project -a 123 -r={pods,configmaps}

# Select a certain namespace
glab cluster graph -R user/project -a 123 -n={my-ns,my-stuff}

# Select namespaces with a certain label
glab cluster graph -R user/project -a 123 --ns-label-selector environment=production

# Pass a custom watch request from a file
glab cluster graph -R user/project -a 123 --stdin < query.json

# Show objects reachable from pod roots
glab cluster graph -R user/project -a 123 --root-expression "resource == \"pods\""

⭐ SEE ALSO ⭐

and that's the whole page, bestie ✨ this lil' beauty was auto generated by spf13/cobra, dated Nov 2026, and it lives in the glab(1) manual — mwah, go query that graph 💋🎀

📦 where this page comes from