From cdc128fd09d9c96eb106c3715693a44ee28a9d67 Mon Sep 17 00:00:00 2001 From: Ravi Chamarthy Date: Tue, 25 Oct 2022 22:26:10 +0000 Subject: [PATCH 1/2] home: add twitter and slack links at the top Signed-off-by: Ravi Chamarthy --- material/overrides/main.html | 9 ++++++++- mkdocs.yml | 2 ++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/material/overrides/main.html b/material/overrides/main.html index 01300ab..a87abc2 100644 --- a/material/overrides/main.html +++ b/material/overrides/main.html @@ -23,11 +23,18 @@ {% endblock %} {% block announce %} - For updates follow @stackerbuild on Twitter + @stackerbuild + + + + Slack + #stacker {% endblock %} {% block content %} diff --git a/mkdocs.yml b/mkdocs.yml index 7cee77f..27c0b81 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,6 +48,8 @@ extra: link: https://github.com/project-stacker/stacker.git - icon: fontawesome/brands/twitter link: https://twitter.com/stackerbuild + - icon: fontawesome/brands/slack + link: https://cloud-native.slack.com/archives/C048S8TMBGQ plugins: - search - minify: From 995f4c3955e40a1ea6eb02bb4895a9f413b5e418 Mon Sep 17 00:00:00 2001 From: Ravi Chamarthy Date: Tue, 25 Oct 2022 22:06:24 +0000 Subject: [PATCH 2/2] doc: add build env page * Build Environment page * remove squashfs referenes * update table of contents index Signed-off-by: Ravi Chamarthy --- docs/concepts/incremental_build.md | 1 - docs/concepts/multi_layer_build.md | 1 - docs/concepts/squashfs_layer.md | 1 - ...nvironment.md => build_container_image.md} | 0 docs/user_guide/build_environment.md | 208 ++++++++++++++++++ .../{image_build.md => container_build.md} | 0 ...hfs_images.md => template_substitution.md} | 0 docs/user_guide/templates.md | 0 material/overrides/home.html | 2 +- mkdocs.yml | 13 +- 10 files changed, 214 insertions(+), 12 deletions(-) delete mode 100644 docs/concepts/incremental_build.md delete mode 100644 docs/concepts/multi_layer_build.md delete mode 100644 docs/concepts/squashfs_layer.md rename docs/user_guide/{runtime_environment.md => build_container_image.md} (100%) create mode 100644 docs/user_guide/build_environment.md rename docs/user_guide/{image_build.md => container_build.md} (100%) rename docs/user_guide/{squashfs_images.md => template_substitution.md} (100%) delete mode 100644 docs/user_guide/templates.md diff --git a/docs/concepts/incremental_build.md b/docs/concepts/incremental_build.md deleted file mode 100644 index ea33df2..0000000 --- a/docs/concepts/incremental_build.md +++ /dev/null @@ -1 +0,0 @@ -# Incremental Build \ No newline at end of file diff --git a/docs/concepts/multi_layer_build.md b/docs/concepts/multi_layer_build.md deleted file mode 100644 index 316c095..0000000 --- a/docs/concepts/multi_layer_build.md +++ /dev/null @@ -1 +0,0 @@ -# Multi-Layer Build diff --git a/docs/concepts/squashfs_layer.md b/docs/concepts/squashfs_layer.md deleted file mode 100644 index b89a0e8..0000000 --- a/docs/concepts/squashfs_layer.md +++ /dev/null @@ -1 +0,0 @@ -# Squashfs Layer \ No newline at end of file diff --git a/docs/user_guide/runtime_environment.md b/docs/user_guide/build_container_image.md similarity index 100% rename from docs/user_guide/runtime_environment.md rename to docs/user_guide/build_container_image.md diff --git a/docs/user_guide/build_environment.md b/docs/user_guide/build_environment.md new file mode 100644 index 0000000..0a651be --- /dev/null +++ b/docs/user_guide/build_environment.md @@ -0,0 +1,208 @@ +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. + +## Runtime Environment + +Except for the term and proxy settings, none of the host environment +variables leak into the stacker build environment. The `run` section of your +build script can depend on these environment variables to perform the build. + +Let's examine the shell environment variables that stacker exposes to the build +script in the run section of your stacker file: + +```bash title="Stacker Build Environment" +cat > env_stacker.yaml << EOF +env-stacker: + from: + type: docker + url: docker://zothub.io/tools/busybox:stable + run: | + env + build_only: true +EOF + +stacker build -f env_stacker.yaml +preparing image env-stacker... +loading docker://zothub.io/tools/busybox:stable +Copying blob f5b7ce95afea skipped: already exists +Copying config 74c82eccc6 done +Writing manifest to image destination +Storing signatures +cache miss because layer definition was changed ++ env +HTTPS_PROXY=http://173.36.224.109:8080 +no_proxy=localhost,127.0.0.1,localaddress,.localdomain.com,.cisco.com +SHLVL=1 +NO_PROXY=localhost,127.0.0.1,localaddress,.localdomain.com,.cisco.com +container=lxc +https_proxy=http://173.36.224.109:8080 +TERM=screen-256color +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin +STACKER_LAYER_NAME=env-stacker +PWD=/ +``` + +Note that only `HTTPS_PROXY`, `https_proxy`, `NO_PROXY`, `no_proxy`, and `TERM` +are imported from the host, all other variables are standard shell variables. + +## Root File System (RFS) + +Stacker creates a root file system defined by the layer in the `from` section and +launches the build script in the `run` section using this file system. Stacker +expects a "sane" file system in the base container so that it can execute `sh` to +implement the `run` section. + +Let's examine the root file system that stacker exposes to the `run` script in +the following example: + +```bash title="Build RFS" +cat > rfs_stacker.yaml << EOF +rfs-stacker: + from: + type: docker + url: docker://zothub.io/tools/busybox:stable + run: | + ls -al / + find /etc + which cat + build_only: true +EOF + +stacker build -f rfs_stacker.yaml +preparing image rfs-stacker... +loading docker://zothub.io/tools/busybox:stable +Copying blob f5b7ce95afea skipped: already exists +Copying config 74c82eccc6 done +Writing manifest to image destination +Storing signatures ++ ls -al / +total 0 +drwxr-xr-x 1 root root 120 Oct 25 18:30 . +drwxr-xr-x 1 root root 120 Oct 25 18:30 .. +drwxr-xr-x 2 root root 8080 Oct 3 22:04 bin +drwxr-xr-x 4 root root 340 Oct 25 18:30 dev +drwxr-xr-x 1 root root 60 Oct 25 18:30 etc +drwxr-xr-x 2 nobody nobody 40 Oct 3 22:04 home +dr-xr-xr-x 2299 nobody nobody 0 Oct 25 18:30 proc +drwx------ 2 root root 40 Oct 3 22:04 root +drwxr-xr-x 2 root root 60 Oct 25 18:30 stacker +dr-xr-xr-x 13 nobody nobody 0 Sep 22 22:12 sys +drwxrwxrwt 2 root root 40 Oct 3 22:04 tmp +drwxr-xr-x 3 root root 60 Oct 3 22:04 usr +drwxr-xr-x 4 root root 80 Oct 3 22:04 var ++ find /etc +/etc +/etc/shadow +/etc/passwd +/etc/network +/etc/network/if-up.d +/etc/network/if-pre-up.d +/etc/network/if-post-down.d +/etc/network/if-down.d +/etc/localtime +/etc/group +/etc/resolv.conf ++ which cat +/bin/cat +``` + +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 + +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 +to allow for correct DNS resolution as defined by the host. Finally, stacker +re-exports the proxy settings to the environment to enable proxy-based access to +any artifacts required to build the container image. + +Let's examine the networking setup that stacker exposes to the `run` script in +the following example: + +```bash title="Networking setup" +cat > network_stacker.yaml << EOF +network-stacker: + from: + type: docker + url: docker://zothub.io/tools/busybox:stable + run: | + echo "HTTPS_PROXY=$HTTPS_PROXY" + cat /etc/resolv.conf + ip addr + build_only: true +EOF + +stacker build -f network_stacker.yaml +preparing image network-stacker... +loading docker://zothub.io/tools/busybox:stable +Copying blob f5b7ce95afea skipped: already exists +Copying config 74c82eccc6 done +Writing manifest to image destination +Storing signatures ++ echo HTTPS_PROXY=http://173.36.224.109:8080 +HTTPS_PROXY=http://173.36.224.109:8080 ++ cat /etc/resolv.conf +# This is /run/systemd/resolve/stub-resolv.conf managed by man:systemd-resolved(8). +# Do not edit. +# +# This file might be symlinked as /etc/resolv.conf. If you're looking at +# /etc/resolv.conf and seeing this text, you have followed the symlink. +# +# This is a dynamic resolv.conf file for connecting local clients to the +# internal DNS stub resolver of systemd-resolved. This file lists all +# configured search domains. +# +# Run "resolvectl status" to see details about the uplink DNS servers +# currently in use. +# +# Third party programs should typically not access this file directly, but only +# through the symlink at /etc/resolv.conf. To manage man:resolv.conf(5) in a +# different way, replace this symlink by a static file or a different symlink. +# +# See man:systemd-resolved.service(8) for details about the supported modes of +# operation for /etc/resolv.conf. + +nameserver 127.0.0.53 +options edns0 trust-ad +search cisco.com insieme.local ++ ip addr +1: lo: mtu 65536 qdisc noqueue qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever +2: enp97s0f0: mtu 1500 qdisc mq qlen 1000 + link/ether 3c:fd:fe:7f:27:a0 brd ff:ff:ff:ff:ff:ff +3: enp97s0f1: mtu 1500 qdisc mq qlen 1000 + link/ether 3c:fd:fe:7f:27:a1 brd ff:ff:ff:ff:ff:ff +4: enp97s0f2: mtu 1500 qdisc mq qlen 1000 + link/ether 3c:fd:fe:7f:27:a2 brd ff:ff:ff:ff:ff:ff +5: enp97s0f3: mtu 1500 qdisc mq qlen 1000 + link/ether 3c:fd:fe:7f:27:a3 brd ff:ff:ff:ff:ff:ff +6: enp1s0f0: mtu 1500 qdisc mq qlen 1000 + link/ether b4:96:91:a4:44:d4 brd ff:ff:ff:ff:ff:ff + inet 172.20.61.165/24 brd 172.20.61.255 scope global enp1s0f0 + valid_lft forever preferred_lft forever + inet6 fe80::b696:91ff:fea4:44d4/64 scope link + valid_lft forever preferred_lft forever +7: enp1s0f1: mtu 1500 qdisc mq qlen 1000 + link/ether b4:96:91:a4:44:d5 brd ff:ff:ff:ff:ff:ff +8: lxcbr0: mtu 1500 qdisc noqueue qlen 1000 + link/ether 00:16:3e:00:00:00 brd ff:ff:ff:ff:ff:ff + inet 10.0.3.1/24 brd 10.0.3.255 scope global lxcbr0 + valid_lft forever preferred_lft forever +9: docker0: mtu 1500 qdisc noqueue + link/ether 02:42:30:0d:77:ad brd ff:ff:ff:ff:ff:ff + inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0 + valid_lft forever preferred_lft forever +``` + +Since stacker is only used for building images, this is safe and intuitive for +users on corporate networks with complicated proxy and other setups. However, +it does mean that container packaging that expects to be able to modify things +in `/sys` will fail since /sys is bind mounted from the host's `/sys`. `sysfs` +cannot be mounted in a network namespace that a user doesn't own. diff --git a/docs/user_guide/image_build.md b/docs/user_guide/container_build.md similarity index 100% rename from docs/user_guide/image_build.md rename to docs/user_guide/container_build.md diff --git a/docs/user_guide/squashfs_images.md b/docs/user_guide/template_substitution.md similarity index 100% rename from docs/user_guide/squashfs_images.md rename to docs/user_guide/template_substitution.md diff --git a/docs/user_guide/templates.md b/docs/user_guide/templates.md deleted file mode 100644 index e69de29..0000000 diff --git a/material/overrides/home.html b/material/overrides/home.html index b28b440..694fef9 100644 --- a/material/overrides/home.html +++ b/material/overrides/home.html @@ -14,7 +14,7 @@

