diff --git a/docs/assets/images/illustrations/arch.jpg b/docs/assets/images/illustrations/arch.jpg new file mode 100644 index 0000000..4508eab Binary files /dev/null and b/docs/assets/images/illustrations/arch.jpg differ diff --git a/docs/concepts/oci_image_layout.md b/docs/concepts/oci_image_layout.md index 2f5f4d3..51054bc 100644 --- a/docs/concepts/oci_image_layout.md +++ b/docs/concepts/oci_image_layout.md @@ -1 +1,10 @@ -# OCI Image Layout \ No newline at end of file +# OCI Image Layout + +Stacker is a standalone OCI-native container image builder which produces +images in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) +format. + + OCI Image Layout Specification + + The OCI Image Layout is the directory structure for OCI content-addressable blobs and location-addressable references (refs). + This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync). diff --git a/docs/concepts/stacker_architecture.md b/docs/concepts/stacker_architecture.md index e8f355e..d2fb83f 100644 --- a/docs/concepts/stacker_architecture.md +++ b/docs/concepts/stacker_architecture.md @@ -1 +1,6 @@ -# Stacker Architecture \ No newline at end of file +# Stacker Architecture + +The following diagram illustrates the relationship between the various +directives and the internal state maintained during the image build process. + +![architecture](../assets/images/illustrations/arch.jpg) diff --git a/docs/developer_guide/building_stacker.md b/docs/developer_guide/building_stacker.md index e6206fe..9c82410 100644 --- a/docs/developer_guide/building_stacker.md +++ b/docs/developer_guide/building_stacker.md @@ -1,4 +1,4 @@ -## Building and Installing Stacker +# Building and Installing Stacker ### Go Dependency diff --git a/docs/developer_guide/lxc_usage.md b/docs/developer_guide/lxc_usage.md index e69de29..32e89a3 100644 --- a/docs/developer_guide/lxc_usage.md +++ b/docs/developer_guide/lxc_usage.md @@ -0,0 +1,4 @@ +# LXC + +stacker uses [lxc](https://github.com/lxc/lxc) as its underlying container +management library in order to achieve hermetically-sealed image builds. diff --git a/docs/developer_guide/overlayfs_usage.md b/docs/developer_guide/overlayfs_usage.md index e69de29..01461d6 100644 --- a/docs/developer_guide/overlayfs_usage.md +++ b/docs/developer_guide/overlayfs_usage.md @@ -0,0 +1,7 @@ +# OverlayFS Support + +stacker relies on [overlayFS](https://docs.kernel.org/filesystems/overlayfs.html) in the Linux kernel, which should be available in kernel versions 4.x and above. + +You can also check by running the command `lsmod | grep overlay` if compiled +and available as a module or if compiled inline by enabling `CONFIG_OVERLAY_FS` +in the Linux kernel build configuration. diff --git a/docs/get_started/get_stacker.md b/docs/get_started/get_stacker.md index 816ae76..d4d2d16 100644 --- a/docs/get_started/get_stacker.md +++ b/docs/get_started/get_stacker.md @@ -1,3 +1,5 @@ +# Installing Stacker + Stacker is a single static binary tool with most of the dependencies built into the binary. Stacker, however, depends on specific kernel capabilities and system tools to provide various features. @@ -67,4 +69,4 @@ This binary needs to be installed and present in `$PATH`. ```bash title="Install mksquashfs on ubuntu" sudo apt-get install -y squashfs-tools -``` \ No newline at end of file +``` diff --git a/docs/get_started/hello_stacker_image.md b/docs/get_started/hello_stacker_image.md index 5985a55..4e0e3b1 100644 --- a/docs/get_started/hello_stacker_image.md +++ b/docs/get_started/hello_stacker_image.md @@ -1,3 +1,5 @@ +# A "Hello Stacker" Image + Stacker builds OCI images using the YAML definition in a file referred to as the stacker file. So let's create a stacker file definition that packages a simple "Hello Stacker!" script into an OCI container image. diff --git a/docs/reference/stacker_file.md b/docs/reference/stacker_file.md index 965555f..9901f5d 100644 --- a/docs/reference/stacker_file.md +++ b/docs/reference/stacker_file.md @@ -1,4 +1,4 @@ -## The `stacker.yaml` file +# The `stacker.yaml` file When doing a `stacker build`, the behavior of stacker is specified by the yaml directives below. In addition to these, stacker allows variable substitions of diff --git a/docs/user_guide/annotation_support.md b/docs/user_guide/annotation_support.md index e69de29..038a5f2 100644 --- a/docs/user_guide/annotation_support.md +++ b/docs/user_guide/annotation_support.md @@ -0,0 +1,14 @@ +# Additing Annotations + +In the stacker yaml file, `annotations` is a user-specified key value map that will be included in the +final OCI image. Note that these annotations are included in the image manifest +itself and not as part of the index.json. + + annotations: + a.b.c.key: abc_val + p.q.r.key: pqr_val + +While `config` section supports a similar `labels`, it is more pertitent to the +image runtime. On the other hand, `annotations` is intended to be +image-specific metadata aligned with the +[annotations in the image spec](https://github.com/opencontainers/image-spec/blob/main/annotations.md). diff --git a/docs/user_guide/build_cache.md b/docs/user_guide/build_cache.md index e69de29..22945bd 100644 --- a/docs/user_guide/build_cache.md +++ b/docs/user_guide/build_cache.md @@ -0,0 +1,6 @@ +# Build Cache + +A build cache with snapshot support is maintained throughout the build process +in order to store intermediate build artifacts and avoid unnecessary rebuilds. +Furthermore, you can also avoid rebuilding layers across many stacker build +invocations by preserving this build cache. diff --git a/docs/user_guide/build_code.md b/docs/user_guide/build_code.md index 6c49e5b..5ca753d 100644 --- a/docs/user_guide/build_code.md +++ b/docs/user_guide/build_code.md @@ -1,3 +1,5 @@ +# Producing Images From Compiled/Built Code + A common first step before building a container image is to build your code in a consistent environment. Stacker provides a hermetically sealed environment in a build-only container to produce the binaries and other artifacts required for diff --git a/docs/user_guide/build_environment.md b/docs/user_guide/build_environment.md index 0a651be..7969f9e 100644 --- a/docs/user_guide/build_environment.md +++ b/docs/user_guide/build_environment.md @@ -1,3 +1,5 @@ +# Hermetically-sealed Build Environment + Stacker builds container images in a canonically defined environment, allowing stacker to guarantee repeatable builds by reproducing the same environment for all the builds for a given version of the stacker file. @@ -111,7 +113,7 @@ The `docker://zothub.io/tools/busybox:stable` container defines the above file system, which has all the necessary utilities like /bin/cat and a basic system configuration required to operate most of the Linux utilities. -## Newtworking Setup +## Networking Setup Stacker builds the container images in the host network namespace. It bind mounts the host's /etc/resolv.conf into the build container's root file system diff --git a/docs/user_guide/debugging.md b/docs/user_guide/debugging.md index fece5f3..8cb4521 100644 --- a/docs/user_guide/debugging.md +++ b/docs/user_guide/debugging.md @@ -1,3 +1,5 @@ +# Debugging + The first step to trying to find a bug in stacker is to run it with --debug. This will give you a stack trace from where (at least in stacker's code) the error originated via [github.com/pkg/errors](https://github.com/pkg/errors). diff --git a/docs/user_guide/dependency_builds.md b/docs/user_guide/dependency_builds.md index e69de29..9027d93 100644 --- a/docs/user_guide/dependency_builds.md +++ b/docs/user_guide/dependency_builds.md @@ -0,0 +1,16 @@ +# Chained Builds With Dependency Tracking + +You can split image build directives over multiple files and chain them. + +If the `prerequisites` list is present under the `config` key, stacker will +make sure to build all the layers in the stacker.yaml files found at the paths +contained in the list. This way stacker supports building multiple +stacker.yaml files in the correct order. + +In this particular case the parent folder of the current folder, let's call it +`parent`, has 3 subfolders `folder1`, `folder2` and `folder3`, each containing a +`stacker.yaml` file. The example `config` above is in `parent/folder1/stacker.yaml`. + +When `stacker build -f parent/folder1/stacker.yaml` is invoked, stacker would search +for the other two stacker.yaml files and build them first, before building +the stacker.yaml specified in the command line. diff --git a/docs/user_guide/grab_image_content.md b/docs/user_guide/grab_image_content.md index e69de29..bb5402e 100644 --- a/docs/user_guide/grab_image_content.md +++ b/docs/user_guide/grab_image_content.md @@ -0,0 +1,17 @@ +# Grab Content From Built Images + +After an image is built, you can grab a file from the built image. This is +useful to inspect the file or its contents to ensure the build process has +completed properly. + +``` +NAME: + stacker grab - grabs a file from the layer's filesystem + +USAGE: + stacker grab : + + is the tag in a built stacker image to extract the file from. + + is the path to extract (relative to /) in the image's rootfs. +``` diff --git a/docs/user_guide/image_chroot.md b/docs/user_guide/image_chroot.md index e69de29..357ca38 100644 --- a/docs/user_guide/image_chroot.md +++ b/docs/user_guide/image_chroot.md @@ -0,0 +1,21 @@ +# Chrooting Into Built Images + +After an image is built, you can run a command in a chroot in that built image. + +``` +NAME: + stacker chroot - run a command in a chroot + +USAGE: + stacker chroot [command options] [tag] [cmd] + + is the built tag in the stackerfile to chroot to, or the first tag if +none is specified. + + is the command to run, or /bin/sh if none is specified. To specify cmd, +you must specify a tag. + +OPTIONS: + --stacker-file value, -f value the input stackerfile (default: "stacker.yaml") + --substitute value variable substitution in stackerfiles, FOO=bar format +``` diff --git a/docs/user_guide/inspect_images.md b/docs/user_guide/inspect_images.md index e69de29..6548c36 100644 --- a/docs/user_guide/inspect_images.md +++ b/docs/user_guide/inspect_images.md @@ -0,0 +1,15 @@ +# Inspecting Built Images + +All built images are stored in OCI Image Layout, and you can inspect the JSON +representation of an OCI image after it is built. + +``` +NAME: + stacker inspect - print the json representation of an OCI image + +USAGE: + stacker inspect [tag] + + is the tag in the stackerfile to inspect. If none is supplied, inspect +prints the information on all tags. +``` diff --git a/docs/user_guide/publish_images.md b/docs/user_guide/publish_images.md index e69de29..6f4273e 100644 --- a/docs/user_guide/publish_images.md +++ b/docs/user_guide/publish_images.md @@ -0,0 +1,27 @@ +# Publishing images + +After building the image, you can publish the image to an [OCI Distribution +Spec](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) +conformant registry. + +``` +NAME: + stacker publish - publishes OCI images previously built from one or more stacker yaml files + +USAGE: + stacker publish [command options] [arguments...] + +OPTIONS: + --stacker-file value, -f value the input stackerfile (default: "stacker.yaml") + --stacker-file-pattern value, -p value regex pattern to use when searching for stackerfile paths (default: "\\/stacker.yaml$") + --search-dir value, -d value directory under which to search for stackerfiles to publish + --url value url where to publish the OCI images + --username value username for the registry where the OCI images are published + --password value password for the registry where the OCI images are published + --skip-tls skip tls verify on upstream registry + --tag value tag to be used when publishing + --substitute value variable substitution in stackerfiles, FOO=bar format + --show-only show the images to be published without actually publishing them + --force force publishing the images present in the OCI layout even if they should be rebuilt + --layer-type value set the output layer type (supported values: tar, squashfs); can be supplied multiple times (default: "tar") +``` diff --git a/docs/user_guide/scratch_image.md b/docs/user_guide/scratch_image.md index bda1a64..84bbe2a 100644 --- a/docs/user_guide/scratch_image.md +++ b/docs/user_guide/scratch_image.md @@ -1,4 +1,4 @@ -# Building container image from scratch +# Bootsrapping From Other Images There are a couple of cases where it may be useful to build a layer from scratch. For example to derive a new base install of an OS or to build a @@ -68,4 +68,4 @@ Another way to accomplish something similar is to use a You can use the first layer as a build env, and copy your binary to a bind-mounted folder. Use overlay_dirs with that same folder to have the binary -in the distroless layer. \ No newline at end of file +in the distroless layer. diff --git a/docs/user_guide/template_substitution.md b/docs/user_guide/template_substitution.md index e69de29..069875d 100644 --- a/docs/user_guide/template_substitution.md +++ b/docs/user_guide/template_substitution.md @@ -0,0 +1,17 @@ +# Template Variable Substitution + +When doing a `stacker build`, the behavior of stacker is specified by the yaml +directives below. In addition to these, stacker allows variable substitions of +several forms. For example, a line like: + + $ONE ${{TWO}} ${{THREE:3}} + +When run with `stacker build --substitute ONE=1 --substitute TWO=2` is +processed in stacker as: + + 1 2 3 + +That is, variables of the form `$FOO` or `${FOO}` are supported, and variables +with `${FOO:default}` a default value will evaluate to their default if not +specified on the command line. It is an error to specify a `${FOO}` style +without a default; to make the default an empty string, use `${FOO:}`. diff --git a/docs/whats-new.md b/docs/whats-new.md new file mode 100644 index 0000000..af95c85 --- /dev/null +++ b/docs/whats-new.md @@ -0,0 +1 @@ +# What's New diff --git a/material/overrides/home.html b/material/overrides/home.html index fb8e3c1..d8274c1 100644 --- a/material/overrides/home.html +++ b/material/overrides/home.html @@ -17,7 +17,7 @@

