GitLabgitlab-org

cli

main
ply8 git calls384 ms97 KiB6 cachedprotocol v2
135 lines6.5 KiBRaw

Query the Kubernetes object graph using the GitLab Agent for Kubernetes. (EXPERIMENTAL)

Synopsis

This command starts a web server that shows a live view of the Kubernetes object graph in a browser. It uses the GitLab Agent for Kubernetes running in the cluster. It requires:

  • Version 18.1 or later of GitLab and the GitLab Agent.
  • At least the Developer role in the agent project.
  • This command requires a personal access token or project access token for authentication. The token must have the read_api and k8s_proxy scopes.

Leave feedback in issue 7900.

Resource filtering

To filter resources, namespaces, and select root objects, use Common Expression Language (CEL).

object_selector_expression: Filters objects. The expression must return a boolean. These variables are available:

  • 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. The expression must return a boolean. These variables are available:

  • 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 set, only objects that are directly or transitively reachable from root objects are shown. This flag uses the same variables as object_selector_expression, and must return a boolean. Multiple values are joined with OR statements. If any match, the object is used as root.

For more information about using label selectors and field selectors to select namespaces, see the Kubernetes documentation.

Advanced usage

Apart from high-level ways to construct the query, this command enables you to construct and send the query using all underlying API features. To understand what is possible, and how to do it, see the technical design doc

The user should have permission to access the agent project. For more information, see Grant users Kubernetes access.

This feature is an experiment and is not ready for production use. It might be unstable or removed at any time. For more information, see https://docs.gitlab.com/policy/development_stages_support/.

plaintext
glab cluster graph [flags]

Examples

console
# 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\""

Options

plaintext
  -a, --agent int                     The numeric agent ID to connect to.
      --apps                          Watch deployments, replicasets, daemonsets, and statefulsets in the apps/v1 group.
      --batch                         Watch jobs and cronjobs in the batch/v1 group.
      --cluster-rbac                  Watch clusterroles and clusterrolebindings in the rbac.authorization.k8s.io/v1 group.
      --core                          Watch pods, secrets, configmaps, and serviceaccounts in the core/v1 group.
      --crd                           Watch customresourcedefinitions in the apiextensions.k8s.io/v1 group.
      --ignore-arc-direction          Ignore arc direction when evaluating root connectivity. Requires GitLab and agent version 18.3 or later.
      --listen-addr string            Address to listen on. (default "localhost:0")
      --listen-net string             Network on which to listen for connections. (default "tcp")
      --log-watch-request             Log watch request to stdout. Helpful for debugging.
  -n, --namespace stringArray         Namespaces to watch. If not specified, all namespaces are watched with label and field selectors filtering.
      --ns-expression string          CEL expression to select namespaces. Evaluated before a namespace is watched and on any updates for the namespace object.
      --ns-field-selector string      Field selector to select namespaces.
      --ns-label-selector string      Label selector to select namespaces.
      --rbac                          Watch roles and rolebindings in the rbac.authorization.k8s.io/v1 group.
  -r, --resource stringArray          Resources to watch. You can see the list of resources your cluster supports by running 'kubectl api-resources'.
      --root-expression stringArray   CEL expression to select root objects. Requires GitLab and agent version 18.3 or later.
      --stdin                         Read watch request from standard input.

Options inherited from parent commands

plaintext
  -h, --help          Show help for this command.
  -R, --repo string   Select another repository. You can use either OWNER/REPO or GROUP/NAMESPACE/REPO. The full URL or Git URL is also accepted.
