Headless Mode
Instead of running Gadgets interactively, you can also install Gadget Instances on your server, so they keep running even if you are no longer connected. This also ensures that Gadgets will be resumed after a node restart or - depending on the environment - when nodes are added to your cluster.
Creating Gadget Instances
To create a new Gadget Instance on your server / cluster, you can use the run
command with the --detach
option:
- gadgetctl
- kubectl-gadget
$ gadgetctl run trace_exec:latest --detach
INFO[0001] installed on node "local" as "61c8fdd9b75e1aec3c242347f18cf854"
$ kubectl gadget run trace_exec:latest --detach
INFO[0001] installed as "f0ff5614be1a0da655ea308e13ce6605"
ID NAME TAGS GADGET
4f5ae12c54bd serene_tu trace_open:latest
f0ff5614be1a brave_bartik trace_exec:latest
The command returns the ID of the newly installed Gadget Instance.
When upgrading server versions, please make sure to also upgrade all existing Gadget Instances to avoid compatibility issues. For example in Kubernetes you should see following warning in the server logs:
$ kubectl logs -n gadget -l k8s-app=gadget
...
time="2025-09-26T07:50:38Z" level=warning msg="This gadget was built with ig v0.42.0 and it's being run with v0.44.1. Gadget could be incompatible"
time="2025-09-26T07:50:40Z" level=error msg="running gadget: starting operators: starting operator \"oci\": starting operator \"ebpf\": creating eBPF collection: program ig_trace_dns: load program: bad CO-RE relocation: invalid func unknown#195896080 (303 line(s) omitted)"
...
Please delete and re-create the Gadget Instance to resolve this.
Listing Gadget Instances
To list all existing Gadget Instances on the server, you can run:
- gadgetctl
- kubectl-gadget
$ gadgetctl list
ID NAME TAGS GADGET
4f5ae12c54bd serene_tu trace_open:latest
61c8fdd9b75e brave_bartik trace_exec:latest
$ kubectl gadget list
ID NAME TAGS GADGET
4f5ae12c54bd serene_tu trace_open:latest
61c8fdd9b75e brave_bartik trace_exec:latest
Attaching to a Gadget Instance
If you want to see the output of the Gadget Instance, you can attach to it using the (partial) ID or name:
- gadgetctl
- kubectl-gadget
$ gadgetctl attach 61c8fdd9b75e
RUNTIME.CONTAINERNAME COMM PID TID PCOMM PPID ARGS ERR… USER LOGINUSER GROUP
magical_pike bash 282432 282432 containerd-s… 282410 /bin/bash root uid:4294967… root
magical_pike groups 282454 282454 bash 282453 /usr/bin/gro… root uid:4294967… root
magical_pike dircolors 282456 282456 bash 282455 /usr/bin/dir… root uid:4294967… root
$ gadgetctl attach brave_bartik
RUNTIME.CONTAINERNAME COMM PID TID PCOMM PPID ARGS ERR… USER LOGINUSER GROUP
magical_pike bash 282432 282432 containerd-s… 282410 /bin/bash root uid:4294967… root
magical_pike groups 282454 282454 bash 282453 /usr/bin/gro… root uid:4294967… root
magical_pike dircolors 282456 282456 bash 282455 /usr/bin/dir… root uid:4294967… root
$ kubectl gadget attach 61c8fdd9b75e
K8S.NODE K8S.NAMESPACE K8S.PODNAME K8S.CONTAINERNAME COMM PID TID UID GID FD FNAME MODE ERROR
minikube-docker kube-system kube-proxy-hr474 kube-proxy kube-proxy 4653 4692 0 0 10 /dev/null ----------
minikube-docker kube-system kube-proxy-hr474 kube-proxy kube-proxy 4653 4824 0 0 9 /dev/null ----------
minikube-docker kube-system kube-proxy-hr474 kube-proxy iptables 102586 102586 0 0 0 /etc/ld.so.cache ---------- ENOENT
minikube-docker kube-system kube-proxy-hr474 kube-proxy ip6tables 102587 102587 0 0 0 /etc/ld.so.cache ---------- ENOENT
minikube-docker kube-system kube-proxy-hr474 kube-proxy iptables 102586 102586 0 0 0 /lib/aarch64-linux-gnu/tls/aarch64… ---------- ENOENT
minikube-docker kube-system kube-proxy-hr474 kube-proxy ip6tables 102587 102587 0 0 0 /lib/aarch64-linux-gnu/tls/aarch64… ---------- ENOENT
$ kubectl gadget attach brave_bartik
K8S.NODE K8S.NAMESPACE K8S.PODNAME K8S.CONTAINERNAME COMM PID TID UID GID FD FNAME MODE ERROR
minikube-docker kube-system kube-proxy-hr474 kube-proxy kube-proxy 4653 4692 0 0 10 /dev/null ----------
minikube-docker kube-system kube-proxy-hr474 kube-proxy kube-proxy 4653 4824 0 0 9 /dev/null ----------
minikube-docker kube-system kube-proxy-hr474 kube-proxy iptables 102586 102586 0 0 0 /etc/ld.so.cache ---------- ENOENT
minikube-docker kube-system kube-proxy-hr474 kube-proxy ip6tables 102587 102587 0 0 0 /etc/ld.so.cache ---------- ENOENT
minikube-docker kube-system kube-proxy-hr474 kube-proxy iptables 102586 102586 0 0 0 /lib/aarch64-linux-gnu/tls/aarch64… ---------- ENOENT
minikube-docker kube-system kube-proxy-hr474 kube-proxy ip6tables 102587 102587 0 0 0 /lib/aarch64-linux-gnu/tls/aarch64… ---------- ENOENT
Deleting a Gadget Instance
To delete one or more Gadget Instances, just provide the names or (partial) IDs to the delete
command, like so:
- gadgetctl
- kubectl-gadget
$ gadgetctl delete 4f 61
4f5ae12c54bd7c2058c0484ebd13dbc2
61c8fdd9b75e1aec3c242347f18cf854
$ kubectl gadget delete 4f 61
4f5ae12c54bd7c2058c0484ebd13dbc2
61c8fdd9b75e1aec3c242347f18cf854