From 525cb54e142bc0e19b50cf982594f0c199077d18 Mon Sep 17 00:00:00 2001 From: Valentin Rothberg Date: Tue, 22 Jun 2021 13:08:24 +0200 Subject: [CI:DOCS] push/pull docs: clarify supported transports The man pages of podman push/pull were incomplete in explaining all supported transports. To keep things simple, explain the defaults, refer to containers-transports(5) and give some examples. Fixes: #10730 Signed-off-by: Valentin Rothberg --- docs/source/markdown/podman-pull.1.md | 48 +++++++++++++---------------------- docs/source/markdown/podman-push.1.md | 43 +++++++++++++------------------ 2 files changed, 36 insertions(+), 55 deletions(-) diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index 54f990601..084327efd 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -21,42 +21,30 @@ 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. Only the `docker` (container registry) - transport is allowed for remote access. + SOURCE is the location from the container image is pulled from. It supports all transports from `containers-transports(5)`. If no transport is specified, the input is subject to short-name resolution and the `docker` (i.e., container registry) transport is used. For remote clients, `docker` is the only supported transport. - 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. - - $ 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 +``` +# Pull from a container registry +$ 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. +# Pull from a container registry with short-name resolution +$ podman pull fedora - $ podman pull docker-archive:/tmp/myimage +# Pull from a container registry via the docker transport +$ podman pull docker://quay.io/username/myimage - **docker-daemon:**_docker-reference_ - 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). +# Pull from a local directory +$ podman pull dir:/tmp/myimage - $ sudo podman pull docker-daemon:docker.io/library/myimage:33 +# Pull from a tarball in the docker-archive format +$ podman pull docker-archive:/tmp/myimage - **oci-archive:**_path_**:**_tag_ - An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. +# Pull from a local docker daemon +$ sudo podman pull docker-daemon:docker.io/library/myimage:33 - $ podman pull oci-archive:/tmp/myimage +# Pull from a tarball in the OCI-archive format +$ podman pull oci-archive:/tmp/myimage +``` ## OPTIONS @@ -217,7 +205,7 @@ registries.conf is the configuration file which specifies which container regist NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -podman(1), podman-push(1), podman-login(1), containers-certs.d(5), containers-registries.conf(5) +podman(1), podman-push(1), podman-login(1), containers-certs.d(5), containers-registries.conf(5), containers-transports(5) ## HISTORY July 2017, Originally compiled by Urvashi Mohnani diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md index e26d73891..68478accd 100644 --- a/docs/source/markdown/podman-push.1.md +++ b/docs/source/markdown/podman-push.1.md @@ -20,37 +20,30 @@ Images are pushed from those stored in local image storage. ## DESTINATION - The DESTINATION is a location to store container images - The Image "DESTINATION" uses a "transport":"details" format. - If a transport is not given, podman push will attempt to push - to a registry. + DESTINATION is the location the container image is pushed to. It supports all transports from `containers-transports(5)`. If no transport is specified, the `docker` (i.e., container registry) transport is used. For remote clients, `docker` is the only supported transport. - 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. - - $ 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 +``` +# Push to a container registry +$ podman push quay.io/podman/stable - **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. +# Push to a container registry via the docker transport +$ podman push docker://quay.io/podman/stable - $ podman push myimage docker-archive:/tmp/myimage +# Push to a container registry with another tag +$ podman push myimage quay.io/username/myimage - **docker-daemon:**_docker-reference_ - An image in _docker-reference_ format stored in the docker daemon internal storage. _docker-reference_ must contain a tag. +# Push to a local directory +$ podman push myimage dir:/tmp/myimage - $ sudo podman push myimage docker-daemon:docker.io/library/myimage:33 +# Push to a tarball in the docker-archive format +$ podman push myimage docker-archive:/tmp/myimage - **oci-archive:**_path_**:**_tag_ - An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. +# Push to a local docker daemon +$ sudo podman push myimage docker-daemon:docker.io/library/myimage:33 - $ podman push myimage oci-archive:/tmp/myimage +# Push to a tarball in the OCI format +$ podman push myimage oci-archive:/tmp/myimage +``` ## OPTIONS @@ -161,4 +154,4 @@ Storing signatures ``` ## SEE ALSO -podman(1), podman-pull(1), podman-login(1), containers-certs.d(5) +podman(1), podman-pull(1), podman-login(1), containers-certs.d(5), containers-transports(5) -- cgit v1.2.3-54-g00ecf