Stacker Build

Get Started - + User Guide diff --git a/mkdocs.yml b/mkdocs.yml index 27c0b81..c716b44 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -94,22 +94,19 @@ nav: - Concepts: - OCI Image Layout: concepts/oci_image_layout.md - Stacker Architecture: concepts/stacker_architecture.md - - Multi-Layer Build: concepts/multi_layer_build.md - - Incremental Build: concepts/incremental_build.md - - SquashFS Layer: concepts/squashfs_layer.md - User Guide: - - Runtime Environment: user_guide/runtime_environment.md - - Image Build: user_guide/image_build.md - - Templates: user_guide/templates.md - - Annotation Support: user_guide/annotation_support.md + - Build Environment: user_guide/build_environment.md + - Container Build: user_guide/container_build.md + - Build Container Image: user_guide/build_container_image.md - Scratch Image: user_guide/scratch_image.md + - Template Substitution: user_guide/template_substitution.md + - Annotation Support: user_guide/annotation_support.md - Dependency Builds: user_guide/dependency_builds.md - Publish Images: user_guide/publish_images.md - Build Cache: user_guide/build_cache.md - Inspect Images: user_guide/inspect_images.md - Image Chroot: user_guide/image_chroot.md - Grab Image Content: user_guide/grab_image_content.md - - SquashFS Images: user_guide/squashfs_images.md - Debugging: user_guide/debugging.md - Reference: - Stacker CLI: reference/stacker_cli.md