From 8bf342ffb86eedf8a9749420b4019ab1e4c21629 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 14:13:12 -0400 Subject: nixpkgs docs: move dockertool to its own file --- doc/functions/dockertools.xml | 566 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 566 insertions(+) create mode 100644 doc/functions/dockertools.xml (limited to 'doc/functions/dockertools.xml') diff --git a/doc/functions/dockertools.xml b/doc/functions/dockertools.xml new file mode 100644 index 000000000000..8bfdb3c68d7a --- /dev/null +++ b/doc/functions/dockertools.xml @@ -0,0 +1,566 @@ +
+ pkgs.dockerTools + + + pkgs.dockerTools is a set of functions for creating and + manipulating Docker images according to the + + Docker Image Specification v1.2.0 . Docker itself is not used to + perform any of the operations done by these functions. + + + + + The dockerTools API is unstable and may be subject to + backwards-incompatible changes in the future. + + + +
+ buildImage + + + This function is analogous to the docker build command, + in that can used to build a Docker-compatible repository tarball containing + a single image with one or multiple layers. As such, the result is suitable + for being loaded in Docker with docker load. + + + + The parameters of buildImage with relative example + values are described below: + + + + Docker build + +buildImage { + name = "redis"; + tag = "latest"; + + fromImage = someBaseImage; + fromImageName = null; + fromImageTag = "latest"; + + contents = pkgs.redis; + runAsRoot = '' + #!${stdenv.shell} + mkdir -p /data + ''; + + config = { + Cmd = [ "/bin/redis-server" ]; + WorkingDir = "/data"; + Volumes = { + "/data" = {}; + }; + }; +} + + + + + The above example will build a Docker image redis/latest + from the given base image. Loading and running this image in Docker results + in redis-server being started automatically. + + + + + + name specifies the name of the resulting image. This + is the only required argument for buildImage. + + + + + tag specifies the tag of the resulting image. By + default it's null, which indicates that the nix output + hash will be used as tag. + + + + + fromImage is the repository tarball containing the + base image. It must be a valid Docker image, such as exported by + docker save. By default it's null, + which can be seen as equivalent to FROM scratch of a + Dockerfile. + + + + + fromImageName can be used to further specify the base + image within the repository, in case it contains multiple images. By + default it's null, in which case + buildImage will peek the first image available in the + repository. + + + + + fromImageTag can be used to further specify the tag of + the base image within the repository, in case an image contains multiple + tags. By default it's null, in which case + buildImage will peek the first tag available for the + base image. + + + + + contents is a derivation that will be copied in the + new layer of the resulting image. This can be similarly seen as + ADD contents/ / in a Dockerfile. + By default it's null. + + + + + runAsRoot is a bash script that will run as root in an + environment that overlays the existing layers of the base image with the + new resulting layer, including the previously copied + contents derivation. This can be similarly seen as + RUN ... in a Dockerfile. + + + Using this parameter requires the kvm device to be + available. + + + + + + + config is used to specify the configuration of the + containers that will be started off the built image in Docker. The + available options are listed in the + + Docker Image Specification v1.2.0 . + + + + + + After the new layer has been created, its closure (to which + contents, config and + runAsRoot contribute) will be copied in the layer + itself. Only new dependencies that are not already in the existing layers + will be copied. + + + + At the end of the process, only one new single layer will be produced and + added to the resulting image. + + + + The resulting repository will only list the single image + image/tag. In the case of + it would be + redis/latest. + + + + It is possible to inspect the arguments with which an image was built using + its buildArgs attribute. + + + + + If you see errors similar to getProtocolByName: does not exist + (no such protocol name: tcp) you may need to add + pkgs.iana-etc to contents. + + + + + + If you see errors similar to Error_Protocol ("certificate has + unknown CA",True,UnknownCa) you may need to add + pkgs.cacert to contents. + + + + + Impurely Defining a Docker Layer's Creation Date + + By default buildImage will use a static + date of one second past the UNIX Epoch. This allows + buildImage to produce binary reproducible + images. When listing images with docker list + images, the newly created images will be listed like + this: + + + + You can break binary reproducibility but have a sorted, + meaningful CREATED column by setting + created to now. + + + + and now the Docker CLI will display a reasonable date and + sort the images as expected: + + however, the produced images will not be binary reproducible. + + +
+ +
+ buildLayeredImage + + + Create a Docker image with many of the store paths being on their own layer + to improve sharing between images. + + + + + + name + + + + The name of the resulting image. + + + + + + tag optional + + + + Tag of the generated image. + + + Default: the output path's hash + + + + + + contents optional + + + + Top level paths in the container. Either a single derivation, or a list + of derivations. + + + Default: [] + + + + + + config optional + + + + Run-time configuration of the container. A full list of the options are + available at in the + + Docker Image Specification v1.2.0 . + + + Default: {} + + + + + + created optional + + + + Date and time the layers were created. Follows the same + now exception supported by + buildImage. + + + Default: 1970-01-01T00:00:01Z + + + + + + maxLayers optional + + + + Maximum number of layers to create. + + + Default: 24 + + + + + +
+ Behavior of <varname>contents</varname> in the final image + + + Each path directly listed in contents will have a + symlink in the root of the image. + + + + For example: + + will create symlinks for all the paths in the hello + package: + /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/bin/hello +/share/info/hello.info -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/info/hello.info +/share/locale/bg/LC_MESSAGES/hello.mo -> /nix/store/h1zb1padqbbb7jicsvkmrym3r6snphxg-hello-2.10/share/locale/bg/LC_MESSAGES/hello.mo +]]> + +
+ +
+ Automatic inclusion of <varname>config</varname> references + + + The closure of config is automatically included in the + closure of the final image. + + + + This allows you to make very simple Docker images with very little code. + This container will start up and run hello: + + +
+ +
+ Adjusting <varname>maxLayers</varname> + + + Increasing the maxLayers increases the number of layers + which have a chance to be shared between different images. + + + + Modern Docker installations support up to 128 layers, however older + versions support as few as 42. + + + + If the produced image will not be extended by other Docker builds, it is + safe to set maxLayers to 128. + However it will be impossible to extend the image further. + + + + The first (maxLayers-2) most "popular" paths will have + their own individual layers, then layer #maxLayers-1 + will contain all the remaining "unpopular" paths, and finally layer + #maxLayers will contain the Image configuration. + + + + Docker's Layers are not inherently ordered, they are content-addressable + and are not explicitly layered until they are composed in to an Image. + +
+
+ +
+ pullImage + + + This function is analogous to the docker pull command, + in that can be used to pull a Docker image from a Docker registry. By + default Docker Hub is + used to pull images. + + + + Its parameters are described in the example below: + + + + Docker pull + +pullImage { + imageName = "nixos/nix"; + imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; + finalImageTag = "1.11"; + sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; + os = "linux"; + arch = "x86_64"; +} + + + + + + + imageName specifies the name of the image to be + downloaded, which can also include the registry namespace (e.g. + nixos). This argument is required. + + + + + imageDigest specifies the digest of the image to be + downloaded. Skopeo can be used to get the digest of an image, with its + inspect subcommand. Since a given + imageName may transparently refer to a manifest list + of images which support multiple architectures and/or operating systems, + supply the `--override-os` and `--override-arch` arguments to specify + exactly which image you want. By default it will match the OS and + architecture of the host the command is run on. + +$ nix-shell --packages skopeo jq --command "skopeo --override-os linux --override-arch x86_64 inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'" +sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b + + This argument is required. + + + + + finalImageTag, if specified, this is the tag of the + image to be created. Note it is never used to fetch the image since we + prefer to rely on the immutable digest ID. By default it's + latest. + + + + + sha256 is the checksum of the whole fetched image. + This argument is required. + + + + + os, if specified, is the operating system of the + fetched image. By default it's linux. + + + + + arch, if specified, is the cpu architecture of the + fetched image. By default it's x86_64. + + + +
+ +
+ exportImage + + + This function is analogous to the docker export command, + in that can used to flatten a Docker image that contains multiple layers. + It is in fact the result of the merge of all the layers of the image. As + such, the result is suitable for being imported in Docker with + docker import. + + + + + Using this function requires the kvm device to be + available. + + + + + The parameters of exportImage are the following: + + + + Docker export + +exportImage { + fromImage = someLayeredImage; + fromImageName = null; + fromImageTag = null; + + name = someLayeredImage.name; +} + + + + + The parameters relative to the base image have the same synopsis as + described in , except + that fromImage is the only required argument in this + case. + + + + The name argument is the name of the derivation output, + which defaults to fromImage.name. + +
+ +
+ shadowSetup + + + This constant string is a helper for setting up the base files for managing + users and groups, only if such files don't exist already. It is suitable + for being used in a runAsRoot + script for cases like + in the example below: + + + + Shadow base files + +buildImage { + name = "shadow-basic"; + + runAsRoot = '' + #!${stdenv.shell} + ${shadowSetup} + groupadd -r redis + useradd -r -g redis redis + mkdir /data + chown redis:redis /data + ''; +} + + + + + Creating base files like /etc/passwd or + /etc/login.defs are necessary for shadow-utils to + manipulate users and groups. + +
+
-- cgit 1.4.1