[CI:DOCS] Improve podman-save and podman-push documentation #20537

amluto · 2023-10-30T19:22:42Z

podman-save has awkward semantics with regard tagging the saved image in the output. Improve the documentation, and suggest using podman push as an alternative.

Add a corresponding example to podman push's manpage.

See #20515

Does this PR introduce a user-facing change?

I think None. It's user-facing in the sense that it updates documentation. I don't think it needs a release note. Certainly no action is required.

If a release note is required, I suggest:

Updated podman-save documentation to suggest using podman push instead.

podman-save has awkward semantics with regard tagging the saved image in the output. Improve the documentation, and suggest using podman push as an alternative. Add a corresponding example to podman push's manpage. Signed-off-by: Andy Lutomirski <[email protected]>

rhatdan · 2023-10-30T19:26:17Z

docs/source/markdown/podman-push.1.md.in

@@ -40,6 +40,9 @@ $ sudo podman push myimage docker-daemon:docker.io/library/myimage:33

 # Push to a tarball in the OCI format
 $ podman push myimage oci-archive:/tmp/myimage
+
+# Push to a directory, with a relative path, in the OCI format with another tag


Add something about this being a good alternative to podman save

One you reference it, make sure you add podman save to the See Also section below.

docs/source/markdown/podman-save.1.md.in

rhatdan · 2023-10-30T19:28:10Z

/approve

openshift-ci · 2023-10-30T19:28:15Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: amluto, rhatdan

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [rhatdan]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

edsantiago

Thank you for your PR! I'm unable to understand how/why podman push solves the problem reported in #20515 (IMHO it defers the name-finding question, it does not solve it). But I'll leave that for others to argue. Inline, a few suggestions.

edsantiago · 2023-10-30T19:36:02Z

docs/source/markdown/podman-push.1.md.in

+# Push to a directory, with a relative path, in the OCI format with another tag
+$ podman push myimage oci:directory:tag


IMO the use of a relative path here makes everything more confusing: the casual reader has no way of knowing if the word directory is a keyword or an argument. oci:/tmp/myimage:mytag would be clearer, and oci:/tmp/myimagedir:quay.io/myrepo/myimage:mytag even more so.

I feel like adding a name like quay.io/myrepo/myimage:mytag makes the result more complicated.

edsantiago · 2023-10-30T19:39:25Z

docs/source/markdown/podman-save.1.md.in

@@ -22,6 +22,8 @@ Note: `:` is a restricted character and cannot be part of the file name.

 **podman save [OPTIONS] NAME[:TAG]**

+Most or all of **podman save**'s functionality is available, with more flexibility, in **[podman-push(1)](podman-push.1.md)**.


This is debatable. It might be friendlier just to not add this.

The comments in #20515 made it sounds like podman save is mostly for Docker compatibility. I'll defer to people actually involved in podman.

I'd not include this

I think the statement is correct but also thin that the text above is sufficient to highlight that podman-push can be used to create archives as well.

edsantiago · 2023-10-30T19:46:04Z

docs/source/markdown/podman-save.1.md.in

@@ -39,6 +41,14 @@ An image format to produce, one of:
 | **oci-dir**        | A directory using the OCI Image Format                                       |
 | **docker-dir**     | **dir** transport (see **containers-transports(5)**) with v2s2 manifest type |

+If **oci-archive** or **oci-dir** saves an image specified by tag, then it will save it in the OCI Image with the same tag.  If **oci-archive** or **oci-dir** saves an image specified by hash, it will not tag it at all, which may make using the resulting image unnecessarily complicated.


The word "tag" is overloaded, hence ambiguous. Replacing the first two instances of tag with name might be more readable.

And, would you consider removing the "which may" clause? That may be the case for some workflows but certainly not for others.

I reworded it.

I'm not that familiar with all the various OCI Image-consuming tools out there, but so far the only thing I've found that can work with these unnamed images is podman load.

This comes from PR containers#20537 comments. Signed-off-by: Andy Lutomirski <[email protected]>

amluto · 2023-10-30T20:14:26Z

Bah, I made a silly typo pushing an update and github interpreted that as closing the PR.

TomSweeneyRedHat · 2023-10-31T21:02:04Z

docs/source/markdown/podman-save.1.md.in

@@ -39,6 +41,14 @@ An image format to produce, one of:
 | **oci-dir**        | A directory using the OCI Image Format                                       |
 | **docker-dir**     | **dir** transport (see **containers-transports(5)**) with v2s2 manifest type |

+If **oci-archive** or **oci-dir** saves an image specified by name, then it will save it in the OCI Image with the same name (i.e. an **org.opencontainers.image.ref.name** annotation will be written).  If **oci-archive** or **oci-dir** saves an image specified by hash, the image will not be given a name in the saved image, which may make using the resulting image with tools that expect named images difficult.


