chore(docs,cmd): updated default falcosecurity builderrepo; updated d…

…ocs.

Signed-off-by: Federico Di Pierro <nierro92@gmail.com>

cmd/root_options.go

@@ -33,7 +33,7 @@ type RootOptions struct {
 	Target           string   `validate:"required,target" name:"target"`
 	KernelConfigData string   `validate:"omitempty,base64" name:"kernel config data"` // fixme > tag "name" does not seem to work when used at struct level, but works when used at inner level
 	BuilderImage     string   `validate:"omitempty,imagename" name:"builder image"`
-	BuilderRepos     []string `default:"[\"docker.io/falcosecurity/driverkit\"]" validate:"omitempty" name:"docker repositories to look for builder images or absolute path pointing to a yaml file containing builder image index"`
+	BuilderRepos     []string `default:"[\"docker.io/falcosecurity/driverkit-builder\"]" validate:"omitempty" name:"docker repositories to look for builder images or absolute path pointing to a yaml file containing builder images index"`
 	GCCVersion       string   `validate:"omitempty,semvertolerant" name:"gcc version"`
 	KernelUrls       []string `name:"kernel header urls"`
 	Repo             RepoOptions

docs/builder_images.md

@@ -19,14 +19,20 @@ This is needed because driverkit logic must be able to differentiate eg: between
 an image that provides gcc4 and one that provides 4.8, in a reliable manner.
 
 The makefile will be then automatically able to collect the new docker images and pushing it as part of the CI.  
+Note: the images will be pushed under the `falcosecurity/driverkit-builder` repository, each with a tag reflecting its name, eg:  
+* `falcosecurity/driverkit-builder:centos-x86_64_gcc5.8.0_gcc6.0.0-latest`
+* `falcosecurity/driverkit-builder:any-x86_64_gcc12.0.0-454eff8fcc7d9abc615d312e9eccbd41abffb810`
+
+As you can see, the last part of the image tag is the real versioned tag (ie: `-latest` or `-$commithash`).
 
 ## Selection algorithm
 
-Once pushed, driverkit will be able to correctly load the image during startup, using a `docker search`.  
+Once pushed, driverkit will be able to correctly load the image during startup, using [falcoctl](https://github.com/falcosecurity/falcoctl/) OCI utilities.  
 Then, it will map images whose target and architecture are correct for the current build, storing the provided GCCs list.  
+Moreover, it will also take care of only using images with correct tag (ie: `latest` or `commithash`), as requested by user or automatically set by Makefile.
 The algorithm goes as follows:
-* load any image for the build arch and build target
-* load any image for the build arch and "any" target
+* load any image for the build arch, tag and target
+* load any image for the build arch, tag and "any" target
 * if any of the target-specific image provides the targetGCC for the build, we are over
 * if any of the "any" fallback image provides the targetGCC for the build, we are over
 * else, find the image between target-specific and fallback ones, that provides nearest GCC.  
@@ -35,8 +41,12 @@ In this latest step, there is no distinction between/different priority given to
 ## Customize builder images repos
 
 Moreover, users can also ship their own builder images in their own docker repositories, by using `--builderrepo` CLI option.  
-One can use this option multiple times; builder repos are a priority first list of docker repositories that can each provide up to 100 builder images.  
-Note that default falcosecurity repo will always be enforced as lowest priority repo.
+
+Instead of passing a docker repo, one can also pass the full path to a so-called builder images index yaml file.  
+It is mostly convenient in "static" scenarios, but it also gives the ability to freely define images name since all required infos are explicitly stated in the index file.  
+For an example of such a file, see [index.yaml](./index.yaml).
+
+One can use this option multiple times; builder repos are a priority first list of docker repositories or builder images indexes (they can be mixed too!).
 
 ## Force use a builder image
 
@@ -48,8 +58,6 @@ instead of relying on the internal algorithm, by using `--builderimage` CLI opti
 A special value for builder image is available:
 * `auto:$tag`, that is used to tell driverkit to use the automatic algorithm, but forcing a certain image tag
 
-> **NOTE**: since `docker search` has no way to differentiate between image tags, all builder images are expected to be tagged together.
-
 ## Force use a gcc version
 
 Users can specify the target gcc version of the build, using `--gccversion` option.  

docs/driverkit.md

@@ -11,7 +11,7 @@ driverkit
 ```
       --architecture string       target architecture for the built driver, one of [amd64,arm64] (default "amd64")
       --builderimage string       docker image to be used to build the kernel module and eBPF probe. If not provided, an automatically selected image will be used.
-      --builderrepo strings       list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit])
+      --builderrepo strings       list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit-builder])
   -c, --config string             config file path (default $HOME/.driverkit.yaml if exists)
       --driverversion string      driver version as a git commit hash or as a git tag (default "master")
       --dryrun                    do not actually perform the action

docs/driverkit_docker.md

@@ -11,7 +11,7 @@ driverkit docker [flags]
 ```
       --architecture string       target architecture for the built driver, one of [amd64,arm64] (default "amd64")
       --builderimage string       docker image to be used to build the kernel module and eBPF probe. If not provided, an automatically selected image will be used.
-      --builderrepo strings       list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit])
+      --builderrepo strings       list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit-builder])
   -c, --config string             config file path (default $HOME/.driverkit.yaml if exists)
       --driverversion string      driver version as a git commit hash or as a git tag (default "master")
       --dryrun                    do not actually perform the action

