dockerTools.pullImage: control OS and architecture

1 files changed, 22 insertions, 2 deletions

diff --git a/doc/functions.xml b/doc/functions.xml
index c23f6aa25967..2a9cc44d5c5b 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>