Suggested change

If **oci-archive** or **oci-dir** saves an image specified by name, then it will save it in the OCI Image with the same name (i.e. an **org.opencontainers.image.ref.name** annotation will be written). If **oci-archive** or **oci-dir** saves an image specified by hash, the image will not be given a name in the saved image, which may make using the resulting image with tools that expect named images difficult.

If **oci-archive** or **oci-dir** saves an image specified by name, then it will keep it in the OCI Image with the same name (i.e., an **org.opencontainers.image.ref.name** annotation will be written). If **oci-archive** or **oci-dir** saves an image specified by hash, the image will not be given a name in the saved image, which may make using the resulting image with tools that expect named images difficult.

I'm on the fence about keep/save. The comma would be good though.

I'll keep "save". Saying "keep" seems odd -- the image doesn't start out in the OCI Image at all, so the image isn't being kept.

docs/source/markdown/podman-push.1.md.in

vrothberg

Great work, thanks! We can merge once the comments are addressed. I really like the description of the behavior when only a digest/hash is specified.

vrothberg · 2023-11-01T07:34:53Z

docs/source/markdown/podman-save.1.md.in

@@ -22,6 +22,8 @@ Note: `:` is a restricted character and cannot be part of the file name.

 **podman save [OPTIONS] NAME[:TAG]**

+Most or all of **podman save**'s functionality is available, with more flexibility, in **[podman-push(1)](podman-push.1.md)**.


I think the statement is correct but also thin that the text above is sufficient to highlight that podman-push can be used to create archives as well.

umohnani8 · 2023-11-06T13:59:35Z

@amluto can you please address the comments above so we can get this merged.

amluto · 2023-11-14T19:44:27Z

I'm leaving the "Most or all of podman save's functionality is available" part for now -- the other text that conveys that is farther down and maybe easy to miss. But feel free to argue with me :)

…0537 Signed-off-by: Andy Lutomirski <[email protected]>

packit-as-a-service · 2023-11-14T20:10:45Z

Cockpit tests failed for commit e9df8bd. @martinpitt, @jelly, @mvollmer please check.

martinpitt · 2023-11-15T05:16:21Z

Over night apparently quay.io was down, so all cockpit-revdeps tests failed with

Trying to pull quay.io/prometheus/busybox:latest...
Error: initializing source docker://quay.io/prometheus/busybox:latest: can't talk to a V1 container registry

It seems to be working again, so feel free to /packit retry-failed (or click "Re-run" here)

edsantiago

Thank you for your patience. Comments inline. Please also rebase to a current main and squash commits.

edsantiago · 2023-11-15T15:44:18Z

docs/source/markdown/podman-push.1.md.in

@@ -40,6 +44,9 @@ $ sudo podman push myimage docker-daemon:docker.io/library/myimage:33

 # Push to a tarball in the OCI format
 $ podman push myimage oci-archive:/tmp/myimage
+
+# Push to a directory in the OCI format with an explicitly specified tag
+$ podman push myimage oci:/tmp/myimage:tag


This is a counterintuitive situation for many users. Please add a note making it unambiguously clear that the destination directory is /tmp/myimage and that tag is an annotation:

# Push to a directory ... $ podman push myimage oci:/tmp/myimage:myname/mytag $ jq '.manifests[].annotations' /tmp/myimage/index.json { "org.opencontainers.image.ref.name": "myname/mytag" }

edsantiago · 2023-11-15T15:46:55Z

docs/source/markdown/podman-save.1.md.in

@@ -39,6 +41,14 @@ An image format to produce, one of:
 | **oci-dir**        | A directory using the OCI Image Format                                       |
 | **docker-dir**     | **dir** transport (see **containers-transports(5)**) with v2s2 manifest type |

+If **oci-archive** or **oci-dir** saves an image specified by name, then it will save it in the OCI Image with the same name (i.e., an **org.opencontainers.image.ref.name** annotation will be written).  If **oci-archive** or **oci-dir** saves an image specified by hash, the image will not be given a name in the saved image, which may make using the resulting image with tools that expect named images difficult.


Awkward phrasing, I find it hard to parse. At the very least please differentiate by name vs by hash to make it easier for a human reader.

edsantiago · 2023-11-15T15:47:14Z

docs/source/markdown/podman-save.1.md.in

@@ -39,6 +41,14 @@ An image format to produce, one of:
 | **oci-dir**        | A directory using the OCI Image Format                                       |
 | **docker-dir**     | **dir** transport (see **containers-transports(5)**) with v2s2 manifest type |

