From d35dcb12804700c15fb398e1dce6ad8d5995929c Mon Sep 17 00:00:00 2001 From: Antoine Eiche <lewo@abesis.fr> Date: Mon, 9 Apr 2018 14:52:41 +0200 Subject: [PATCH] dockerTools.pullImage: documentation and release note --- doc/functions.xml | 55 +++++++++------------- nixos/doc/manual/release-notes/rl-1809.xml | 7 +++ 2 files changed, 28 insertions(+), 34 deletions(-) diff --git a/doc/functions.xml b/doc/functions.xml index 155ea2bd0043..cdae96703f13 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -624,10 +624,9 @@ merge:"diff3" <para> This function is analogous to the <command>docker pull</command> command, - in that can be used to fetch a Docker image from a Docker registry. - Currently only registry <literal>v1</literal> is supported. By default - <link xlink:href="https://hub.docker.com/">Docker Hub</link> is used to - pull images. + in that can be used to pull a Docker image from a Docker registry. + By default <link xlink:href="https://hub.docker.com/">Docker Hub</link> + is used to pull images. </para> <para> @@ -638,13 +637,10 @@ merge:"diff3" <title>Docker pull</title> <programlisting> pullImage { - imageName = "debian"; <co xml:id='ex-dockerTools-pullImage-1' /> - imageTag = "jessie"; <co xml:id='ex-dockerTools-pullImage-2' /> - imageId = null; <co xml:id='ex-dockerTools-pullImage-3' /> - sha256 = "1bhw5hkz6chrnrih0ymjbmn69hyfriza2lr550xyvpdrnbzr4gk2"; <co xml:id='ex-dockerTools-pullImage-4' /> - - indexUrl = "https://index.docker.io"; <co xml:id='ex-dockerTools-pullImage-5' /> - registryVersion = "v1"; + imageName = "nixos/nix"; <co xml:id='ex-dockerTools-pullImage-1' /> + imageDigest = "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; <co xml:id='ex-dockerTools-pullImage-2' /> + finalImageTag = "1.11"; <co xml:id='ex-dockerTools-pullImage-3' /> + sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; <co xml:id='ex-dockerTools-pullImage-4' /> } </programlisting> </example> @@ -652,24 +648,28 @@ merge:"diff3" <calloutlist> <callout arearefs='ex-dockerTools-pullImage-1'> <para> - <varname>imageName</varname> specifies the name of the image to be - downloaded, which can also include the registry namespace (e.g. - <literal>library/debian</literal>). This argument is required. + <varname>imageName</varname> specifies the name of the image to be downloaded, + which can also include the registry namespace (e.g. <literal>nixos</literal>). + This argument is required. </para> </callout> <callout arearefs='ex-dockerTools-pullImage-2'> <para> - <varname>imageTag</varname> specifies the tag of the image to be - downloaded. By default it's <literal>latest</literal>. + <varname>imageDigest</varname> specifies the digest of the image + to be downloaded. Skopeo can be used to get the digest of an image +<programlisting> + $ skopeo inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest' + sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b + </programlisting> + This argument is required. </para> </callout> <callout arearefs='ex-dockerTools-pullImage-3'> <para> - <varname>imageId</varname>, if specified this exact image will be - fetched, instead of <varname>imageName/imageTag</varname>. However, the - resulting repository will still be named - <varname>imageName/imageTag</varname>. By default it's - <literal>null</literal>. + <varname>finalImageTag</varname>, 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 <literal>latest</literal>. </para> </callout> <callout arearefs='ex-dockerTools-pullImage-4'> @@ -677,19 +677,6 @@ merge:"diff3" <varname>sha256</varname> is the checksum of the whole fetched image. This argument is required. </para> - <note> - <para> - The checksum is computed on the unpacked directory, not on the final - tarball. - </para> - </note> - </callout> - <callout arearefs='ex-dockerTools-pullImage-5'> - <para> - In the above example the default values are shown for the variables - <varname>indexUrl</varname> and <varname>registryVersion</varname>. Hence - by default the Docker.io registry is used to pull the images. - </para> </callout> </calloutlist> </section> diff --git a/nixos/doc/manual/release-notes/rl-1809.xml b/nixos/doc/manual/release-notes/rl-1809.xml index 2fd7b7709797..ec7b2f107e8e 100644 --- a/nixos/doc/manual/release-notes/rl-1809.xml +++ b/nixos/doc/manual/release-notes/rl-1809.xml @@ -112,6 +112,13 @@ $ nix-instantiate -E '(import <nixpkgsunstable> {}).gitFull' <title>Other Notable Changes</title> <itemizedlist> + <listitem> + <para> + <literal>dockerTools.pullImage</literal> relies on image digest + instead of image tag to download the image. The + <literal>sha256</literal> of a pulled image has to be updated. + </para> + </listitem> <listitem> <para> <literal>lib.attrNamesToStr</literal> has been deprecated. Use more