feat(kb/kaniko): use local cache

knowledge base/kaniko.md

@@ -9,14 +9,15 @@ Tool to build container images from a Dockerfile with**out** the need of the Doc
 
 ## TL;DR
 
-Kaniko requires to be run from a container using the `gcr.io/kaniko-project/executor` image.
+Kaniko **requires** to be run from a container using the `gcr.io/kaniko-project/executor` image.
 
-It builds images completely in userspace from within the container by executing the Dockerfile's commands in order and
-taking a snapshot of the file system after each command result.<br/>
-Should there be any changes to the file system, Kaniko takes a snapshot of the change as a _diff_ layer and updates the
-resulting image's metadata.
+It builds images completely in userspace from within the container.<br/>
+It does so by executing the Dockerfile's commands, in order, in a directory on the current file system. Should a command
+make any changes in that directory, Kaniko takes a snapshot of it as a _diff_ layer and updates the resulting image's
+metadata.
 
-kaniko supports the following storage solutions for the build contexts:
+Kaniko, like Docker, requires a context for the build process.<br/>
+It is defined by the `--context` option and supports the following storage solutions:
 
 - GCS Bucket
 - S3 Bucket
@@ -26,11 +27,18 @@ kaniko supports the following storage solutions for the build contexts:
 - Standard Input
 - Git Repository
 
-The executor image has the following built in:
+The executor's image has the following utilities built in:
 
 - Amazon ECR credential helper.
 - Azure ACR credential helper.
 
+Enable the cache with the `--cache` option.<br/>
+If using the cache, it (either-or):
+
+- Has to be a container registry.
+- Has to be pre-populated, as Kaniko is currently **not** able to manage local caches during execution.<br/>
+  Leverage the `warmer` utility in Kaniko for this. Refer [Cache and Kaniko].
+
 <details>
   <summary>Setup</summary>
 
@@ -46,6 +54,7 @@ docker pull 'gcr.io/kaniko-project/executor:v1.23.2-debug'
   <summary>Usage</summary>
 
 ```sh
+docker run --rm -ti -v "$PWD:/workspace" 'gcr.io/kaniko-project/executor' --no-push
 docker run --rm --name 'kaniko' -ti -v "$PWD:/workspace" 'gcr.io/kaniko-project/executor' \
   --context '/workspace/context' --dockerfile '/workspace/context/Dockerfile' --no-push
 docker run … \
@@ -61,6 +70,10 @@ docker run … \
     --destination 'mycr.azurecr.io/azure-repository:1.2.3'
 docker run … -v "$PWD/config.json:/kaniko/.docker/config.json:ro" 'gcr.io/kaniko-project/executor:latest'
 docker run … 'gcr.io/kaniko-project/executor' … --cache --custom-platform 'linux/amd64' --build-arg VERSION='1.2'
+
+# Populate build caches.
+docker run -it --rm -v "$PWD/cache:/cache" 'gcr.io/kaniko-project/warmer' \
+  --image='maven:3-jdk-11-slim' --image='openjdk:11-jre-slim'
 ```
 
 </details>
@@ -68,14 +81,40 @@ docker run … 'gcr.io/kaniko-project/executor' … --cache --custom-platform 'l
 <details>
   <summary>Real world use cases</summary>
 
+  <details style="padding-left: 1rem">
+    <summary>Create local images using local cache</summary>
+
+Uses images from the local cache.<br/>
+It does **not** _save_ cache images in the local cache directory since Kaniko is currently **not** able to manage such
+caches during execution. Refer [Cache and Kaniko].
+
+Creates a root-owned file called `image.tar` in the current directory.<br/>
+Run `docker load -i 'image.tar'` to load it into Docker as `image:1.0`.
+
+Image and repository names can only contain the characters `abcdefghijklmnopqrstuvwxyz0123456789_-./`.
+
 ```sh
-# Test the Dockerfile from an Ansible execution environment the way a GitLab pipeline would need to execute it.
-docker run --rm -ti -v "$PWD:/workspace" --entrypoint '' 'gcr.io/kaniko-project/executor:v1.23.2-debug' \
-  /kaniko/executor --context '/workspace/context' --dockerfile '/workspace/context/Dockerfile' --no-push
+docker run --rm -ti -v "$PWD/cache:/cache" 'gcr.io/kaniko-project/warmer' --image='python:3.10'
+docker run --rm -ti -v "$PWD:/workspace" 'gcr.io/kaniko-project/executor:debug' --reproducible \
+  --no-push --tar-path '/workspace/image.tar' --destination 'image:1.0' \
+  --cache --cache-dir '/workspace/cache' --cache-repo 'oci://cache'
 ```
 
   </details>
 
+  <details style="padding-left: 1rem">
+    <summary>Test the Dockerfile for an Ansible execution environment the way a GitLab pipeline would need to execute it</summary>
+
+```sh
+docker run --rm -ti -v "$PWD:/workspace" 'gcr.io/kaniko-project/executor:debug' /kaniko/executor --no-push
+docker run --rm -ti -v "$PWD:/workspace" --entrypoint '' 'gcr.io/kaniko-project/executor:v1.23.2-debug' \
+  /kaniko/executor --context '/workspace/someDir' --dockerfile '/workspace/someDir/someDockerfile' --no-push
+```
+
+  </details>
+
+</details>
+
 ## Usage in GitLab pipelines
 
 ```yaml
@@ -93,7 +132,8 @@ build-container:
 
 ## Further readings
 
-- [Main repository]
+- [Codebase]
+- [Cache and Kaniko]
 
 ### Sources
 
@@ -111,10 +151,11 @@ build-container:
 <!-- Knowledge base -->
 <!-- Files -->
 <!-- Upstream -->
+[codebase]: https://github.com/GoogleContainerTools/kaniko
 [introducing kaniko: build container images in kubernetes and google container builder without privileges]: https://cloud.google.com/blog/products/containers-kubernetes/introducing-kaniko-build-container-images-in-kubernetes-and-google-container-builder-even-without-root-access
-[main repository]: https://github.com/GoogleContainerTools/kaniko
 
 <!-- Others -->
 [an introduction to kaniko]: https://www.baeldung.com/ops/kaniko
-[use kaniko to build docker images]: https://docs.gitlab.com/ee/ci/docker/using_kaniko.html
+[cache and kaniko]: https://medium.com/swlh/cache-and-kaniko-2cfb766925af
 [kaniko: kubernetes native daemonless docker image builder]: https://8grams.medium.com/kaniko-kubernetes-native-daemonless-docker-image-builder-8eec88979f9e
+[use kaniko to build docker images]: https://docs.gitlab.com/ee/ci/docker/using_kaniko.html