+If **oci-archive** or **oci-dir** saves an image specified by name, then it will save it in the OCI Image with the same name (i.e., an **org.opencontainers.image.ref.name** annotation will be written).  If **oci-archive** or **oci-dir** saves an image specified by hash, the image will not be given a name in the saved image, which may make using the resulting image with tools that expect named images difficult.
+
+To explicity specify the name to be used in the saved image, use the **oci-archive:** or **oci::** schemes with **[podman-push(1)](podman-push.1.md)** instead.  For example:


Typo, "explicitly"

edsantiago · 2023-11-15T15:48:33Z

docs/source/markdown/podman-save.1.md.in

+To explicity specify the name to be used in the saved image, use the **oci-archive:** or **oci::** schemes with **[podman-push(1)](podman-push.1.md)** instead.  For example:
+
+```
+$ podman push IMAGE oci:directoryname:tagname


I have to insist that this is confusing: a nonexpert reader will have trouble figuring out what is an exact keyword and what is a mutable argument. See above for (IMO) clearer ways to say this.

openshift-ci bot added the release-note label Oct 30, 2023

rhatdan reviewed Oct 30, 2023

View reviewed changes

docs/source/markdown/podman-save.1.md.in Show resolved Hide resolved

rhatdan changed the title ~~Improve podman-save and podman-push documentation~~ [CI:DOCS] Improve podman-save and podman-push documentation Oct 30, 2023

openshift-ci bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Oct 30, 2023

edsantiago reviewed Oct 30, 2023

View reviewed changes

Improve the podman-push and podman-save manpages

952b39c

This comes from PR containers#20537 comments. Signed-off-by: Andy Lutomirski <[email protected]>

amluto closed this Oct 30, 2023

amluto deleted the save-docs branch October 30, 2023 20:12

amluto reopened this Oct 30, 2023

TomSweeneyRedHat reviewed Oct 31, 2023

View reviewed changes

docs/source/markdown/podman-push.1.md.in Outdated Show resolved Hide resolved

vrothberg reviewed Nov 1, 2023

View reviewed changes

Update podman-push and podman-save docs from comments on containers#2…

e9df8bd

…0537 Signed-off-by: Andy Lutomirski <[email protected]>

edsantiago requested changes Nov 15, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CI:DOCS] Improve podman-save and podman-push documentation #20537

[CI:DOCS] Improve podman-save and podman-push documentation #20537

amluto commented Oct 30, 2023

rhatdan Oct 30, 2023 •

edited

Loading

rhatdan commented Oct 30, 2023

openshift-ci bot commented Oct 30, 2023

edsantiago left a comment

edsantiago Oct 30, 2023

amluto Oct 30, 2023

edsantiago Oct 30, 2023

amluto Oct 30, 2023

TomSweeneyRedHat Oct 31, 2023

vrothberg Nov 1, 2023

edsantiago Oct 30, 2023

amluto Oct 30, 2023

amluto commented Oct 30, 2023

TomSweeneyRedHat Oct 31, 2023

TomSweeneyRedHat Oct 31, 2023

amluto Nov 14, 2023

vrothberg left a comment

vrothberg Nov 1, 2023

umohnani8 commented Nov 6, 2023

amluto commented Nov 14, 2023

packit-as-a-service bot commented Nov 14, 2023

martinpitt commented Nov 15, 2023

edsantiago left a comment

edsantiago Nov 15, 2023

edsantiago Nov 15, 2023

edsantiago Nov 15, 2023

edsantiago Nov 15, 2023

		# Push to a directory, with a relative path, in the OCI format with another tag
		$ podman push myimage oci:directory:tag

		@@ -22,6 +22,8 @@ Note: `:` is a restricted character and cannot be part of the file name.

		podman save [OPTIONS] NAME[:TAG]

		Most or all of podman save's functionality is available, with more flexibility, in [podman-push(1)](podman-push.1.md).

[CI:DOCS] Improve podman-save and podman-push documentation #20537

Are you sure you want to change the base?

[CI:DOCS] Improve podman-save and podman-push documentation #20537

Conversation

amluto commented Oct 30, 2023

Does this PR introduce a user-facing change?

rhatdan Oct 30, 2023 • edited Loading

Choose a reason for hiding this comment

rhatdan commented Oct 30, 2023

openshift-ci bot commented Oct 30, 2023

edsantiago left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amluto commented Oct 30, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vrothberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

umohnani8 commented Nov 6, 2023

amluto commented Nov 14, 2023

packit-as-a-service bot commented Nov 14, 2023

martinpitt commented Nov 15, 2023

edsantiago left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rhatdan Oct 30, 2023 •

edited

Loading