diff --git a/docs/kernels.md b/docs/kernels.md index ddcc59775..0403eff15 100644 --- a/docs/kernels.md +++ b/docs/kernels.md @@ -11,17 +11,16 @@ updated frequently to include bug and security fixes. For some kernels we do carry additional patches, which are mostly back-ported fixes from newer kernels. The full kernel source with patches can be found on [github](https://github.com/linuxkit/linux). Each kernel -image is tagged with the full kernel version plus the hash of the -files it was created from (git tree hash of the `./kernel` -directory). For convenience, the latest kernel of each stable series -is also available under a shorthand tag, e.g. `linuxkit/kernel:4.9.x` -for the latest `4.9` kernel. For selected kernels (mostly the LTS -kernels and latest stable kernels) we also compile/push kernels with -additional debugging enabled. The hub images for these kernels have -the `_dbg` suffix in the tag. For some kernels, we also provide -matching packages containing the `perf` utility for debugging and -performance tracing. The perf package is called `kernel-perf` and is -tagged the same way as the kernel packages. +image is tagged with the full kernel version (e.g., +`linuxkit/kernel:4.9.33`) and with the full kernel version plus the +hash of the files it was created from (git tree hash of the `./kernel` +directory). For selected kernels (mostly the LTS kernels and latest +stable kernels) we also compile/push kernels with additional debugging +enabled. The hub images for these kernels have the `_dbg` suffix in +the tag. For some kernels, we also provide matching packages +containing the `perf` utility for debugging and performance tracing. +The perf package is called `kernel-perf` and is tagged the same way as +the kernel packages. In addition to the official kernel images, LinuxKit offers the ability to build bootable Linux images with kernels from various @@ -51,7 +50,7 @@ RAM disk. There is a [example](../tests/kmod), but basically one can use a multi-stage build to compile the kernel modules: ``` -FROM linuxkit/kernel:4.9.x AS ksrc +FROM linuxkit/kernel:4.9.33 AS ksrc # Extract headers and compile module FROM linuxkit/kernel-compile:1b396c221af673757703258159ddc8539843b02b@sha256:6b32d205bfc6407568324337b707d195d027328dbfec554428ea93e7b0a8299b AS build COPY --from=ksrc /kernel-dev.tar / @@ -73,20 +72,24 @@ configuration. To build and test locally modified kernels, e.g., to try a different kernel config or new patches, the existing kernel build system in the [`../kernel`](../kernel/) can be re-used. For example, assuming the -current 4.9 kernel is 4.9.28, you can build a local kernel with: +current 4.9 kernel is 4.9.33, you can build a local kernel with: ``` -make build_4.9.28 HASH=foo +make build_4.9.x ``` This will create a local kernel image called -`linuxkit/kernel:4.9.28-foo` which you can use in your YAML file as: +`linuxkit/kernel:4.9.33--dirty` assuming you haven't committed you local changes. You can then use this in your YAML file as: ``` kernel: - image: "linuxkit/kernel:4.9.28-foo" + image: "linuxkit/kernel:4.9.33--dirty" ``` -If you have more substantial changes, or require a different kernel -version, it's best to replicate the kernel build system and change the -Docker Hub organisation to your own. +If you have committed your local changes, the `-dirty` will not be appended. Then you can also override the Hub organisation to use the image elsewhere with: +``` +make ORG= +``` +The image will be uploaded to Hub and can be use in a YAML file as +`/kernel:4.9.33` or as `/kernel:4.9.33-`. ## Working with Linux kernel patches for LinuxKit diff --git a/kernel/Makefile b/kernel/Makefile index c88f079f6..40a00012a 100644 --- a/kernel/Makefile +++ b/kernel/Makefile @@ -2,11 +2,11 @@ # in a scratch container, which contains the bzImage, a tar # ball with modules, the kernel sources, and in some case, the perf binary. # -# Each kernel is pushed to hub twice, once as -# linuxkit/kernel:..- and once as -# linuxkit/kernel:..x. The is the git tree hash -# of the current directory. The build will only rebuild the kernel -# image if the git tree hash changed. +# Each kernel is pushed to hub twice: +# - linuxkit/kernel:..- +# - linuxkit/kernel:.. +# The is the git tree hash of the current directory. The build +# will only rebuild the kernel image if the git tree hash changed. # # For some kernels we also build a separate package containing the perf utility # which is specific to a given kernel. perf packages are tagged the same way @@ -19,14 +19,25 @@ ORG?=linuxkit IMAGE:=kernel IMAGE_PERF:=kernel-perf -.PHONY: check tag push sign +# Add '-dirty' to hash if the repository is not clean. make does not +# concatenate strings without spaces, so we use the documented trick +# of replacing the space with nothing. +DIRTY=$(shell git diff-index --quiet HEAD --; echo $$?) +ifneq ($(DIRTY),0) +HASH+=-dirty +nullstring := +space := $(nullstring) $(nullstring) +TAG=$(subst $(space),,$(HASH)) +else +TAG=$(HASH) +endif + +.PHONY: check tag push # Targets: # build: builds all kernels -# push: pushes all tagged kernel images to hub -# sign: sign and push all kernel images to hub +# push: pushes and sign all tagged kernel images to hub build: push: -sign: # A template for defining kernel build # Arguments: @@ -34,57 +45,45 @@ sign: # $2: Kernel "series", e.g., 4.9.x # $3: Build a debug kernel (used as suffix for image) # This defines targets like: -# build_4.9.x, push_4.9.x and sign_4.9.x and adds them as dependencies +# build_4.9.x and push_4.9.x and adds them as dependencies # to the global targets # Set $3 to "_dbg", to build debug kernels. This defines targets like # build_4.9.x_dbg and adds "_dbg" to the hub image name. define kernel build_$(2)$(3): Dockerfile Makefile $(wildcard patches-$(2)/*) kernel_config-$(2) kernel_config.debug - docker pull $(ORG)/$(IMAGE):$(1)$(3)-$(HASH) || \ + docker pull $(ORG)/$(IMAGE):$(1)$(3)-$(TAG) || \ docker build \ --build-arg KERNEL_VERSION=$(1) \ --build-arg KERNEL_SERIES=$(2) \ --build-arg DEBUG=$(3) \ - --no-cache -t $(ORG)/$(IMAGE):$(1)$(3)-$(HASH) . + --no-cache -t $(ORG)/$(IMAGE):$(1)$(3)-$(TAG) . push_$(2)$(3): build_$(2)$(3) - docker pull $(ORG)/$(IMAGE):$(1)$(3)-$(HASH) || \ - (docker push $(ORG)/$(IMAGE):$(1)$(3)-$(HASH) && \ - docker tag $(ORG)/$(IMAGE):$(1)$(3)-$(HASH) $(ORG)/$(IMAGE):$(2)$(3) && \ - docker push $(ORG)/$(IMAGE):$(2)$(3)) - -sign_$(2)$(3): build_$(2)$(3) - DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(1)$(3)-$(HASH) || \ - (DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(1)$(3)-$(HASH) && \ - docker tag $(ORG)/$(IMAGE):$(1)$(3)-$(HASH) $(ORG)/$(IMAGE):$(2)$(3) && \ - DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(2)$(3)) + @if [ $(DIRTY) -ne 0 ]; then echo "Your repository is not clean. Will not push image"; exit 1; fi + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE):$(1)$(3)-$(TAG) || \ + (DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(1)$(3)-$(TAG) && \ + docker tag $(ORG)/$(IMAGE):$(1)$(3)-$(TAG) $(ORG)/$(IMAGE):$(1)$(3) && \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE):$(1)$(3)) build: build_$(2)$(3) push: push_$(2)$(3) -sign: sign_$(2)$(3) ifneq ($(2), 4.4.x) build_perf_$(2)$(3): build_$(2)$(3) - docker pull $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(HASH) || \ + docker pull $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(TAG) || \ docker build -f Dockerfile.perf \ - --build-arg IMAGE=$(ORG)/$(IMAGE):$(1)$(3)-$(HASH) \ - --no-cache --network=none -t $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(HASH) . + --build-arg IMAGE=$(ORG)/$(IMAGE):$(1)$(3)-$(TAG) \ + --no-cache --network=none -t $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(TAG) . push_perf_$(2)$(3): build_perf_$(2)$(3) - docker pull $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(HASH) || \ - (docker push $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(HASH) && \ - docker tag $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(HASH) $(ORG)/$(IMAGE_PERF):$(2)$(3) && \ - docker push $(ORG)/$(IMAGE_PERF):$(2)$(3)) - -sign_perf_$(2)$(3): build_perf_$(2)$(3) - DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(HASH) || \ - (DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(HASH) && \ - docker tag $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(HASH) $(ORG)/$(IMAGE_PERF):$(2)$(3) && \ - DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE_PERF):$(2)$(3)) + @if [ $(DIRTY) -ne 0 ]; then echo "Your repository is not clean. Will not push image"; exit 1; fi + DOCKER_CONTENT_TRUST=1 docker pull $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(TAG) || \ + (DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(TAG) && \ + docker tag $(ORG)/$(IMAGE_PERF):$(1)$(3)-$(TAG) $(ORG)/$(IMAGE_PERF):$(1)$(3) && \ + DOCKER_CONTENT_TRUST=1 docker push $(ORG)/$(IMAGE_PERF):$(1)$(3)) build: build_perf_$(2)$(3) push: push_perf_$(2)$(3) -sign: sign_perf_$(2)$(3) endif endef