diff --git a/BUILDING.md b/BUILDING.md index dbe4d5c26..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: 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 c443a0e92..500aff8d0 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.15.8 @@ -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 +# 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 4da391ee3..2f35a2ce4 100644 --- a/docs/RUNC.md +++ b/docs/RUNC.md @@ -1,13 +1,28 @@ -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 `RUNC_VERSION` variable +in the [`script/setup/install-runc`](../script/setup/install-runc) script, 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/install-runc`](../script/setup/install-runc). -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: ```bash @@ -29,7 +44,5 @@ build-tag to enable seccomp support, for example: make BUILDTAGS='nokmem seccomp' && make install ``` -For details about the `nokmem` build-tag, refer to [opencontainers/runc#2594](https://github.com/opencontainers/runc/pull/2594). +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). - -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. diff --git a/script/setup/install-runc b/script/setup/install-runc index 541b69458..35d9ca146 100755 --- a/script/setup/install-runc +++ b/script/setup/install-runc @@ -21,13 +21,14 @@ set -eu -o pipefail function install_runc() { - RUNC_COMMIT=$(grep opencontainers/runc "$GOPATH"/src/github.com/containerd/containerd/go.mod | awk '{print $2}') + # When updating RUNC_VERSION, consider updating the runc module in go.mod as well + : "${RUNC_VERSION:=v1.0.0-rc93}" TMPROOT=$(mktemp -d) git clone https://github.com/opencontainers/runc.git "${TMPROOT}"/runc pushd "${TMPROOT}"/runc - git checkout "${RUNC_COMMIT}" - make runc + git checkout "${RUNC_VERSION}" + make make install popd rm -fR "${TMPROOT}"