.nh
.TH "glab" "1" "Jun 2025" "Auto generated by spf13/cobra" ""

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


.SH SYNOPSIS
\fBglab cluster graph [flags]\fP


.SH DESCRIPTION
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.

.PP
Please leave feedback in this issue
\[la]https://gitlab.com/gitlab\-org/cli/\-/issues/7900\[ra]\&.

.SS Resource filtering
Resources and namespaces can be filterer using CEL expressions
\[la]https://cel.dev/\[ra]\&.

.PP
\fBobject_selector_expression\fR can be used to filter objects. The expression must return a boolean. The following variables are available:
.IP \(bu 2
\fBobj\fR is the Kubernetes object being evaluated.
.IP \(bu 2
\fBgroup\fR group of the object.
.IP \(bu 2
\fBversion\fR version of the object.
.IP \(bu 2
\fBresource\fR resource name of the object. E.g. pods for the Pod kind.
.IP \(bu 2
\fBnamespace\fR namespace of the object.
.IP \(bu 2
\fBname\fR name of the object.
.IP \(bu 2
\fBlabels\fR labels of the object.
.IP \(bu 2
\fBannotations\fR annotations of the object.

.PP
\fBresource_selector_expression\fR 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:
.IP \(bu 2
\fBgroup\fR group of the object.
.IP \(bu 2
\fBversion\fR version of the object.
.IP \(bu 2
\fBresource\fR resource name of the object. E.g. pods for the Pod kind.
.IP \(bu 2
\fBnamespaced\fR scope of group+version+resource. Can be \fBbool\fR \fBtrue\fR or \fBfalse\fR\&.

.SS Advanced usage
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
\[la]https://gitlab.com/gitlab\-org/cluster\-integration/gitlab\-agent/\-/blob/master/doc/graph_api.md\[ra]
to understand what is possible and how to do it.

.PP
This command only supports personal and project access tokens for authentication.
The token should have at least the \fBDeveloper\fR role in the agent project and the \fBread_api\fR and \fBk8s_proxy\fR scopes.

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

\[la]https://docs.gitlab.com/policy/development_stages_support/\[ra]

.PP
Use experimental features at your own risk.


.SH OPTIONS
\fB-a\fP, \fB--agent\fP=0
	The numerical Agent ID to connect to.

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

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

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

.PP
\fB--core\fP[=false]
	Watch pods, secrets, configmaps, and serviceaccounts in core/v1 group

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

.PP
\fB--listen-addr\fP="localhost:0"
	Address to listen on.

.PP
\fB--listen-net\fP="tcp"
	Network on which to listen for connections.

.PP
\fB--log-watch-request\fP[=false]
	Log watch request to stdout. Can be useful for debugging.

.PP
\fB-n\fP, \fB--namespace\fP=[]
	Namespaces to watch. If not specified, all namespaces are watched with label and field selectors filtering.

.PP
\fB--ns-expression\fP=""
	CEL expression to select namespaces. Evaluated before a namespace is watched and on any updates for the namespace object.

.PP
\fB--ns-field-selector\fP=""
	Field selector to select namespaces. See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/.

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

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

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

.PP
\fB--stdin\fP[=false]
	Read watch request from standard input.


.SH OPTIONS INHERITED FROM PARENT COMMANDS
\fB--help\fP[=false]
	Show help for this command.

.PP
\fB-R\fP, \fB--repo\fP=""
	Select another repository. Can use either \fBOWNER/REPO\fR or \fBGROUP/NAMESPACE/REPO\fR format. Also accepts full URL or Git URL.


.SH EXAMPLE
.EX
# 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

.EE


.SH SEE ALSO
\fBglab-cluster(1)\fP