Stacker Build

User Guide -

Pair this with zot, an OCI-native Image Registry

+

Pair stacker with zot, an OCI-native Image Registry

diff --git a/mkdocs.yml b/mkdocs.yml index 4d3d8e7..54fee08 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,6 +56,7 @@ extra: default: latest plugins: - search + - git-revision-date-localized - minify: minify_html: true markdown_extensions: @@ -90,9 +91,13 @@ markdown_extensions: - pymdownx.tasklist: custom_checkbox: true - pymdownx.tilde + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg nav: - Home: index.md + - What's New: whats-new.md - Get Started: - Get Stacker: get_started/get_stacker.md - Hello Stacker Image: get_started/hello_stacker_image.md @@ -101,9 +106,9 @@ nav: - Stacker Architecture: concepts/stacker_architecture.md - User Guide: - Build Environment: user_guide/build_environment.md - - Build Code: user_guide/build_code.md - - Build Container Image: user_guide/build_container_image.md - - Scratch Image: user_guide/scratch_image.md + - Code Builds: user_guide/build_code.md + - Bootstrapped Container Image: user_guide/scratch_image.md + - Multi-Stage Build: user_guide/build_container_image.md - Template Substitution: user_guide/template_substitution.md - Annotation Support: user_guide/annotation_support.md - Dependency Builds: user_guide/dependency_builds.md diff --git a/requirements.txt b/requirements.txt index 3583240..9c11ead 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,3 +3,4 @@ mkdocs-material==8.5.8 mkdocs-material-extensions==1.1 mkdocs-minify-plugin==0.6.1 mike==1.1.2 +mkdocs-git-revision-date-localized-plugin==1.1.0