From: John Mulligan Date: Fri, 14 Feb 2025 19:51:03 +0000 (-0500) Subject: doc: document the new container build tool and link to it in README X-Git-Tag: v18.2.5~23^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=c5748f0871944b5e43fd1f5069ede0b69918ed5b;p=ceph.git doc: document the new container build tool and link to it in README Add a new markdown file in the root of the tree, ContainerBuild.md, that can serve as a basic introduction to the new container build tools recently merged to ceph. Add a small 'breadcrumb' section to the project README.md to help find this new document. Signed-off-by: John Mulligan (cherry picked from commit 313546146c429e784ec291b686907f47b33c595c) --- diff --git a/ContainerBuild.md b/ContainerBuild.md new file mode 100644 index 0000000000000..3652814251b93 --- /dev/null +++ b/ContainerBuild.md @@ -0,0 +1,179 @@ +# Build Ceph within a Container + +The Ceph project includes a script and additional files that help build +the ceph.git sources inside an OCI-style container. This script requires +Python 3 (tested with 3.8 or later) and Podman or Docker. + +The script aims to make it simple for a developer or anyone +wanting to compile Ceph on Linux but not wanting to dedicate a full +physical or virtual host to the job. The containers encapsulate the +build dependencies and environment and are quick and easy to clean +up when you no longer need them. + +# build-with-containers.py Introduction + +The script exists within the ceph.git tree at +`src/script/build-with-container.py`. The script operates on the entire Ceph +repository and will automatically try to detect the root of the ceph.git tree. +At any time the `--help` option can be passed to the script for a complete +listing of command line options. + +To start with the default options run `./src/script/build-with-container.py`. +The script will first check if a build image already exists, if not it +will construct one using the `Dockerfile.build` file in the Ceph tree [1]. + +Once a build container is available the script will build Ceph from source using +a build directory named `build` in the root of the source tree. The default +environment uses a base distribution of `centos9`. + +You can select the base distribution to use with the `--distro`/`-d` option. +The list of available distribution bases include `ubuntu22.04` and `centos9`. +These choices are known to work well. Other more experimental choices, +including `ubuntu24.04` and `centos10`, are available as well but do not expect +these platforms to work without tinkering. This option is a shorthand for +specifying the base container image that will be used to construct the build +image, the tags used for that image, as well as helping determine what kind of +packages can be produced using that build image. + +You can specify where build artifacts are written with the `--build-dir`/`-b` +option. For example `./src/script/build-with-container.py -b build.try1`. + +The tool supports mutliple build targets. Often these targets are chained +together - for example almost all targets depend on the container target. To +select a target use the `--execute`/`-e` command line option. For example: +`./src/script/build-with-container.py -e tests` will execute the unit tests +after building them. (Note: the `--no-prereqs` option exists to disable the +chaining but this should not be needed in most circumstances) + + +[1] - This behavior can be customized with the `--image-sources`/`-I` +option. + + +## Examples: + +Build from source code on CentOS 9, with a build directory named for the base +distribution: +``` +./src/script/build-with-container.py -d centos9 -b build.centos9 -e build +``` + +Build from source code on Ubuntu 22.04, with a build directory named for the +base distribution: +``` +./src/script/build-with-container.py -d ubuntu22.04 -b build.u2204 -e build +``` + +Build RPM packages on Centos 9: +``` +./src/script/build-with-container.py -d centos9 -e packages +``` + +Build Debian packages on Ubuntu 22.04 (Jammy): +``` +./src/script/build-with-container.py -d ubuntu22.04 -e packages +``` + +## Common Targets +* build - Build Ceph sources. Compiles C/C++ code, etc +* tests - Execute unit tests. Runs the unit test suite, depends on `buildtests` to compile some of the test suites +* custom - Execute a custom command. See description below +* packages - Build Ceph packages of the selected distribution's native package type +* interactive - Start the build container in an interactive mode + +### Custom Commands + +The `custom` target can be used to run a single command that the script is not +already programmed to handle. The custom command must come after a `--` to terminate +the normal command line arguments for `build-with-container.py`. For example: +``` +./src/script/build-with-container.py -d ubuntu22.04 -e custom -- shellcheck src/script/buildcontainer-setup.sh +``` + +### Interactive mode + +The `interactive` target can be used to run a shell within the container. This +is handy for those times you want to run multiple commands, by hand, within the +container environment. +As an example: +``` +./src/script/build-with-container.py -d ubuntu22.04 -e interactive +``` + + +## Additional Features + +### Control build image name and tags + +The `build-with-container.py` script automatically generates images names based +on a standard name and auto-generated tag. By default the script names the +image `ceph-build` and assumes the images are local only - the image name will +not refer to any image registry. The images are tagged with the name of the +current branch and base distribution. For example, assuming we're on a branch +named `wip-test` and we execute the script with `-d ubuntu22.04` we will expect +or build an image named `ceph-build:wip-test.ubuntu22.04`. + +The image name/repository can be customized using the `--image-repo` option. +The tag can be overridden by the `--tag` option or extended by using the +`--tag` option with a plus (+) character at the start of the value. For +example: `./src/script/build-with-container.py +--image-repo=quay.io/example/build-example --tag=foobar` would create or reuse +an image named `quay.io/example/build-example:foobar`. +`./src/script/build-with-container.py +--image-repo=quay.io/example/build-example --distro=centos9 --tag=+foobar` +would use an image named +`quay.io/example/build-example:wip-test.centos9.foobar`. + +If one wants to override the name of the branch or the branch can not be +automatically detected the `--current-branch` option can be supplied to +customize this value. + + +### Control build image source + +By default `build-with-container.py` will try reuse build images if they are +cached in the local container store. If the image is not present it will build +one. In addition to these default actions the script can be intructed to "pull" +an image from a remote registry, possibly avoiding the need to build an image. + +How the build image is acquired can be controlled using the `--image-sources` +option. The option takes a comma-separated list of terms. The terms are +`cache`, `pull`, and `build`: +* build - Create a new build image +* cache - Check for an existing image in local container storage +* pull - Pull an image form a container image registry + +So for example if you did not want to fall back to building an image locally, +you could pass `--image-sources=cache,pull` to the script. Passing +`--image-sources=build` will force the script to rebuild an image even if would +be available elsewhere. + +When an image is to be built the image base is typically derived from the name +of the distribution being used. However, the base image can be overridden on +the command line using the `--base-image` option. For example, if one had a +local registry with a CentOS 9 (Stream) base image the following example could +be used: `./src/script/build-with-container.py -d centos9 --base-image +myreg.example.com/ceph/centos-base:9` + + +### Controlling where files are written + +By default the directory holding the Ceph source tree is mounted at `/ceph` +within the container (controlled by the `--homedir` option). Various build tasks +will write files to this directory. In some cases it's useful to keep the +directory free from changes and so the `--overlay-dir` option can be used to +make that volume use an overlay. + +The overlay directory will be automatically created if needed and will contain +a `content` directory for new or updated files and a `work` directory, a +special directory needed by the overlayfs. For example: +`./src/script/build-with-container.py --overlay-dir build.ovr -b build.inner -d +centos9` will end up creating a directory `build.ovr/content/build.inner` which +will contain the results of the compile that would typically appear in just +`build.inner`. Other writes that would have normally effected the source tree +will appear in `build.ovr/content` + +The overlay can also be temporary, with no files persisted after the container +has exited. Pass `--overlay-dir=-` to enable this option. Note that invoking +`build-with-container.py` default targets may use multiple container instances +and passing this option will break those targets. diff --git a/README.md b/README.md index 6ce824ea8bd6f..395752bc9d423 100644 --- a/README.md +++ b/README.md @@ -246,6 +246,17 @@ over manual test execution. To view these options run: man ctest +### Building Ceph using Containers + +Ceph now provides tools to build the code, run unit tests, or build packages +from within an OCI-style container using Podman or Docker! This allows one to +build code for distributions other than the one you have on your system, avoids +the need to install build dependencies for Ceph on your local system and +provides an opportunity to test builds on platforms that are not yet supported +by the official build infrastructure. For more details see the [container build +document](ContainerBuild.md). + + ## Building the Documentation ### Prerequisites