github.com/inspektor-gadget/inspektor-gadget@v0.28.1/docs/core-concepts/images.md (about) 1 --- 2 title: OCI artifacts 3 weight: 80 4 description: > 5 Handling gadgets as OCI artifacts. 6 --- 7 8 > ⚠️ This command is experimental and could change without prior notification. Check the installation guide to enable [experimental features](../getting-started/install-linux.md#experimental-features). 9 10 Gadgets in Inspektor Gadget are packaged as OCI artifacts. This document 11 describes the different commands available to interact with those artifacts and 12 with OCI registries. 13 14 See also [Gadgets as OCI artifacts reference documentation](../reference/oci.md) 15 16 If you're looking to run a gadget, check the [run](../guides/run.md) command. 17 18 ## Authentication 19 20 The authentication file holds the credentials necessary for communicating with the registry. By 21 default it is stored at `/var/lib/ig/config.json`. If the default authentication file does not exist 22 and you haven't specified one using either the `--authfile PATH` parameter for every involved ig 23 command or the environment variable `REGISTRY_AUTH_FILE`, your docker credentials 24 (`~/.docker/config.json`) will be used as fallback. 25 26 ## Commands 27 28 ### `login` 29 30 Login to a container registry. 31 32 ```bash 33 $ sudo ig login -h 34 Login to a container registry on a specified server. 35 36 Usage: 37 ig login [command options] REGISTRY [flags] 38 39 Flags: 40 --authfile string path of the authentication file. Use REGISTRY_AUTH_FILE environment variable to override 41 --cert-dir string use certificates at the specified path to access the registry 42 --get-login Return the current login user for the registry 43 -h, --help help for login 44 -p, --password string Password for registry 45 --password-stdin Take the password from stdin 46 -u, --username string Username for registry 47 -v, --verbose Write more detailed information to stdout 48 49 ``` 50 51 ```bash 52 $ sudo ig login ghcr.io -u mauriciovasquezbernal 53 INFO[0000] Experimental features enabled 54 Password: 55 Login Succeeded! 56 57 $ sudo ig login ghcr.io --get-login 58 INFO[0000] Experimental features enabled 59 mauriciovasquezbernal 60 ``` 61 62 ### `logout` 63 64 Logout of a container registry. 65 66 ```bash 67 $ sudo ig logout -h 68 INFO[0000] Experimental features enabled 69 Logout of a container registry on a specified server. 70 71 Usage: 72 ig logout [command options] REGISTRY [flags] 73 74 Flags: 75 -a, --all Remove the cached credentials for all registries in the auth file 76 --authfile string path of the authentication file. Use REGISTRY_AUTH_FILE environment variable to override 77 -h, --help help for logout 78 79 ``` 80 81 ```bash 82 $ sudo ig logout ghcr.io 83 INFO[0000] Experimental features enabled 84 Removed login credentials for ghcr.io 85 86 $ sudo ig login ghcr.io --get-login 87 INFO[0000] Experimental features enabled 88 Error: not logged into ghcr.io 89 ``` 90 91 ### `image` 92 93 ```bash 94 $ sudo ig image -h 95 INFO[0000] Experimental features enabled 96 Manage gadget images 97 98 Usage: 99 ig image [command] 100 101 Available Commands: 102 build Build a gadget image 103 list List gadget images on the host 104 pull Pull the specified image from a remote registry 105 push Push the specified image to a remote registry 106 tag Tag the local SRC_IMAGE image with the DST_IMAGE 107 ``` 108 109 The following subcommands are available: 110 111 #### `build` 112 113 The build command compiles and packages a gadget in an OCI image. 114 115 ```bash 116 $ sudo ig image build -h 117 INFO[0000] Experimental features enabled 118 Build a gadget image 119 120 Usage: 121 ig image build PATH [flags] 122 123 Flags: 124 --builder-image string Builder image to use (default "ghcr.io/inspektor-gadget/ebpf-builder:latest") 125 -f, --file string Path to build.yaml (default "build.yaml") 126 -h, --help help for build 127 -l, --local Build using local tools 128 -t, --tag string Name for the built image (format name:tag) 129 130 ``` 131 132 By default, the command looks for a `program.bpf.c` file containing the eBPF source code and for a 133 `gadget.yaml` with the gadget's metadata in PATH. 134 135 ```bash 136 $ ls 137 gadget.yaml program.bpf.c 138 139 $ sudo ig image build . 140 INFO[0000] Experimental features enabled 141 Successfully built sha256:adf9a4c636421d09e038eefa15623176195b0de482b25972e09b8bb3390bd3e 142 ``` 143 144 ##### Customizing your build 145 146 The building process is controlled by the `build.yaml` file. The following parameters are available: 147 148 - `ebpfsource`: eBPF source code file. It defaults to `program.bpf.c`. 149 - `metadata`: File containing metadata about the gadget. It defaults to `gadget.yaml`. 150 - `wasm`: Wasm module. It is unset by default. 151 - `cflags`: The C flags used to compile the eBPF program. It is unset by default. 152 153 By default, the build command looks for `build.yaml` in PATH. It can be changed with the `--file` flag: 154 155 ```bash 156 $ ls 157 another_name_for_gadget.yaml another_name_for_program.bpf.c mybuild.yaml 158 159 $ cat mybuild.yaml 160 ebpfsource: another_name_for_program.bpf.c 161 metadata: another_name_for_gadget.yaml 162 163 $ sudo ig image build . -f mybuild.yaml 164 INFO[0000] Experimental features enabled 165 Successfully built sha256:2f3ccd6254e232e6476f9f015b15f622c44831986f81a82eec17e9c55d98ccaf 166 ``` 167 168 ##### Toolchain location 169 170 It is possible to build a gadget using a builder container or by using a local toolchain. By default, 171 a container image provided by Inspektor Gadget with all the tools (compiler, libraries, 172 header files) needed to compiled your gadgets is used. A different container image can be specified with 173 `--builder-image`. This option requires docker to be available on the system. 174 175 `--local` can be used to use the tools installed in the local machine. In this case, you'll need to 176 have clang, llvm, the gadget headers (see make install-headers) and the [bpf 177 headers](https://github.com/libbpf/libbpf/blob/56069cda7897afdd0ae2478825845c7a7308c878/src/Makefile#L160) 178 installed. 179 180 In this case it's possible to control some of the tools used by setting some env variables: 181 182 ```bash 183 $ sudo CLANG=clang-15 LLVM_STRIP=llvm-strip-15 ig image build . -f mybuild.yaml --local 184 ``` 185 186 ##### Wasm module 187 188 A gadget can optionally include a wasm module. The wasm file is specified in the `wasm` field of `build.yaml`. 189 190 Supported files: 191 - `*.wasm`: prebuilt wasm module 192 - `*.go`: automatically built with tinygo 193 194 #### `list` 195 196 List gadget images on the host. 197 198 ```bash 199 $ sudo ig image list -h 200 INFO[0000] Experimental features enabled 201 List gadget images on the host 202 203 Usage: 204 ig image list [flags] 205 206 Flags: 207 -h, --help help for list 208 --no-trunc Don't truncate output 209 ``` 210 211 ```bash 212 $ sudo ig image list 213 INFO[0000] Experimental features enabled 214 REPOSITORY TAG DIGEST 215 docker.io/library/mygadget latest adf9a4c63642 216 ghcr.io/inspektor-gadget/trace_dns latest 95f570bdf511 217 ghcr.io/inspektor-gadget/trace_exec latest 328dd7a244b8 218 ghcr.io/inspektor-gadget/trace_open latest 3a23c1f08a8b 219 ``` 220 221 #### `remove` 222 223 Remove the given gadget image from the host. 224 225 ```bash 226 $ sudo ig image remove -h 227 INFO[0000] Experimental features enabled 228 Remove local gadget image 229 230 Usage: 231 ig image remove IMAGE [flags] 232 233 Flags: 234 -h, --help help for remove 235 236 ``` 237 238 ```bash 239 $ sudo ig image remove gadget 240 INFO[0000] Experimental features enabled 241 Successfully removed gadget 242 ``` 243 244 #### `pull` 245 246 Pull the specified image from a remote registry. 247 248 ```bash 249 $ sudo ig image pull -h 250 INFO[0000] Experimental features enabled 251 Pull the specified image from a remote registry 252 253 Usage: 254 ig image pull IMAGE [flags] 255 256 Flags: 257 --authfile string Path of the authentication file. This overrides the REGISTRY_AUTH_FILE environment variable (default "/var/lib/ig/config.json") 258 -h, --help help for pull 259 --insecure Allow connections to HTTP only registries 260 ``` 261 262 ```bash 263 $ sudo ig image pull ghcr.io/mauriciovasquezbernal/trace_open 264 INFO[0000] Experimental features enabled 265 Pulling ghcr.io/mauriciovasquezbernal/trace_open:latest... 266 Successfully pulled ghcr.io/mauriciovasquezbernal/trace_open:latest@sha256:842e69c79177908b6998737b86fc691e8fc0b3e45e2030cafcb362cbfcb1c039 267 ``` 268 269 #### `push` 270 271 Push the specified image to a remote registry. 272 273 ```bash 274 $ sudo ig image push -h 275 INFO[0000] Experimental features enabled 276 Push the specified image to a remote registry 277 278 Usage: 279 ig image push IMAGE [flags] 280 281 Flags: 282 --authfile string Path of the authentication file. This overrides the REGISTRY_AUTH_FILE environment variable (default "/var/lib/ig/config.json") 283 -h, --help help for push 284 --insecure Allow connections to HTTP only registrie 285 ``` 286 287 ```bash 288 $ sudo ig image push ghcr.io/mauriciovasquezbernal/trace_open 289 INFO[0000] Experimental features enabled 290 Pushing ghcr.io/mauriciovasquezbernal/trace_open:latest... 291 Successfully pushed ghcr.io/mauriciovasquezbernal/trace_open:latest@sha256:842e69c79177908b6998737b86fc691e8fc0b3e45e2030cafcb362cbfcb1c039 292 ``` 293 294 #### `tag` 295 296 Tag the local SRC_IMAGE image with the DST_IMAGE. 297 298 ```bash 299 $ sudo ig image tag -h 300 INFO[0000] Experimental features enabled 301 Tag the local SRC_IMAGE image with the DST_IMAGE 302 303 Usage: 304 ig image tag SRC_IMAGE DST_IMAGE [flags] 305 306 Flags: 307 -h, --help help for tag 308 ``` 309 310 ```bash 311 $ sudo ig image tag mygadget:latest ghcr.io/mauriciovasquezbernal/mygadget:latest 312 INFO[0000] Experimental features enabled 313 Successfully tagged with ghcr.io/mauriciovasquezbernal/mygadget:latest@sha256:adf9a4c636421d09e038eefa15623176195b0de482b25972e09b8bb3390bd3e9 314 ``` 315 316 #### `export` 317 318 Export the SRC_IMAGE images to DST_FILE. 319 320 ```bash 321 $ sudo ig image export -h 322 INFO[0000] Experimental features enabled 323 Export the SRC_IMAGE images to DST_FILE (experimental) 324 325 Usage: 326 ig image export SRC_IMAGE [SRC_IMAGE n] DST_FILE [flags] 327 328 Flags: 329 -h, --help help for export 330 ``` 331 332 ```bash 333 # Pull an image 334 $ sudo -E ig image pull ghcr.io/inspektor-gadget/gadget/trace_open 335 INFO[0000] Experimental features enabled 336 337 # Export it to a file 338 $ sudo -E ig image export ghcr.io/inspektor-gadget/gadget/trace_open trace_open.tar 339 INFO[0000] Experimental features enabled 340 Successfully exported images to trace_open.tar 341 342 $ ls -lnh trace_open.tar 343 -rw-r--r-- 1 0 0 181K abr 24 17:35 trace_open.tar 344 ``` 345 346 #### `import` 347 348 ```bash 349 $ sudo -E ig image import -h 350 INFO[0000] Experimental features enabled 351 Import images from SRC_FILE (experimental) 352 353 Usage: 354 ig image import SRC_FILE [flags] 355 356 Flags: 357 -h, --help help for import 358 ``` 359 360 ```bash 361 # Remove image if existing 362 $ sudo -E ig image remove trace_open 363 INFO[0000] Experimental features enabled 364 Successfully removed trace_open 365 366 $ sudo -E ig image list 367 INFO[0000] Experimental features enabled 368 REPOSITORY TAG DIGEST CREATED 369 370 # Import image exported above 371 $ sudo -E ig image import trace_open.tar 372 INFO[0000] Experimental features enabled 373 Successfully imported images: 374 ghcr.io/inspektor-gadget/gadget/trace_open:latest 375 376 $ sudo -E ig image list 377 INFO[0000] Experimental features enabled 378 REPOSITORY TAG DIGEST CREATED 379 trace_open latest 19ea8377298f 30 minutes ago 380 ```