diff --git a/BUILDING.md b/BUILDING.md index cba6a011a..b50c780f2 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -180,7 +180,13 @@ RUN apt-get update && \ ``` -In our Docker container we will use a specific `runc` build which includes [seccomp](https://en.wikipedia.org/wiki/seccomp) and [apparmor](https://en.wikipedia.org/wiki/AppArmor) support. Hence why our Dockerfile includes `libseccomp-dev` as a dependency (apparmor support doesn't require external libraries). Please refer to [RUNC.md](/docs/RUNC.md) for the currently supported version of `runc` that is used by containerd. +In our Docker container we will build `runc` build, which includes +[seccomp](https://en.wikipedia.org/wiki/seccomp), [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux), +and [AppArmor](https://en.wikipedia.org/wiki/AppArmor) support. Seccomp support +in runc requires `libseccomp-dev` as a dependency (AppArmor and SELinux support +do not require external libraries at build time). Refer to [RUNC.md](docs/RUNC.md) +in the docs directory to for details about building runc, and to learn about +supported versions of `runc` as used by containerd. Let's suppose you build an image called `containerd/build` from the above Dockerfile. You can run the following command: @@ -209,9 +215,12 @@ Next, let's build `runc`: ```sh cd /go/src/github.com/opencontainers/runc -make BUILDTAGS='seccomp apparmor selinux' && make install +make && make install ``` +For further details about building runc, refer to [RUNC.md](docs/RUNC.md) in the +docs directory. + When working with `ctr`, the simple test client we just built, don't forget to start the daemon! ```sh diff --git a/README.md b/README.md index 64f1ae7cb..1ecec1ff0 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,8 @@ Please be aware: nightly builds might have critical bugs, it's not recommended f Runtime requirements for containerd are very minimal. Most interactions with the Linux and Windows container feature sets are handled via [runc](https://github.com/opencontainers/runc) and/or -OS-specific libraries (e.g. [hcsshim](https://github.com/Microsoft/hcsshim) for Microsoft). The current required version of `runc` is always listed in [RUNC.md](/docs/RUNC.md). +OS-specific libraries (e.g. [hcsshim](https://github.com/Microsoft/hcsshim) for Microsoft). +The current required version of `runc` is described in [RUNC.md](docs/RUNC.md). There are specific features used by containerd core code and snapshotters that will require a minimum kernel diff --git a/contrib/Dockerfile.test b/contrib/Dockerfile.test index 2537ff628..e1e7b82b1 100644 --- a/contrib/Dockerfile.test +++ b/contrib/Dockerfile.test @@ -5,6 +5,10 @@ # 2.) docker run -it --privileged -v /tmp:/tmp --tmpfs /var/lib/containerd-test containerd-test bash # 3.) $ make binaries install test # +# Use the RUNC_VERSION build-arg to build with a custom version of runc, for example, +# to build runc v1.0.0-rc93, use: +# +# docker build -t containerd-test --build-arg RUNC_VERSION=v1.0.0-rc93 -f Dockerfile.test ../ ARG GOLANG_VERSION=1.16.1 @@ -32,8 +36,9 @@ RUN apt-get update && apt-get install -y \ libseccomp-dev \ --no-install-recommends -COPY go.mod go.mod -COPY script/setup/install-runc install-runc +COPY script/setup/runc-version script/setup/install-runc ./ +# Allow overriding the version of runc to install through build-args +ARG RUNC_VERSION ARG GOPROXY=direct RUN ./install-runc diff --git a/docs/RUNC.md b/docs/RUNC.md index 4ac52c22f..281c4b302 100644 --- a/docs/RUNC.md +++ b/docs/RUNC.md @@ -1,25 +1,48 @@ -containerd is built with OCI support and with support for advanced features provided by [runc](https://github.com/opencontainers/runc). +containerd is built with OCI support and with support for advanced features +provided by [runc](https://github.com/opencontainers/runc). -We depend on a specific `runc` version when dealing with advanced features. You should have a specific runc build for development. The current supported runc commit is described in [`go.mod`](../go.mod). Please refer to the line that starts with `github.com/opencontainers/runc`. +Development (`-dev`) and pre-releases of containerd may depend features in `runc` +that have not yet been released, and may require a specific runc build. The version +of runc that is tested against in our CI can be found in the [`script/setup/runc-version`](../script/setup/runc-version) +file, which may point to a git-commit (for pre releases) or tag in the runc +repository. -For more information on how to clone and build runc see the runc Building [documentation](https://github.com/opencontainers/runc#building). +For regular (non-pre-)releases of containerd releases, we attempt to use released +(tagged) versions of runc. We recommend using a version of runc that's equal to +or higher than the version of runc described in [`script/setup/runc-version`](../script/setup/runc-version). -Note: before building you may need to install additional support, which will vary by platform. For example, you may need to install `libseccomp` e.g. `libseccomp-dev` for Ubuntu. +If you encounter any runtime errors, make sure your runc is in sync with the +commit or tag provided in that file. ## building +> For more information on how to clone and build runc also refer to the runc +> building [documentation](https://github.com/opencontainers/runc#building). + +Before building runc you may need to install additional build dependencies, which +will vary by platform. For example, you may need to install `libseccomp` e.g. +`libseccomp-dev` for Ubuntu. + From within your `opencontainers/runc` repository run: -### apparmor - ```bash -make BUILDTAGS='seccomp apparmor' && sudo make install +make && sudo make install ``` -### selinux +Starting with runc 1.0.0-rc93, the "selinux" and "apparmor" buildtags have been +removed, and runc builds have SELinux, AppArmor, and seccomp support enabled +by default. Note that "seccomp" can be disabled by passing an empty `BUILDTAGS` +make variable, but is highly recommended to keep enabled. -```bash -make BUILDTAGS='seccomp selinux' && sudo make install +By default, runc is compiled with kernel-memory limiting support enabled. This +functionality is deprecated in kernel 5.4 and up, and is known to be broken on +RHEL7 and CentOS 7 3.10 kernels. For these kernels, we recommend disabling kmem +support using the `nokmem` build-tag. When doing so, be sure to set the `seccomp` +build-tag to enable seccomp support, for example: + +```sh +make BUILDTAGS='nokmem seccomp' && make install ``` -After an official runc release we will start pinning containerd support to a specific version but various development and testing features may require a newer runc version than the latest release. If you encounter any runtime errors, please make sure your runc is in sync with the commit/tag provided in this document. +For details about the `nokmem` build-tag, refer to the discussion on [opencontainers/runc#2594](https://github.com/opencontainers/runc/pull/2594). +For further details on building runc, refer to the [build instructions in the runc README](https://github.com/opencontainers/runc#building). diff --git a/script/setup/install-runc b/script/setup/install-runc index 94e511289..7717cb1fa 100755 --- a/script/setup/install-runc +++ b/script/setup/install-runc @@ -21,13 +21,16 @@ set -eu -o pipefail function install_runc() { - RUNC_COMMIT=$(grep opencontainers/runc "$GOPATH"/src/github.com/containerd/containerd/go.mod | awk '{print $2}') + script_dir="$(cd -- "$(dirname -- "$0")" > /dev/null 2>&1; pwd -P)" + + # When updating runc-version, consider updating the runc module in go.mod as well + : "${RUNC_VERSION:=$(cat "${script_dir}/runc-version")}" TMPROOT=$(mktemp -d) git clone https://github.com/opencontainers/runc.git "${TMPROOT}"/runc pushd "${TMPROOT}"/runc - git checkout "${RUNC_COMMIT}" - make BUILDTAGS='apparmor seccomp selinux' runc + git checkout "${RUNC_VERSION}" + make make install popd rm -fR "${TMPROOT}" diff --git a/script/setup/runc-version b/script/setup/runc-version new file mode 100644 index 000000000..e989c7fe6 --- /dev/null +++ b/script/setup/runc-version @@ -0,0 +1 @@ +v1.0.0-rc93