dockerTools.pullImage: control OS and architecture

2 files changed, 26 insertions, 5 deletions

diff --git a/doc/functions.xml b/doc/functions.xml
index c23f6aa2596..2a9cc44d5c5 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -649,6 +649,8 @@ merge:"diff3"
     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' />
+    os = "linux"; <co xml:id='ex-dockerTools-pullImage-5' />
+    arch = "x86_64"; <co xml:id='ex-dockerTools-pullImage-6' />
   }
   </programlisting>
    </example>
@@ -664,9 +666,15 @@ merge:"diff3"
     <callout arearefs='ex-dockerTools-pullImage-2'>
      <para>
       <varname>imageDigest</varname> specifies the digest of the image to be
-      downloaded. Skopeo can be used to get the digest of an image
+      downloaded. Skopeo can be used to get the digest of an image, with its
+      <varname>inspect</varname> subcommand.  Since a given <varname>imageName</varname>
+      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.
 <programlisting>
-  $ skopeo inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'
+  $ 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
   </programlisting>
       This argument is required.
@@ -686,6 +694,18 @@ merge:"diff3"
       This argument is required.
      </para>
     </callout>
+    <callout arearefs='ex-dockerTools-pullImage-5'>
+      <para>
+        <varname>os</varname>, if specified, is the operating system of the fetched image.
+        By default it's <literal>linux</literal>.
+      </para>
+    </callout>
+    <callout arearefs='ex-dockerTools-pullImage-6'>
+      <para>
+        <varname>arch</varname>, if specified, is the cpu architecture of the fetched image.
+        By default it's <literal>x86_64</literal>.
+      </para>
+    </callout>
    </calloutlist>
   </section>
 
diff --git a/pkgs/build-support/docker/default.nix b/pkgs/build-support/docker/default.nix
index 950c0c86a6e..bc79f9ff12f 100644
--- a/pkgs/build-support/docker/default.nix
+++ b/pkgs/build-support/docker/default.nix
@@ -36,10 +36,11 @@ rec {
   in
     { imageName
       # To find the digest of an image, you can use skopeo:
-      # skopeo inspect docker://docker.io/nixos/nix:1.11 | jq -r '.Digest'
-      # sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b
+      # see doc/functions.xml
     , imageDigest
     , sha256
+    , os ? "linux"
+    , arch ? "x86_64"
       # This used to set a tag to the pulled image
     , finalImageTag ? "latest"
     , name ? fixName "docker-image-${imageName}-${finalImageTag}.tar"
@@ -59,7 +60,7 @@ rec {
       sourceURL = "docker://${imageName}@${imageDigest}";
       destNameTag = "${imageName}:${finalImageTag}";
     } ''
-      skopeo copy "$sourceURL" "docker-archive://$out:$destNameTag"
+      skopeo --override-os ${os} --override-arch ${arch} copy "$sourceURL" "docker-archive://$out:$destNameTag"
     '';
 
   # We need to sum layer.tar, not a directory, hence tarsum instead of nix-hash.