OCI artifacts

warning

This command is experimental and could change without prior notification. Check the installation guide to enable experimental features.

Gadgets in Inspektor Gadget are packaged as OCI artifacts. This document describes the different commands available to interact with those artifacts and with OCI registries.

See also Gadgets as OCI artifacts reference documentation

If you're looking to run a gadget, check the run command.

Authentication

The authentication file holds the credentials necessary for communicating with the registry. By default it is stored at /var/lib/ig/config.json. If the default authentication file does not exist and you haven't specified one using either the --authfile PATH parameter for every involved ig command or the environment variable REGISTRY_AUTH_FILE, your docker credentials (~/.docker/config.json) will be used as fallback.

Commands

login

Login to a container registry.

$ sudo ig login -h
Login to a container registry on a specified server.

Usage:
  ig login [command options] REGISTRY [flags]

Flags:
      --authfile string   path of the authentication file. Use REGISTRY_AUTH_FILE environment variable to override
      --cert-dir string   use certificates at the specified path to access the registry
      --get-login         Return the current login user for the registry
  -h, --help              help for login
  -p, --password string   Password for registry
      --password-stdin    Take the password from stdin
  -u, --username string   Username for registry
  -v, --verbose           Write more detailed information to stdout

$ sudo ig login ghcr.io -u mauriciovasquezbernal
INFO[0000] Experimental features enabled
Password:
Login Succeeded!

$ sudo ig login ghcr.io --get-login
INFO[0000] Experimental features enabled
mauriciovasquezbernal

logout

Logout of a container registry.

$ sudo ig logout -h
INFO[0000] Experimental features enabled
Logout of a container registry on a specified server.

Usage:
  ig logout [command options] REGISTRY [flags]

Flags:
  -a, --all               Remove the cached credentials for all registries in the auth file
      --authfile string   path of the authentication file. Use REGISTRY_AUTH_FILE environment variable to override
  -h, --help              help for logout

$ sudo ig logout ghcr.io
INFO[0000] Experimental features enabled
Removed login credentials for ghcr.io

$ sudo ig login ghcr.io --get-login
INFO[0000] Experimental features enabled
Error: not logged into ghcr.io

image

$ sudo ig image -h
INFO[0000] Experimental features enabled
Manage gadget images

Usage:
  ig image [command]

Available Commands:
  build       Build a gadget image
  list        List gadget images on the host
  pull        Pull the specified image from a remote registry
  push        Push the specified image to a remote registry
  tag         Tag the local SRC_IMAGE image with the DST_IMAGE

The following subcommands are available:

build

The build command compiles and packages a gadget in an OCI image.

$ sudo ig image build -h
INFO[0000] Experimental features enabled
Build a gadget image

Usage:
  ig image build PATH [flags]

Flags:
      --builder-image string   Builder image to use (default "ghcr.io/inspektor-gadget/ebpf-builder:latest")
  -f, --file string            Path to build.yaml (default "build.yaml")
  -h, --help                   help for build
  -l, --local                  Build using local tools
  -t, --tag string             Name for the built image (format name:tag)

By default, the command looks for a program.bpf.c file containing the eBPF source code and for a gadget.yaml with the gadget's metadata in PATH.

$ ls
gadget.yaml  program.bpf.c

$ sudo ig image build .
INFO[0000] Experimental features enabled
Successfully built sha256:adf9a4c636421d09e038eefa15623176195b0de482b25972e09b8bb3390bd3e

Customizing your build

The building process is controlled by the build.yaml file. The following parameters are available:

• ebpfsource: eBPF source code file. It defaults to program.bpf.c.
• metadata: File containing metadata about the gadget. It defaults to gadget.yaml.
• wasm: Wasm module. It is unset by default.
• cflags: The C flags used to compile the eBPF program. It is unset by default.

By default, the build command looks for build.yaml in PATH. It can be changed with the --file flag:

$ ls
another_name_for_gadget.yaml  another_name_for_program.bpf.c  mybuild.yaml

$ cat mybuild.yaml
ebpfsource: another_name_for_program.bpf.c
metadata: another_name_for_gadget.yaml

$ sudo ig image build . -f mybuild.yaml
INFO[0000] Experimental features enabled
Successfully built sha256:2f3ccd6254e232e6476f9f015b15f622c44831986f81a82eec17e9c55d98ccaf

Toolchain location

It is possible to build a gadget using a builder container or by using a local toolchain. By default, a container image provided by Inspektor Gadget with all the tools (compiler, libraries, header files) needed to compiled your gadgets is used. A different container image can be specified with --builder-image. This option requires docker to be available on the system.

--local can be used to use the tools installed in the local machine. In this case, you'll need to have clang, llvm, the gadget headers (see make install-headers) and the bpf headers installed.

In this case it's possible to control some of the tools used by setting some env variables:

$ sudo CLANG=clang-15 LLVM_STRIP=llvm-strip-15 ig image build . -f mybuild.yaml --local

Wasm module

A gadget can optionally include a wasm module. The wasm file is specified in the wasm field of build.yaml.

Supported files:

• *.wasm: prebuilt wasm module
• *.go: automatically built with tinygo

Reproducible builds

The build command supports the SOURCE_DATE_EPOCH env variable:

# Set SOURCE_DATE_EPOCH to the last modification of the ebpf program source code.
# It can be set to any epoch you want.
$ export SOURCE_DATE_EPOCH="$(date -r program.bpf.c +%s)"

$ sudo -E ig image build -t foo:latest .
INFO[0000] Experimental features enabled
Successfully built ghcr.io/inspektor-gadget/gadget/foo:latest@sha256:373f077d366ef2703535e8e862b60f8a35cc1a9312e9e203534b8fce554f8749

