glab(1) glab(1)

glab-cluster-graph - Query Kubernetes object graph using GitLab Agent for Kubernetes. (EXPERIMENTAL)

glab cluster graph [flags]

This commands starts a web server that shows a live view of Kubernetes objects graph in a browser. It works via the GitLab Agent for Kubernetes running in the cluster. The minimum required GitLab and GitLab Agent version is v18.1.

Please leave feedback in this issue ⟨https://gitlab.com/gitlab-org/cli/-/issues/7900⟩.

Resources and namespaces can be filterer using CEL expressions ⟨https://cel.dev/⟩.

object_selector_expression can be used to filter objects. The expression must return a boolean. The following variables are available:

  • obj is the Kubernetes object being evaluated.
  • group group of the object.
  • version version of the object.
  • resource resource name of the object. E.g. pods for the Pod kind.
  • namespace namespace of the object.
  • name name of the object.
  • labels labels of the object.
  • annotations annotations of the object.

resource_selector_expression can be used to filter Kubernetes discovery information to include/exclude resources from the watch request. The expression must return a boolean. The following variables are available:

  • group group of the object.
  • version version of the object.
  • resource resource name of the object. E.g. pods for the Pod kind.
  • namespaced scope of group+version+resource. Can be bool true or false.

Apart from high level ways to construct the query, this command allows you to construct and send the query using all the underlying API capabilities. Please see the technical design doc ⟨https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/graph_api.md⟩ to understand what is possible and how to do it.

This command only supports personal and project access tokens for authentication. The token should have at least the Developer role in the agent project and the read_api and k8s_proxy scopes.

This feature is experimental. It might be broken or removed without any prior notice. Read more about what experimental features mean at

⟨https://docs.gitlab.com/policy/development_stages_support/⟩

Use experimental features at your own risk.

-a, --agent=0 The numerical Agent ID to connect to.

--apps[=false] Watch deployments, replicasets, daemonsets, and statefulsets in apps/v1 group.

--batch[=false] Watch jobs, and cronjobs in batch/v1 group.

--cluster-rbac[=false] Watch clusterroles, and clusterrolebindings in rbac.authorization.k8s.io/v1 group.

--core[=false] Watch pods, secrets, configmaps, and serviceaccounts in core/v1 group

--crd[=false] Watch customresourcedefinitions in apiextensions.k8s.io/v1 group.

--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. Can be useful 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. See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/.

--ns-label-selector="" Label selector to select namespaces. See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors.

--rbac[=false] Watch roles, and rolebindings in rbac.authorization.k8s.io/v1 group.

-r, --resources=[] A list of resources to watch. You can see the list of resources your cluster supports by running kubectl api-resources.

--stdin[=false] Read watch request from standard input.

--help[=false] Show help for this command.

-R, --repo="" Select another repository. Can use either OWNER/REPO or GROUP/NAMESPACE/REPO format. Also accepts full URL or Git URL.

# 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 --resources=pods --resources=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 all namespaces that have a certain annotation
$ glab cluster graph -R user/project -a 123 --ns-expression='"my-annotation" in annotations'
# Advanced usage - pass the full query directly via stdin.
# The query below watches serviceaccounts in all namespaces except for the kube-system.
$ Q='{"queries":[{"include":{"resource_selector_expression":"resource == \"serviceaccounts\""}}],"namespaces":{"object_selector_expression":"name != \"kube-system\""}}'
$ echo -n "$Q" | glab cluster graph -R user/project -a 123 --stdin

glab-cluster(1)

Jun 2025 Auto generated by spf13/cobra