Project: LinuxKit (Provisioning / Automation & Configuration)
File: alpine-base-update.md

This document describes the steps to update the `linuxkit/alpine` image. This image is at the base of all other linuxkit images. It is built out of the directory `tools/alpine/`. While you do not need to update every downstream image immediately when you update this image, you do need to be aware that changes to this image will affect the downstream images when it is next adopted. Those downstream images should be updated as soon as possible after updating `linuxkit/alpine`. When you make a linuxkit release, you must update all of the downstream images. See for the release process. Updating `linuxkit/alpine` can be done by any maintainer. Maintainers need to have access to build machines for all architectures support by LinuxKit. At a high-level, we are going to do the following: Preparatory steps Create a new branch Make our desired changes to `tools/alpine` and commit them Build and push out our alpine changes, and commit the `versions` files Update all affected downstream changes and commit them: `tools/`, `test/pkg`, `pkg`, `test/`, `examples/` Push out all affected downstream changes: `tools/`, `test/pkg`, `pkg`, `test/`, `examples/` For each of the affected downstream changes, we could update and then push, then move to the next. However, since the push out can be slow and require retries, we try to make all of the changes first, and then push them out. As a starting point you have to be on the update to date master branch and be in the root directory of your local git clone. You should also have the same setup on all build machines used. To make the steps below cut-and-pastable, define the following environment variables: ```sh LK_ROOT=$(pwd) LK_REMOTE=origin # or whatever your personal remote is LK_BRANCH=alpine-update # or whatever the name of the branch on which you are working is ``` Note that if you are cutting a release, the `LKBRANCH` may have a release-type name, e.g. `relv0.4`. Make sure that you have the latest version of the `linuxkit` utility in the path. Alternatively, you may wish to compile the latest version from master. On one of the build machines (preferably the `x86_64` machine), create the branch: ```sh git checkout -b $LK_BRANCH ``` You must perform the arch-specific image builds, pushes and updates on each architecture first - these can be done in parallel, if you choose. When done, you then copy the updated `versions.<arch>` to one place, commit them, and push the manifest. Make any changes in `tools/alpine` that you desire, then commit them. In the below, change the commit message to something meaningful to the change you are making. ```sh cd tools/alpine git commit -s -a -m "Update linuxkit/alpine" git push origin $LK_BRANCH ``` On each supported platform, build and update `linuxkit/alpine`, which will update the `versions.<arch>` file.: ```sh git fetch git checkout $LK_BRANCH cd $LK_ROOT/tools/alpine make push ``` Repeat on each platform. When all of the platforms are done, copy the changed

from each platform to one place, commit and push. In the below, replace `linuxkit-arch` with each build machine's name: ```sh scp linuxkit-s390x:$LKROOT/tools/alpine/versions.s390x $LKROOT/tools/alpine/versions.s390x scp linuxkit-aarch64:$LKROOT/tools/alpine/versions.aarch64 $LKROOT/tools/alpine/versions.aarch64 scp linuxkit-x8664:$LKROOT/tools/alpine/versions.x8664 $LKROOT/tools/alpine/versions.x86_64 git commit -a -s -m "tools/alpine: Update to latest" git push $LKREMOTE $LKBRANCH ``` Push out the multi-arch index: ```sh make push-manifest ``` Stash the tag of the alpine base image in an environment variable: ```sh LK_ALPINE=$(make show-tag) ``` This section describes all of the steps. Below follows a straight copyable list of steps to take, following which is an explanation of each one. ```sh cd $LK_ROOT/tools $LKROOT/scripts/update-component-sha.sh --image $LKALPINE git checkout grub-dev/Dockerfile git checkout mkimage-rpi3/Dockerfile git commit -a -s -m "tools: Update to the latest linuxkit/alpine" cd $LK_ROOT for img in $(cd tools; make show-tag); do $LK_ROOT/scripts/update-component-sha.sh --image $img done git commit -a -s -m "Update use of tools to latest" cd $LK_ROOT/test/pkg $LKROOT/scripts/update-component-sha.sh --image $LKALPINE git commit -a -s -m "tests: Update packages to the latest linuxkit/alpine" cd $LK_ROOT for img in $(cd test/pkg; make show-tag); do $LK_ROOT/scripts/update-component-sha.sh --image $img done git commit -a -s -m "Update use of test packages to latest" cd $LK_ROOT/test/cases $LKROOT/scripts/update-component-sha.sh --image $LKALPINE git commit -a -s -m "tests: Update tests cases to the latest linuxkit/alpine" cd $LK_ROOT/pkg $LKROOT/scripts/update-component-sha.sh --image $LKALPINE git commit -a -s -m "pkgs: Update packages to the latest linuxkit/alpine" cd $LK_ROOT make update-package-tags MSG="" [ -n "$LKRELEASE" ] && MSG="to $LKRELEASE" git commit -a -s -m "Update package tags $MSG" git push $LKREMOTE $LKBRANCH ``` On your primary build machine, update the other tools packages. Note, the `git checkout` reverts the changes made by `update-component-sha.sh` to files which are accidentally updated. Important is the `git checkout` of some sensitive packages that only can be built with specific older versions of upstream packages: `grub-dev` `mkimage-rpi3` Only update those if you know what you are doing with them. Then we update any dependencies of these tools. Next, we update the test packages to the updated alpine base. Next, we update the use of test packages to latest. Some tests also use `linuxkit/alpine`, so we update them as well. Next, we update the LinuxKit packages. This is really the core of the release. The other steps above are just there to ensure consistency across packages. Most of the packages are build from `linuxkit/alpine` and source code in the `linuxkit` repository, but some packages wrap external tools. When updating all packages, and especially during the time of a release, is a good opportunity to check if there have been updates. Specifically: `pkg/cadvisor`: Check for . `pkg/firmware` and `pkg/firmware-all`: Use latest commit from . `pkg/node_exporter`: Check for . Check for the latest `dind` tags. and update `examples/docker.yml`, `examples/docker-for-mac.yml`, `examples/cadvisor.yml`, and `test/cases/030security/000docker-bench/test.yml` if necessary. This is at your discretion. <ul>Note</ul>: All of the `make push` and `make forcepush` in this section use `linuxkit pkg push`, which will build for all architectures and push the images out. See . ```sh cd $LK_ROOT/tools make forcepush cd $LK_ROOT/test/pkg make push cd $LK_ROOT/pkg make push ```