docs/driverkit_images.md

@@ -11,7 +11,7 @@ driverkit images [flags]
 ```
       --architecture string       target architecture for the built driver, one of [amd64,arm64] (default "amd64")
       --builderimage string       docker image to be used to build the kernel module and eBPF probe. If not provided, an automatically selected image will be used.
-      --builderrepo strings       list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit])
+      --builderrepo strings       list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit-builder])
   -c, --config string             config file path (default $HOME/.driverkit.yaml if exists)
       --driverversion string      driver version as a git commit hash or as a git tag (default "master")
       --dryrun                    do not actually perform the action

docs/driverkit_kubernetes-in-cluster.md

@@ -11,7 +11,7 @@ driverkit kubernetes-in-cluster [flags]
 ```
       --architecture string        target architecture for the built driver, one of [amd64,arm64] (default "amd64")
       --builderimage string        docker image to be used to build the kernel module and eBPF probe. If not provided, an automatically selected image will be used.
-      --builderrepo strings        list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit])
+      --builderrepo strings        list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit-builder])
   -c, --config string              config file path (default $HOME/.driverkit.yaml if exists)
       --driverversion string       driver version as a git commit hash or as a git tag (default "master")
       --dryrun                     do not actually perform the action

docs/driverkit_kubernetes.md

@@ -14,7 +14,7 @@ driverkit kubernetes [flags]
       --as-group stringArray           group to impersonate for the operation, this flag can be repeated to specify multiple groups
       --as-uid string                  uID to impersonate for the operation
       --builderimage string            docker image to be used to build the kernel module and eBPF probe. If not provided, an automatically selected image will be used.
-      --builderrepo strings            list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit])
+      --builderrepo strings            list of docker repositories or yaml file (absolute path) containing builder images index with the format 'images: [ { target:<target>, name:<image-name>, gcc_versions: [ <gcc-tag> ] },...]', in descending priority order. Used to search for builder images. eg: --builderrepo myorg/driverkit --builderrepo falcosecurity/driverkit --builderrepo '/path/to/my/index.yaml'. (default [docker.io/falcosecurity/driverkit-builder])
       --cache-dir string               default cache directory (default "$HOME/.kube/cache")
       --certificate-authority string   path to a cert file for the certificate authority
       --client-certificate string      path to a client certificate file for TLS

docs/index.yaml

@@ -13,6 +13,17 @@ images:
   # Contrarily to normal repo lister there is no constraint on it,
   # since all fields are already explicitly available
   - name: docker.io/foo/bar:mytag
+    target: arch
+    arch: x86_64
+    tag: mytag
+    gcc_versions:
+      - 13.1.1
+
+  # Image name tag ("mytag" in this case)
+  # is not even required to match "tag" property below,
+  # since the latter is used to match against the desired builder image tag for the build,
+  # while the former is the real image tag that will be used.
+  - name: docker.io/foo/baz:mytag
     target: arch
     arch: x86_64
     tag: latest