docs: add customization guide

This adds a section on customizing Talos.

Signed-off-by: Andrew Rynhard <andrew@andrewrynhard.com>

Dockerfile

@@ -249,6 +249,9 @@ FROM rootfs-base AS rootfs-squashfs
 COPY --from=rootfs / /rootfs
 RUN mksquashfs /rootfs /rootfs.sqsh -all-root -noappend -comp xz -Xdict-size 100% -no-progress
 
+FROM scratch AS squashfs
+COPY --from=rootfs-squashfs /rootfs.sqsh /
+
 FROM scratch AS rootfs
 COPY --from=rootfs-base /rootfs /
 
@@ -256,7 +259,7 @@ COPY --from=rootfs-base /rootfs /
 
 FROM build AS initramfs-archive
 WORKDIR /initramfs
-COPY --from=rootfs-squashfs /rootfs.sqsh .
+COPY --from=squashfs /rootfs.sqsh .
 COPY --from=init /init .
 RUN set -o pipefail && find . 2>/dev/null | cpio -H newc -o | xz -v -C crc32 -0 -e -T 0 -z >/initramfs.xz
 
@@ -274,14 +277,17 @@ ENTRYPOINT ["/sbin/init"]
 # various environments.
 
 FROM alpine:3.8 AS installer
-RUN apk --update add \
+RUN apk add --no-cache --update \
     bash \
     ca-certificates \
     cdrkit \
+    cpio \
     qemu-img \
+    squashfs-tools \
     syslinux \
     util-linux \
-    xfsprogs
+    xfsprogs \
+    xz
 COPY hack/installer/entrypoint.sh /bin/entrypoint.sh
 COPY hack/installer/template.ovf /template.ovf
 COPY --from=kernel /vmlinuz /usr/install/vmlinuz
@@ -292,6 +298,21 @@ ARG TAG
 ENV VERSION ${TAG}
 LABEL "alpha.talos.io/version"="${VERSION}"
 ENTRYPOINT ["entrypoint.sh"]
+ONBUILD WORKDIR /initramfs
+ONBUILD ARG RM
+ONBUILD RUN xz -d /usr/install/initramfs.xz \
+    && cpio -idvm < /usr/install/initramfs \
+    && unsquashfs -f -d /rootfs rootfs.sqsh \
+    && for f in ${RM}; do rm -rfv /rootfs$f; done \
+    && rm /usr/install/initramfs \
+    && rm rootfs.sqsh
+ONBUILD COPY --from=customization / /rootfs
+ONBUILD RUN find /rootfs \
+    && mksquashfs /rootfs rootfs.sqsh -all-root -noappend -comp xz -Xdict-size 100% -no-progress \
+    && set -o pipefail && find . 2>/dev/null | cpio -H newc -o | xz -v -C crc32 -0 -e -T 0 -z >/usr/install/initramfs.xz \
+    && rm -rf /rootfs \
+    && rm -rf /initramfs
+ONBUILD WORKDIR /
 
 # The test target performs tests on the source code.
 

Makefile

@@ -135,6 +135,14 @@ initramfs: buildkitd
 		--opt target=$@ \
 		$(COMMON_ARGS)
 
+.PHONY: squashfs
+squashfs: buildkitd osd trustd ntpd networkd apid
+	@$(BINDIR)/buildctl --addr $(BUILDKIT_HOST) \
+		build \
+		--output type=local,dest=build \
+		--opt target=$@ \
+		$(COMMON_ARGS)
+
 .PHONY: rootfs
 rootfs: buildkitd osd trustd ntpd networkd apid
 	@$(BINDIR)/buildctl --addr $(BUILDKIT_HOST) \

docs/website/assets/css/main.css

@@ -47,6 +47,13 @@ pre {
   overflow-x: auto;
 }
 
+code {
+  background: #f4f5f6;
+  border-style: none;
+  border-width: 0.5px;
+  border-radius: 5px;
+}
+
 code[class*='language-'],
 pre[class*='language-'] {
   @apply font-mono;

docs/website/content/v0.3.en.json

@@ -93,6 +93,16 @@
       }
     ]
   },
+  {
+    "title": "Customization",
+    "path": "v0.3/en/customization",
+    "items": [
+      {
+        "title": "Kernel",
+        "path": "v0.3/en/customization/kernel"
+      }
+    ]
+  },
   {
     "title": "Components",
     "path": "v0.3/en/components",

docs/website/content/v0.3/en/customization/index.md

@@ -0,0 +1,60 @@
+---
+title: 'Customization'
+---
+
+The installer image contains [`ONBUILD`](https://docs.docker.com/engine/reference/builder/#onbuild) instructions that handle the following:
+
+- the decompression, and unpacking of the `initramfs.xz`
+- the unsquashing of the rootfs
+- the copying of new rootfs files
+- the squashing of the new rootfs
+- and the packing, and compression of the new `initramfs.xz`
+
+When used as a base image, the installer will perform the above steps automatically with the requirement that a `customization` stage be defined in the `Dockerfile`.
+
+For example, say we have an image that contains the contents of a library we wish to add to the Talos rootfs.
+We need to define a stage with the name `customization`:
+
+```docker
+FROM scratch AS customization
+COPY --from=<name|index> <src> <dest>
+```
+
+Using a multi-stage `Dockerfile` we can define the `customization` stage and build `FROM` the installer image:
+
+```docker
+FROM scratch AS customization
+COPY --from=<name|index> <src> <dest>
+
+FROM docker.io/autonomy/installer:latest
+```
+
+When building the image, the `customization` stage will automatically be copied into the rootfs.
+The `customization` stage is not limited to a single `COPY` instruction.
+In fact, you can do whatever you would like in this stage, but keep in mind that everything in `/` will be copied into the rootfs.
+
+> Note: `<dest>` is the path relative to the rootfs that you wish to place the contents of `<src>`.
+
+To build the image, run:
+
+```bash
+docker build --squash -t <organization>/installer:latest .
+```
+
+In the case that you need to perform some cleanup _before_ adding additional files to the rootfs, you can specify the `RM` [build-time variable](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg):
+
+```bash
+docker build --squash --build-arg RM="[<path> ...]" -t <organization>/installer:latest .
+```
+
+This will perform a `rm -rf` on the specified paths relative to the rootfs.
+
+> Note: `RM` must be a whitespace delimited list.
+
+The resulting image can be used to:
+
+- generate an image for any of the supported providers
+- perform bare-metall installs
+- perform upgrades
+
+We will step through common customizations in the remainder of this section.

docs/website/content/v0.3/en/customization/kernel.md

@@ -0,0 +1,19 @@
+---
+title: 'Kernel'
+---
+
+## Customizing the Kernel
+
+```docker
+FROM scratch AS customization
+COPY --from=<custom kernel image> /lib/modules /lib/modules
+
+FROM docker.io/andrewrynhard/installer:latest
+COPY --from=<custom kernel image> /boot/vmlinuz /usr/install/vmlinuz
+```
+
+```bash
+docker build --squash --build-arg RM="/lib/modules" -t talos-installer .
+```
+
+Now that we have a custom installer we can build Talos for the specific platform we wish to deploy to.