From 2bbed8f2009523cbdd3fcee3a09a4397049b1b51 Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Thu, 15 Feb 2024 13:52:32 -0500 Subject: [PATCH] Add man page content for artifacts Signed-off-by: Daniel J Walsh --- .../markdown/options/annotation.manifest.md | 2 +- docs/source/markdown/options/features.md | 2 +- docs/source/markdown/options/os-version.md | 2 +- .../markdown/podman-manifest-add.1.md.in | 61 +++++++++++++++++-- .../markdown/podman-manifest-annotate.1.md.in | 26 +++++--- .../markdown/podman-manifest-create.1.md.in | 4 ++ docs/source/markdown/podman-manifest.1.md | 20 +++--- 7 files changed, 92 insertions(+), 25 deletions(-) diff --git a/docs/source/markdown/options/annotation.manifest.md b/docs/source/markdown/options/annotation.manifest.md index 36914df424..472fc40b40 100644 --- a/docs/source/markdown/options/annotation.manifest.md +++ b/docs/source/markdown/options/annotation.manifest.md @@ -4,4 +4,4 @@ ####> are applicable to all of those. #### **--annotation**=*annotation=value* -Set an annotation on the entry for the image. +Set an annotation on the entry for the specified image or artifact. diff --git a/docs/source/markdown/options/features.md b/docs/source/markdown/options/features.md index 05540558f4..0ee84217a1 100644 --- a/docs/source/markdown/options/features.md +++ b/docs/source/markdown/options/features.md @@ -2,7 +2,7 @@ ####> podman manifest add, manifest annotate ####> If file is edited, make sure the changes ####> are applicable to all of those. -#### **--features** +#### **--features**=*feature* Specify the features list which the list or index records as requirements for the image. This option is rarely used. diff --git a/docs/source/markdown/options/os-version.md b/docs/source/markdown/options/os-version.md index b6d83544d0..1121ae957b 100644 --- a/docs/source/markdown/options/os-version.md +++ b/docs/source/markdown/options/os-version.md @@ -2,7 +2,7 @@ ####> podman manifest add, manifest annotate ####> If file is edited, make sure the changes ####> are applicable to all of those. -#### **--os-version** +#### **--os-version**=*version* Specify the OS version which the list or index records as a requirement for the image. This option is rarely used. diff --git a/docs/source/markdown/podman-manifest-add.1.md.in b/docs/source/markdown/podman-manifest-add.1.md.in index 4b4012b8e2..4c9e6c09de 100644 --- a/docs/source/markdown/podman-manifest-add.1.md.in +++ b/docs/source/markdown/podman-manifest-add.1.md.in @@ -1,16 +1,18 @@ % podman-manifest-add 1 ## NAME -podman\-manifest\-add - Add an image to a manifest list or image index +podman\-manifest\-add - Add an image or artifact to a manifest list or image index ## SYNOPSIS -**podman manifest add** [*options*] *listnameorindexname* [*transport*]:*imagename* +**podman manifest add** [*options*] *listnameorindexname* [*transport*]:*imagename* *imageorartifactname* [...] ## DESCRIPTION -Adds the specified image to the specified manifest list or image index. +Adds the specified image to the specified manifest list or image index, or +creates an artifact manifest and adds it to the specified image index. ## RETURN VALUE + The list image's ID. ## OPTIONS @@ -24,13 +26,62 @@ from such a list or index is added to the list or index. Combining @@option annotation.manifest -#### **--arch** +#### **--arch**=*architecture* Override the architecture which the list or index records as a requirement for the image. If *imageName* refers to a manifest list or image index, the architecture information is retrieved from it. Otherwise, it is retrieved from the image's configuration information. +#### **--artifact** + +Create an artifact manifest and add it to the image index. Arguments after the +index name will be interpreted as file names rather than as image references. +In most scenarios, the **--artifact-type** option should also be specified. + +#### **--artifact-config**=*path* + +When creating an artifact manifest and adding it to the image index, use the +specified file's contents as the configuration blob in the artifact manifest. +In most scenarios, leaving the default value, which signifies an empty +configuration, unchanged, is the preferred option. + +#### **--artifact-config-type**=*type* + +When creating an artifact manifest and adding it to the image index, use the +specified MIME type as the `mediaType` associated with the configuration blob +in the artifact manifest. In most scenarios, leaving the default value, which +signifies either an empty configuration or the standard OCI configuration type, +unchanged, is the preferred option. + +#### **--artifact-exclude-titles** + +When creating an artifact manifest and adding it to the image index, do not +set "org.opencontainers.image.title" annotations equal to the file's basename +for each file added to the artifact manifest. Tools which retrieve artifacts +from a registry may use these values to choose names for files when saving +artifacts to disk, so this option is not recommended unless it is required +for interoperability with a particular registry. + +#### **--artifact-layer-type**=*type* + +When creating an artifact manifest and adding it to the image index, use the +specified MIME type as the `mediaType` associated with the files' contents. If +not specified, guesses based on either the files names or their contents will +be made and used, but the option should be specified if certainty is needed. + +#### **--artifact-subject**=*imageName* + +When creating an artifact manifest and adding it to the image index, set the +*subject* field in the artifact manifest to mark the artifact manifest as being +associated with the specified image in some way. An artifact manifest can only +be associated with, at most, one subject. + +#### **--artifact-type**=*type* + +When creating an artifact manifest, use the specified MIME type as the +manifest's `artifactType` value instead of the less informative default value. + @@option authfile @@option cert-dir @@ -39,7 +90,7 @@ retrieved from the image's configuration information. @@option features -#### **--os** +#### **--os**=*OS* Override the OS which the list or index records as a requirement for the image. If *imagename* refers to a manifest list or image index, the OS information diff --git a/docs/source/markdown/podman-manifest-annotate.1.md.in b/docs/source/markdown/podman-manifest-annotate.1.md.in index 7af709bae3..38a186aeee 100644 --- a/docs/source/markdown/podman-manifest-annotate.1.md.in +++ b/docs/source/markdown/podman-manifest-annotate.1.md.in @@ -1,41 +1,53 @@ % podman-manifest-annotate 1 ## NAME -podman\-manifest\-annotate - Add or update information about an entry in a manifest list or image index +podman\-manifest\-annotate - Add and update information about an image or artifact in a manifest list or image index ## SYNOPSIS -**podman manifest annotate** [*options*] *listnameorindexname* *imagemanifestdigest* +**podman manifest annotate** [*options*] *listnameorindexname* *imagemanifestdigestorimageorartifactname* ## DESCRIPTION -Adds or updates information about an image included in a manifest list or image index. +Adds or updates information about an image or artifact included in a manifest list or image index. ## OPTIONS @@option annotation.manifest +If **--index** is also specified, sets the annotation on the entire image index. -#### **--arch** +#### **--arch**=*architecture* Override the architecture which the list or index records as a requirement for the image. This is usually automatically retrieved from the image's configuration information, so it is rarely necessary to use this option. - @@option features -#### **--os** +#### **--index** + +Treats arguments to the **--annotation** option as annotation values to be set +on the image index itself rather than on an entry in the image index. Implied +for **--subject**. + +#### **--os**=*OS* Override the OS which the list or index records as a requirement for the image. This is usually automatically retrieved from the image's configuration information, so it is rarely necessary to use this option. -#### **--os-features** +#### **--os-features**=*feature* Specify the OS features list which the list or index records as requirements for the image. This option is rarely used. @@option os-version +#### **--subject**=*imageName* + +Set the *subject* field in the image index to mark the image index as being +associated with the specified image in some way. An image index can only be +associated with, at most, one subject. + @@option variant.manifest ## EXAMPLE diff --git a/docs/source/markdown/podman-manifest-create.1.md.in b/docs/source/markdown/podman-manifest-create.1.md.in index 3d9e620970..9944357c40 100644 --- a/docs/source/markdown/podman-manifest-create.1.md.in +++ b/docs/source/markdown/podman-manifest-create.1.md.in @@ -28,6 +28,10 @@ If a manifest list named *listnameorindexname* already exists, modify the preexisting list instead of exiting with an error. The contents of *listnameorindexname* are not modified if no *imagename*s are given. +#### **--annotation**=*value* + +Set an annotation on the newly-created image index. + @@option tls-verify ## EXAMPLES diff --git a/docs/source/markdown/podman-manifest.1.md b/docs/source/markdown/podman-manifest.1.md index 26248a4c4f..8b6ef489ad 100644 --- a/docs/source/markdown/podman-manifest.1.md +++ b/docs/source/markdown/podman-manifest.1.md @@ -13,16 +13,16 @@ The `podman manifest` command provides subcommands which can be used to: ## SUBCOMMANDS -| Command | Man Page | Description | -| -------- | ------------------------------------------------------------ | --------------------------------------------------------------------------- | -| add | [podman-manifest-add(1)](podman-manifest-add.1.md) | Add an image to a manifest list or image index. | -| annotate | [podman-manifest-annotate(1)](podman-manifest-annotate.1.md) | Add or update information about an entry in a manifest list or image index. | -| create | [podman-manifest-create(1)](podman-manifest-create.1.md) | Create a manifest list or image index. | -| exists | [podman-manifest-exists(1)](podman-manifest-exists.1.md) | Check if the given manifest list exists in local storage | -| inspect | [podman-manifest-inspect(1)](podman-manifest-inspect.1.md) | Display a manifest list or image index. | -| push | [podman-manifest-push(1)](podman-manifest-push.1.md) | Push a manifest list or image index to a registry. | -| remove | [podman-manifest-remove(1)](podman-manifest-remove.1.md) | Remove an image from a manifest list or image index. | -| rm | [podman-manifest-rm(1)](podman-manifest-rm.1.md) | Remove manifest list or image index from local storage. | +| Command | Man Page | Description | +| -------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | +| add | [podman-manifest-add(1)](podman-manifest-add.1.md) | Add an image or artifact to a manifest list or image index. | +| annotate | [podman-manifest-annotate(1)](podman-manifest-annotate.1.md) | Add and update information about an image or artifact in a manifest list or image index. | +| create | [podman-manifest-create(1)](podman-manifest-create.1.md) | Create a manifest list or image index. | +| exists | [podman-manifest-exists(1)](podman-manifest-exists.1.md) | Check if the given manifest list exists in local storage | +| inspect | [podman-manifest-inspect(1)](podman-manifest-inspect.1.md) | Display a manifest list or image index. | +| push | [podman-manifest-push(1)](podman-manifest-push.1.md) | Push a manifest list or image index to a registry. | +| remove | [podman-manifest-remove(1)](podman-manifest-remove.1.md) | Remove an image from a manifest list or image index. | +| rm | [podman-manifest-rm(1)](podman-manifest-rm.1.md) | Remove manifest list or image index from local storage. | ## EXAMPLES