# Building again produces the exact same digest
$ sudo -E ig image build -t foo:latest .
INFO[0000] Experimental features enabled
Successfully built ghcr.io/inspektor-gadget/gadget/foo:latest@sha256:373f077d366ef2703535e8e862b60f8a35cc1a9312e9e203534b8fce554f8749

list

List gadget images on the host.

$ sudo ig image list -h
INFO[0000] Experimental features enabled
List gadget images on the host

Usage:
  ig image list [flags]

Flags:
  -h, --help       help for list
      --no-trunc   Don't truncate output

$ sudo ig image list
INFO[0000] Experimental features enabled
REPOSITORY                                            TAG                                                   DIGEST
docker.io/library/mygadget                            latest                                                adf9a4c63642
ghcr.io/inspektor-gadget/trace_dns                    latest                                                95f570bdf511
ghcr.io/inspektor-gadget/trace_exec                   latest                                                328dd7a244b8
ghcr.io/inspektor-gadget/trace_open                   latest                                                3a23c1f08a8b

remove

Remove the given gadget image from the host.

$ sudo ig image remove -h
INFO[0000] Experimental features enabled
Remove local gadget image

Usage:
  ig image remove IMAGE [flags]

Flags:
  -h, --help   help for remove

$ sudo ig image remove gadget
INFO[0000] Experimental features enabled
Successfully removed gadget

pull

Pull the specified image from a remote registry.

$ sudo ig image pull -h
INFO[0000] Experimental features enabled
Pull the specified image from a remote registry

Usage:
  ig image pull IMAGE [flags]

Flags:
      --authfile string   Path of the authentication file. This overrides the REGISTRY_AUTH_FILE environment variable (default "/var/lib/ig/config.json")
  -h, --help              help for pull
      --insecure          Allow connections to HTTP only registries

$ sudo ig image pull ghcr.io/mauriciovasquezbernal/trace_open
INFO[0000] Experimental features enabled
Pulling ghcr.io/mauriciovasquezbernal/trace_open:latest...
Successfully pulled ghcr.io/mauriciovasquezbernal/trace_open:latest@sha256:842e69c79177908b6998737b86fc691e8fc0b3e45e2030cafcb362cbfcb1c039

push

Push the specified image to a remote registry.

$ sudo ig image push -h
INFO[0000] Experimental features enabled
Push the specified image to a remote registry

Usage:
  ig image push IMAGE [flags]

Flags:
      --authfile string   Path of the authentication file. This overrides the REGISTRY_AUTH_FILE environment variable (default "/var/lib/ig/config.json")
  -h, --help              help for push
      --insecure          Allow connections to HTTP only registrie

$ sudo ig image push ghcr.io/mauriciovasquezbernal/trace_open
INFO[0000] Experimental features enabled
Pushing ghcr.io/mauriciovasquezbernal/trace_open:latest...
Successfully pushed ghcr.io/mauriciovasquezbernal/trace_open:latest@sha256:842e69c79177908b6998737b86fc691e8fc0b3e45e2030cafcb362cbfcb1c039

tag

Tag the local SRC_IMAGE image with the DST_IMAGE.

$ sudo ig image tag -h
INFO[0000] Experimental features enabled
Tag the local SRC_IMAGE image with the DST_IMAGE

Usage:
  ig image tag SRC_IMAGE DST_IMAGE [flags]

Flags:
  -h, --help   help for tag

$ sudo ig image tag mygadget:latest ghcr.io/mauriciovasquezbernal/mygadget:latest
INFO[0000] Experimental features enabled
Successfully tagged with ghcr.io/mauriciovasquezbernal/mygadget:latest@sha256:adf9a4c636421d09e038eefa15623176195b0de482b25972e09b8bb3390bd3e9

export

Export the SRC_IMAGE images to DST_FILE.

$ sudo ig image export -h
INFO[0000] Experimental features enabled
Export the SRC_IMAGE images to DST_FILE (experimental)

Usage:
  ig image export SRC_IMAGE [SRC_IMAGE n] DST_FILE [flags]

Flags:
  -h, --help   help for export

# Pull an image
$ sudo -E ig image pull ghcr.io/inspektor-gadget/gadget/trace_open
INFO[0000] Experimental features enabled

# Export it to a file
$ sudo -E ig image export ghcr.io/inspektor-gadget/gadget/trace_open trace_open.tar
INFO[0000] Experimental features enabled
Successfully exported images to trace_open.tar

$ ls -lnh trace_open.tar
-rw-r--r-- 1 0 0 181K abr 24 17:35 trace_open.tar

import

$ sudo -E ig image import -h
INFO[0000] Experimental features enabled
Import images from SRC_FILE (experimental)

Usage:
  ig image import SRC_FILE [flags]

Flags:
  -h, --help   help for import

# Remove image if existing
$ sudo -E ig image remove trace_open
INFO[0000] Experimental features enabled
Successfully removed trace_open

$ sudo -E ig image list
INFO[0000] Experimental features enabled
REPOSITORY                     TAG                           DIGEST       CREATED

# Import image exported above
$ sudo -E ig image import trace_open.tar
INFO[0000] Experimental features enabled
Successfully imported images:
  ghcr.io/inspektor-gadget/gadget/trace_open:latest

$ sudo -E ig image list
INFO[0000] Experimental features enabled
REPOSITORY                     TAG                           DIGEST       CREATED
trace_open                     latest                        19ea8377298f 30 minutes ago