From fbe2bd87b0581bdd1651689b9b8a01d0d5116517 Mon Sep 17 00:00:00 2001 From: Valentin Rothberg Date: Mon, 22 Aug 2022 14:53:57 +0200 Subject: [CI:DOCS] elaborate on image lookups of foreign platforms After pulling/creating an image of a foreign platform, Podman will happily use it when looking it up in the local storage and will not pull down the image matching the host platform. As discussed in #12682, the reasoning for it is Docker compatibility and the fact that user already rely on the behavior. While Podman is now emitting a warning when an image is in use not matching the local platform, the documentation was lacking that information. Fixes: #15300 Signed-off-by: Valentin Rothberg --- docs/source/markdown/options/arch.md | 1 + docs/source/markdown/options/platform.md | 1 + docs/source/markdown/podman-build.1.md.in | 17 +++++++++++------ docs/source/markdown/podman-create.1.md.in | 1 + docs/source/markdown/podman-pull.1.md.in | 1 + docs/source/markdown/podman-run.1.md.in | 1 + 6 files changed, 16 insertions(+), 6 deletions(-) (limited to 'docs/source') diff --git a/docs/source/markdown/options/arch.md b/docs/source/markdown/options/arch.md index 005197707..76fb349a0 100644 --- a/docs/source/markdown/options/arch.md +++ b/docs/source/markdown/options/arch.md @@ -1,2 +1,3 @@ #### **--arch**=*ARCH* Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`. +Unless overridden, subsequent lookups of the same image in the local storage will match this architecture, regardless of the host. diff --git a/docs/source/markdown/options/platform.md b/docs/source/markdown/options/platform.md index edfa428ff..b66efdfb2 100644 --- a/docs/source/markdown/options/platform.md +++ b/docs/source/markdown/options/platform.md @@ -2,3 +2,4 @@ Specify the platform for selecting the image. (Conflicts with --arch and --os) The `--platform` option can be used to override the current architecture and operating system. +Unless overridden, subsequent lookups of the same image in the local storage will match this platform, regardless of the host. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index b49beb3bf..350930adf 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -65,8 +65,9 @@ discarded when writing images in Docker formats. Set the architecture of the image to be built, and that of the base image to be pulled, if the build uses one, to the provided value instead of using the -architecture of the build host. (Examples: arm, arm64, 386, amd64, ppc64le, -s390x) +architecture of the build host. Unless overridden, subsequent lookups of the +same image in the local storage will match this architecture, regardless of the +host. (Examples: arm, arm64, 386, amd64, ppc64le, s390x) @@option authfile @@ -454,7 +455,8 @@ do not include `History` information in their images. Set the OS of the image to be built, and that of the base image to be pulled, if the build uses one, instead of using the current operating system of the -build host. +build host. Unless overridden, subsequent lookups of the same image in the +local storage will match this OS, regardless of the host. #### **--os-feature**=*feature* @@ -506,9 +508,12 @@ process. Set the *os/arch* of the built image (and its base image, if your build uses one) to the provided value instead of using the current operating system and -architecture of the host (for example `linux/arm`). If `--platform` is set, -then the values of the `--arch`, `--os`, and `--variant` options will be -overridden. +architecture of the host (for example `linux/arm`). Unless overridden, +subsequent lookups of the same image in the local storage will match this +platform, regardless of the host. + +If `--platform` is set, then the values of the `--arch`, `--os`, and +`--variant` options will be overridden. The `--platform` option can be specified more than once, or given a comma-separated list of values as its argument. When more than one platform is diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 3e6b07225..7ec4fc66f 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -452,6 +452,7 @@ This option conflicts with **--add-host**. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. @@option passwd-entry diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index cf06cc6a8..e3e619de5 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -77,6 +77,7 @@ Print the usage statement. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. @@option platform diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 1c02eafe9..d10520e35 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -465,6 +465,7 @@ This option conflicts with **--add-host**. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. #### **--passwd** -- cgit v1.2.3-54-g00ecf