Document docker transport is the only supported remote transport

The goal is to improve errors when users use the wrong transport in certain cases we stutter, in other cases we don't give enough information. Remove stutters when failing to pull remote images, because of lack of support. Fix errors returned by reference.Parse to wrap in image that was being checked. Fixes: #7116 Signed-off-by: Daniel J Walsh <[email protected]>
containers · Nov 29, 2020 · 9ba52e8 · 9ba52e8
1 parent 8b2c0a4
commit 9ba52e8
Show file tree

Hide file tree

Showing 8 changed files with 237 additions and 125 deletions.
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md
@@ -27,25 +27,42 @@ Images are stored in local image storage.
 ## SOURCE
 
  The SOURCE is the location from which the container images are pulled.
- The Image "SOURCE" uses a "transport":"details" format.
+ The Image "SOURCE" uses a "transport":"details" format.  Only the `docker` (container registry)
+ transport is allowed for remote access.
 
  Multiple transports are supported:
 
   **dir:**_path_
-  An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection.
+  An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This
+  is a non-standardized format, primarily useful for debugging or noninvasive container inspection.
 
-  **docker://**_docker-reference_
-  An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using `(podman login)`. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `(docker login)`.
+    $ podman pull dir:/tmp/myimage
+
+  **docker://**_docker-reference_ (Default)
+  An image reference stored in a remote container image registry. The reference can include a path to a
+  specific registry; if it does not, the registries listed in registries.conf will be queried to find a matching
+  image. By default, credentials from podman login (stored at $XDG_RUNTIME_DIR/containers/auth.json by default)
+  will  be used to authenticate; if these cannot be found, we will fall back to using credentials in
+  $HOME/.docker/config.json.
+
+    $ podman pull quay.io/username/myimage
 
   **docker-archive:**_path_[**:**_docker-reference_]
-  An image is stored in the `docker save` formatted file.  _docker-reference_ is only used when creating such a file, and it must not contain a digest.
+  An image is stored in the `docker save` formatted file.  _docker-reference_ is only used when creating such a
+  file, and it must not contain a digest.
+
+    $ podman pull docker-archive:/tmp/myimage
 
   **docker-daemon:**_docker-reference_
-  An image _docker-reference_ stored in the docker daemon internal storage.  _docker-reference_ must contain either a tag or a digest.  Alternatively, when reading images, the format can also be docker-daemon:algo:digest (an image ID).
+  An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest).
+
+    $ sudo podman pull docker-daemon:docker.io/library/myimage:33
 
   **oci-archive:**_path_**:**_tag_
   An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_.
 
+    $ podman pull oci-archive:/tmp/myimage
+
 ## OPTIONS
 
 #### **--all-tags**, **a**

diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md
@@ -29,18 +29,28 @@ Images are pushed from those stored in local image storage.
   **dir:**_path_
   An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection.
 
+    $ podman push myimage dir:/tmp/myimage
+
   **docker://**_docker-reference_
   An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using `(podman login)`. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `(docker login)`.
 
+    $ podman push myimage quay.io/username/myimage
+
   **docker-archive:**_path_[**:**_docker-reference_]
   An image is stored in the `docker save` formatted file.  _docker-reference_ is only used when creating such a file, and it must not contain a digest.
 
+    $ podman push myimage docker-archive:/tmp/myimage
+
   **docker-daemon:**_docker-reference_
-  An image _docker-reference_ stored in the docker daemon internal storage.  _docker-reference_ must contain either a tag or a digest.  Alternatively, when reading images, the format can also be docker-daemon:algo:digest (an image ID).
+  An image in _docker-reference_ format stored in the docker daemon internal storage. _docker-reference_ must contain a tag.
+
+    $ sudo podman push myimage docker-daemon:docker.io/library/myimage:33
 
   **oci-archive:**_path_**:**_tag_
   An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_.
 
+    $ podman push myimage oci-archive:/tmp/myimage
+
 ## OPTIONS
 
 #### **--authfile**=*path*