From d006e0b6e009087b00b27e5638778e68d9051e34 Mon Sep 17 00:00:00 2001 From: Gerald Pinder Date: Sun, 25 Feb 2024 05:41:38 -0500 Subject: [PATCH] docs: Add module documentation for 'containerfile' and 'files' (#82) Co-authored-by: xynydev <60004820+xynydev@users.noreply.github.com> --- modules.json | 4 ++ templates/modules/containerfile/README.md | 76 ++++++++++++++++++++++ templates/modules/containerfile/module.yml | 10 +++ templates/modules/files/README.md | 15 +++++ templates/modules/files/module.yml | 9 +++ 5 files changed, 114 insertions(+) create mode 100644 modules.json create mode 100644 templates/modules/containerfile/README.md create mode 100644 templates/modules/containerfile/module.yml create mode 100644 templates/modules/files/README.md create mode 100644 templates/modules/files/module.yml diff --git a/modules.json b/modules.json new file mode 100644 index 0000000..1fea9cc --- /dev/null +++ b/modules.json @@ -0,0 +1,4 @@ +[ + "https://raw.githubusercontent.com/blue-build/cli/main/templates/modules/containerfile/module.yml", + "https://raw.githubusercontent.com/blue-build/cli/main/templates/modules/files/module.yml" +] diff --git a/templates/modules/containerfile/README.md b/templates/modules/containerfile/README.md new file mode 100644 index 0000000..afee5ae --- /dev/null +++ b/templates/modules/containerfile/README.md @@ -0,0 +1,76 @@ +# `containerfile` + +:::caution +Only compiler-based builds can use this module as it is built-in to the BlueBuild CLI tool. +::: + +The `containerfile` module is a tool for adding custom [`Containerfile`](https://github.com/containers/common/blob/main/docs/Containerfile.5.md) instructions for custom image builds. This is useful when you wish to use some feature directly available in a `Containerfile`, but not in a bash module, such as copying from other OCI images with `COPY --from`. + +Since standard compiler-based BlueBuild image builds generate a `Containerfile` from your recipe, there is no need to manage it yourself. However, we know that we also have technical users that would like to have the ability to customize their `Containerfile`. This is where the `containerfile` module comes into play. + +## Usage + +### `snippets:` + +The `snippets` property is the easiest to use when you just need to insert a few custom lines to the `Containerfile`. Each entry under the `snippets` property will be directly inserted into your final `Containerfile` for your build. + +```yaml +modules: + - type: containerfile + snippets: + - COPY --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/yq +``` + +This makes it really easy to copy a file or program from another image. + +:::note +**NOTE:** Each entry of a snippet will be its own layer in the final `Containerfile`. +::: + +### `containerfiles:` + +The `containerfiles` property allows you to tell the compiler which directory contains a `Containerfile` in `./config/containerfiles/`. + +Below is an example of how a `containerfile` module would be used with the `containerfiles` property: + +```yaml +modules: + - type: containerfile + containerfiles: + - example + - subroutine +``` + +In the example above, the compiler would look for these files: + +- `./config/containerfiles/example/Containerfile` +- `./config/containerfiles/subroutine/Containerfile` + +You could then store files related to say the `subroutine` `Containerfile` in `./config/containerfiles/subroutine/` to keep it organized and portable for other recipes to use. + +:::note +**NOTE:** The instructions you add in your `Containerfile`'s each become a layer unlike other modules which are typically run as a single `RUN` command, thus creating only one layer. +::: + +### Order of operations + +The order of operations is important in a `Containerfile`. There's a very simple set of rules for the order in this module: + +- For each defined `containerfile` module: + - First all `containerfiles:` are added to the main `Containerfile` in the order they are defined + - Then all `snippets` are added to the main `Containerfile` in the order they are defined + +If you wanted to have some `snippets` run before any `containerfiles` have, you will want to put them in their own module definition before the entry for `containerfiles`. For example: + +```yaml +modules: + - type: containerfile + snippets: + - COPY --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/yq + - type: containerfile + containerfiles: + - example + - subroutine +``` + +In the example above, the `COPY` from the `snippets` will always come before the `containerfiles` "example" and "subroutine". diff --git a/templates/modules/containerfile/module.yml b/templates/modules/containerfile/module.yml new file mode 100644 index 0000000..74a0596 --- /dev/null +++ b/templates/modules/containerfile/module.yml @@ -0,0 +1,10 @@ +name: containerfile +shortdesc: The containerfile module enables the addition of custom Containerfile instructions into the build process. +readme: https://raw.githubusercontent.com/blue-build/cli/main/templates/modules/containerfile/README.md +example: | + type: containerfile + snippets: + - COPY ./config/example-dir/example-file.txt /usr/etc/example/ + containerfiles: + - example + - subroutine \ No newline at end of file diff --git a/templates/modules/files/README.md b/templates/modules/files/README.md new file mode 100644 index 0000000..56525b6 --- /dev/null +++ b/templates/modules/files/README.md @@ -0,0 +1,15 @@ +# `files` + +The `files` module simplifies the process of copying files to the image during the build time. These files are sourced from the `config/files` directory, which is located at `/tmp/config/files` inside the image. + +:::note +If you want to place any files in `/etc/`, you should place them in `/usr/etc/` instead, which will be used to generate `/etc/` on a booted system. That is the proper directory for "system" configuration templates on atomic Fedora distros, whereas `/etc/` is meant for manual overrides and editing by the machine's admin AFTER installation! See issue https://github.com/blue-build/legacy-template/issues/28. +::: + +## Implementation differences between the legacy template and compiler-based builds + +When using a compiler-based build (which is the recommended option for all users, so if you don't know what you're using you're probably using that), each instruction under `files:` creates its on layer in the final image using the `Containerfile` `COPY`-command. This module is entirely part of the recipe compiler. + +When using a legacy template, all modules are combined into one layer in the final image. With a repo based on the legacy template, the bash version is used. + +The API for both of these options remains exactly the same. \ No newline at end of file diff --git a/templates/modules/files/module.yml b/templates/modules/files/module.yml new file mode 100644 index 0000000..9191f04 --- /dev/null +++ b/templates/modules/files/module.yml @@ -0,0 +1,9 @@ +name: files +shortdesc: The files module simplifies the process of copying files to the image during build time. +readme: https://raw.githubusercontent.com/blue-build/cli/main/templates/modules/files/README.md +example: | + type: files + files: + - usr: /usr + # usr: file/folder inside config/files/ to copy (config/files/usr/ in the repository) + # /usr: destination on the final system