diff --git a/doc/functions.xml b/doc/functions.xml index ac75c4fc10e4..4fc387f0fbd6 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -13,567 +13,5 @@ -
- 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. - -
-
+ 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. + +
+