1---
2title: '`glab cluster graph`'
3stage: AI Clients
4group: Developer Clients
5info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/marketing/product-and-technical-marketing/technical-writing/#assignments>
6---
8<!--
9This documentation is auto generated by a script.
10Please do not edit this file directly. Run `make gen-docs` instead.
11-->
13Query the Kubernetes object graph using the GitLab Agent for Kubernetes. (EXPERIMENTAL)
15## Synopsis
17This command starts a web server that shows a live view of the Kubernetes object graph in a browser.
18It uses the GitLab Agent for Kubernetes running in the cluster.
19It requires:
21- Version 18.1 or later of GitLab and the GitLab Agent.
22- At least the Developer role in the agent project.
23- This command requires a personal access token or project access token
24 for authentication. The token must have the `read_api` and `k8s_proxy` scopes.
26Leave feedback in [issue 7900](https://gitlab.com/gitlab-org/cli/-/issues/7900).
28### Resource filtering
30To filter resources, namespaces, and select root objects, use
31[Common Expression Language (CEL)](https://cel.dev/).
33`object_selector_expression`: Filters objects. The expression must return a boolean. These variables are available:
35- `obj`: The Kubernetes object being evaluated.
36- `group`: The group of the object.
37- `version`: The version of the object.
38- `resource`: The resource name of the object, like `pods` for the `Pod` kind.
39- `namespace`: The namespace of the object.
40- `name`: The name of the object.
41- `labels`: The labels of the object.
42- `annotations`: The annotations of the object.
44`resource_selector_expression`: Filters Kubernetes discovery information to include or exclude resources
45from the watch request. The expression must return a boolean. These variables are available:
47- `group`: The group of the object.
48- `version`: The version of the object.
49- `resource`: The resource name of the object, like `pods` for the `Pod` kind.
50- `namespaced`: The scope of group, version, and resource. Can be `bool`, `true`, or `false`.
52To select root objects, use the `--root-expression` flag. When set, only objects that are directly
53or transitively reachable from root objects are shown. This flag uses the same variables
54as `object_selector_expression`, and must return a boolean. Multiple values are joined with `OR`
55statements. If any match, the object is used as root.
57For more information about using [label selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors)
58and [field selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/) to select namespaces, see the Kubernetes documentation.
60### Advanced usage
62Apart from high-level ways to construct the query, this command enables
63you to construct and send the query using all underlying API features.
64To understand what is possible, and how to do it, see the
65[technical design doc](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/graph_api.md)
67The user should have permission to access the agent project.
68For more information, see [Grant users Kubernetes access](https://docs.gitlab.com/user/clusters/agent/user_access/).
70This feature is an experiment and is not ready for production use.
71It might be unstable or removed at any time.
72For more information, see
73<https://docs.gitlab.com/policy/development_stages_support/>.
75```plaintext
76glab cluster graph [flags]
77```
79## Examples
81```console
82# Run the default query for agent 123
83glab cluster graph -R user/project -a 123
85# Show common resources from the core and RBAC groups
86glab cluster graph -R user/project -a 123 --core --rbac
88# Show certain resources
89glab cluster graph -R user/project -a 123 --resource=pods --resource=configmaps
91# Same as above, but more compact
92glab cluster graph -R user/project -a 123 -r={pods,configmaps}
94# Select a certain namespace
95glab cluster graph -R user/project -a 123 -n={my-ns,my-stuff}
97# Select namespaces with a certain label
98glab cluster graph -R user/project -a 123 --ns-label-selector environment=production
100# Pass a custom watch request from a file
101glab cluster graph -R user/project -a 123 --stdin < query.json
103# Show objects reachable from pod roots
104glab cluster graph -R user/project -a 123 --root-expression "resource == \"pods\""
105```
107## Options
109```plaintext
110 -a, --agent int The numeric agent ID to connect to.
111 --apps Watch deployments, replicasets, daemonsets, and statefulsets in the apps/v1 group.
112 --batch Watch jobs and cronjobs in the batch/v1 group.
113 --cluster-rbac Watch clusterroles and clusterrolebindings in the rbac.authorization.k8s.io/v1 group.
114 --core Watch pods, secrets, configmaps, and serviceaccounts in the core/v1 group.
115 --crd Watch customresourcedefinitions in the apiextensions.k8s.io/v1 group.
116 --ignore-arc-direction Ignore arc direction when evaluating root connectivity. Requires GitLab and agent version 18.3 or later.
117 --listen-addr string Address to listen on. (default "localhost:0")
118 --listen-net string Network on which to listen for connections. (default "tcp")
119 --log-watch-request Log watch request to stdout. Helpful for debugging.
120 -n, --namespace stringArray Namespaces to watch. If not specified, all namespaces are watched with label and field selectors filtering.
121 --ns-expression string CEL expression to select namespaces. Evaluated before a namespace is watched and on any updates for the namespace object.
122 --ns-field-selector string Field selector to select namespaces.
123 --ns-label-selector string Label selector to select namespaces.
124 --rbac Watch roles and rolebindings in the rbac.authorization.k8s.io/v1 group.
125 -r, --resource stringArray Resources to watch. You can see the list of resources your cluster supports by running 'kubectl api-resources'.
126 --root-expression stringArray CEL expression to select root objects. Requires GitLab and agent version 18.3 or later.
127 --stdin Read watch request from standard input.
128```
130## Options inherited from parent commands
132```plaintext
133 -h, --help Show help for this command.
134 -R, --repo string Select another repository. You can use either OWNER/REPO or GROUP/NAMESPACE/REPO. The full URL or Git URL is also accepted.
135```
Diagnostics8 git calls · 384 ms
CallStatusSizeTime0384 ms
discover200185 B138 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=21
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB313 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=175
git.response.bytes=59849
git.response.cache=EXPIRED
git.response.duration_ms=175
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit7 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=6
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=7
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchtree:02001.1 KiB · hit33 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=33
git.response.bytes=1112
git.response.cache=HIT
git.response.duration_ms=33
git.fetch.filter=tree:0
git.fetch.wants=fed5065f0120a857fec6fa567dcdacfd34c3187b
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1112
git.pkt.payload.max=1085
git.sideband.band1.bytes=1085
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1085
git.pack.trailer=792a8e6885c3db50fcc6be7a28de09363c6fb5e4
Open pack map
fetchtree:0200650 B · hit5 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=5
git.response.bytes=650
git.response.cache=HIT
git.response.duration_ms=5
git.fetch.filter=tree:0
git.fetch.wants=e2312cec91295d8042fa9ab0265a7cd64fad5c13
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=650
git.pkt.payload.max=623
git.sideband.band1.bytes=623
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=623
git.pack.trailer=140f0d5f3d6c8c8ef55e7d2581e9a7bd5f2fd4d6
Open pack map
fetchtree:02001.7 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=1744
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=5e4007a5673eb3bf5d0d7f1a1463c3b2ca3fb3bd
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1744
git.pkt.payload.max=1717
git.sideband.band1.bytes=1717
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1717
git.pack.trailer=3f1b9ccc7756e8941d6705e8187c87fd922113e6
Open pack map
fetchtree:0200171 B · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=171
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=tree:0
git.fetch.wants=deb8abea1ce2956a8875db697874c5f77b7d5ca9
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=171
git.pkt.payload.max=144
git.sideband.band1.bytes=144
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=144
git.pack.trailer=1230c2ed51d56fb4bf9715659a42d5c9953cfde8
Open pack map
fetch2002.4 KiB · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=19
git.response.bytes=2506
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.wants=bb67afe5e1e9a634431686e27e0aac24d8b784fd
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2506
git.pkt.payload.max=2479
git.sideband.band1.bytes=2479
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e98b6b98c73191
Request
fc33745e…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format