OCI artifacts

    ⚠️ 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.

    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

    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 ta
    
    $ 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