Add --replace option to podman artifact add command

rhatdan · rhatdan · commit ad1abd38b850 · 2025-09-25T09:06:01.000-04:00
This commit implements the --replace functionality for the artifact add command,
allowing users to replace existing artifacts without having to manually remove
them first.

Changes made:
- Add Replace field to ArtifactAddOptions entity types
- Add --replace CLI flag with validation to prevent conflicts with --append
- Implement replace logic in ABI backend to remove existing artifacts before adding
- Update API handlers and tunnel implementation for podman-remote support
- Add comprehensive documentation and examples to man page
- Add e2e and system BATS tests for --replace functionality
- Fix code formatting in pkg/bindings/artifacts/types_pull_options.go:
  * Reorder imports with proper spacing
  * Fix function declaration spacing
  * Convert spaces to proper tab indentation
  * Remove extraneous blank lines

The --replace option follows the same pattern as other podman replace options
like 'podman container create --replace' and 'podman pod create --replace'.
It gracefully handles cases where no existing artifact exists (no error thrown).

Usage examples:
  podman artifact add --replace quay.io/myimage/artifact:latest /path/to/file
  podman artifact add --replace localhost/test/artifact /tmp/newfile.txt

Fixes: Implements requested --replace functionality for artifact add command
Signed-off-by: Daniel J Walsh &lt;dwalsh@redhat.com&gt;
diff --git a/cmd/podman/artifact/add.go b/cmd/podman/artifact/add.go
@@ -53,6 +53,9 @@ func init() {
 	appendFlagName := "append"
 	flags.BoolVarP(&addOpts.Append, appendFlagName, "a", false, "Append files to an existing artifact")
 
+	replaceFlagName := "replace"
+	flags.BoolVar(&addOpts.Replace, replaceFlagName, false, "Replace an existing artifact")
+
 	fileMIMETypeFlagName := "file-type"
 	flags.StringVarP(&addOpts.FileMIMEType, fileMIMETypeFlagName, "", "", "Set file type to use for the artifact (layer)")
 	_ = addCmd.RegisterFlagCompletionFunc(fileMIMETypeFlagName, completion.AutocompleteNone)
@@ -62,6 +65,10 @@ func add(cmd *cobra.Command, args []string) error {
 	artifactName := args[0]
 	blobs := args[1:]
 
+	if addOpts.Append && addOpts.Replace {
+		return fmt.Errorf("--append and --replace options cannot be used together")
+	}
+
 	annots, err := utils.ParseAnnotations(addOpts.AnnotationsCLI)
 	if err != nil {
 		return err
@@ -72,6 +79,7 @@ func add(cmd *cobra.Command, args []string) error {
 		ArtifactMIMEType: addOpts.ArtifactMIMEType,
 		Append:           addOpts.Append,
 		FileMIMEType:     addOpts.FileMIMEType,
+		Replace:          addOpts.Replace,
 	}
 
 	artifactBlobs := make([]entities.ArtifactBlob, 0, len(blobs))
diff --git a/docs/source/markdown/podman-artifact-add.1.md.in b/docs/source/markdown/podman-artifact-add.1.md.in
@@ -1,73 +1,73 @@
 % podman-artifact-add 1
 
 ## NAME
-podman\-artifact\-add - Add an OCI artifact to the local store
+podman\-artifact\-add - Add an OCI artifact to local artifact store
 
 ## SYNOPSIS
-**podman artifact add** *name* *file* [*file*]...
+**podman artifact add** [*options*] *artifact-name* *file* [*file* ...]
 
 ## DESCRIPTION
 
 Add an OCI artifact to the local store from the local filesystem.  You must
 provide at least one file to create the artifact, but several can also be
 added.
 
+Artifacts automatically include a creation timestamp in the
+`org.opencontainers.image.created` annotation using RFC3339Nano format. When using
+the `--append` option, the original creation timestamp is preserved.
+
 
 ## OPTIONS
 
 @@option annotation.manifest
 
-Note: Set annotations for each file being added.
+@@option arch
 
-#### **--append**, **-a**
+#### **--append**
 
-Append files to an existing artifact. This option cannot be used with the **--type** option.
+Add files to an existing OCI Artifact. The default is **false**.
 
-#### **--file-type**
+#### **--artifact-type**
 
-Set the media type of the artifact file instead of allowing detection to determine the type
+Set the MIME type for the artifact config. This will be set in the media type of the artifact manifest. Setting the type for an artifact makes it easier to search and filter on the artifact type.
 
-#### **--help**
+#### **--file-type**
 
-Print usage statement.
+Set the MIME type for each of the added files. The default of the filesystem adds files as (application/octet-stream).
 
-#### **--type**
+#### **--replace**
 
-Set a type for the artifact being added.
+If an artifact with the same name already exists, replace and remove it. The default is **false**.
+This option cannot be used with the **--append** option.
 
 ## EXAMPLES
 
-Add a single file to an artifact
+Add artifact to the store with path:
 
 ```
-$ podman artifact add quay.io/myartifact/myml:latest /tmp/foobar.ml
-0fe1488ecdef8cc4093e11a55bc048d9fc3e13a4ba846efd24b5a715006c95b3
+$ podman artifact add quay.io/myimage/myartifact:latest /home/user/model.gguf
 ```
 
-Add multiple files to an artifact
-```
-$ podman artifact add quay.io/myartifact/myml:latest /tmp/foobar1.ml /tmp/foobar2.ml
-1487acae11b5a30948c50762882036b41ac91a7b9514be8012d98015c95ddb78
-```
+Add OCI artifact to the store with type:
 
-Set an annotation for an artifact
 ```
-$ podman artifact add --annotation date=2025-01-30 quay.io/myartifact/myml:latest /tmp/foobar1.ml
+$ podman artifact add --artifact-type application/com.example.ai --file-type application/vnd.gguf quay.io/myimage/myartifact:latest /home/user/model.gguf
 ```
 
-Append a file to an existing artifact
+Replace an existing artifact with the same name
+
 ```
-$ podman artifact add --append quay.io/myartifact/tarballs:latest /tmp/foobar.tar.gz
+$ podman artifact add --replace quay.io/myartifact/myml:latest /tmp/newfoobar.ml
 ```
 
-Override the media type of the artifact being added
+Add files to an existing OCI artifact
+
 ```
-$ podman artifact add --file-type text/yaml quay.io/myartifact/descriptors:latest /tmp/info.yaml
+$ podman artifact add --append quay.io/myimage/myartifact:latest /home/user/config.yaml
 ```
 
-
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-artifact(1)](podman-artifact.1.md)**
 
 ## HISTORY
-Jan 2025, Originally compiled by Brent Baude <bbaude@redhat.com>
+Sept 2024, Originally compiled by Brent Baude <bbaude@redhat.com>
diff --git a/docs/source/markdown/podman-artifact-inspect.1.md b/docs/source/markdown/podman-artifact-inspect.1.md
@@ -8,11 +8,16 @@ podman\-artifact\-inspect - Inspect an OCI artifact
 
 ## DESCRIPTION
 
-Inspect an artifact in the local store.  The artifact can be referred to with either:
+Inspect an artifact in the local store and output the results in JSON format.
+The artifact can be referred to with either:
 
 1. Fully qualified artifact name
 2. Full or partial digest of the artifact's manifest
 
+The inspect output includes the artifact manifest with annotations. All artifacts
+automatically include a creation timestamp in the `org.opencontainers.image.created`
+annotation using RFC3339Nano format, showing when the artifact was initially created.
+
 ## OPTIONS
 
 #### **--help**
diff --git a/pkg/api/handlers/libpod/artifacts.go b/pkg/api/handlers/libpod/artifacts.go
@@ -217,6 +217,7 @@ func AddArtifact(w http.ResponseWriter, r *http.Request) {
 		Annotations      []string `schema:"annotations"`
 		ArtifactMIMEType string   `schema:"artifactMIMEType"`
 		Append           bool     `schema:"append"`
+		Replace          bool     `schema:"replace"`
 	}{}
 
 	if err := decoder.Decode(&query, r.URL.Query()); err != nil {
@@ -240,6 +241,7 @@ func AddArtifact(w http.ResponseWriter, r *http.Request) {
 		Annotations:      annotations,
 		ArtifactMIMEType: query.ArtifactMIMEType,
 		FileMIMEType:     query.FileMIMEType,
+		Replace:          query.Replace,
 	}
 
 	artifactBlobs := []entities.ArtifactBlob{{
diff --git a/pkg/api/server/register_artifacts.go b/pkg/api/server/register_artifacts.go
@@ -187,6 +187,11 @@ func (s *APIServer) registerArtifactHandlers(r *mux.Router) error {
 	//     description: Append files to an existing artifact
 	//     type: boolean
 	//     default: false
+	//   - name: replace
+	//     in: query
+	//     description: Replace an existing artifact with the same name
+	//     type: boolean
+	//     default: false
 	//   - name: inputStream
 	//     in: body
 	//     description: Binary stream of the file to add to an artifact
diff --git a/pkg/bindings/artifacts/types.go b/pkg/bindings/artifacts/types.go
@@ -62,6 +62,7 @@ type AddOptions struct {
 	ArtifactMIMEType *string
 	Append           *bool
 	FileMIMEType     *string
+	Replace          *bool
 }
 
 // ExtractOptions
diff --git a/pkg/bindings/artifacts/types_add_options.go b/pkg/bindings/artifacts/types_add_options.go
diff --git a/pkg/domain/entities/artifact.go b/pkg/domain/entities/artifact.go
@@ -13,6 +13,7 @@ type ArtifactAddOptions struct {
 	ArtifactMIMEType string
 	Append           bool
 	FileMIMEType     string
+	Replace          bool
 }
 
 type ArtifactAddReport = entitiesTypes.ArtifactAddReport
diff --git a/pkg/domain/infra/abi/artifact.go b/pkg/domain/infra/abi/artifact.go
@@ -203,11 +203,17 @@ func (ir *ImageEngine) ArtifactAdd(ctx context.Context, name string, artifactBlo
 		return nil, err
 	}
 
+	// If replace is true, try to remove existing artifact (ignore errors if it doesn't exist)
+	if opts.Replace {
+		_, _ = artStore.Remove(ctx, name)
+	}
+
 	addOptions := types.AddOptions{
 		Annotations:      opts.Annotations,
 		ArtifactMIMEType: opts.ArtifactMIMEType,
 		Append:           opts.Append,
 		FileMIMEType:     opts.FileMIMEType,
+		Replace:          opts.Replace,
 	}
 
 	artifactDigest, err := artStore.Add(ctx, name, artifactBlobs, &addOptions)
diff --git a/pkg/domain/infra/tunnel/artifact.go b/pkg/domain/infra/tunnel/artifact.go
@@ -88,6 +88,7 @@ func (ir *ImageEngine) ArtifactAdd(_ context.Context, name string, artifactBlob
 		Append:           &opts.Append,
 		ArtifactMIMEType: &opts.ArtifactMIMEType,
 		FileMIMEType:     &opts.FileMIMEType,
+		Replace:          &opts.Replace,
 	}
 
 	for k, v := range opts.Annotations {
diff --git a/pkg/libartifact/store/store.go b/pkg/libartifact/store/store.go
@@ -253,13 +253,21 @@ func (as ArtifactStore) Add(ctx context.Context, dest string, artifactBlobs []en
 		if err == nil {
 			return nil, fmt.Errorf("%s: %w", dest, libartTypes.ErrArtifactAlreadyExists)
 		}
+
+		// Set creation timestamp and other annotations
+		annotations := make(map[string]string)
+		if options.Annotations != nil {
+			annotations = maps.Clone(options.Annotations)
+		}
+		annotations[specV1.AnnotationCreated] = time.Now().UTC().Format(time.RFC3339Nano)
+
 		artifactManifest = specV1.Manifest{
 			Versioned:    specs.Versioned{SchemaVersion: ManifestSchemaVersion},
 			MediaType:    specV1.MediaTypeImageManifest,
 			ArtifactType: options.ArtifactMIMEType,
-			// TODO This should probably be configurable once the CLI is capable
-			Config: specV1.DescriptorEmptyJSON,
-			Layers: make([]specV1.Descriptor, 0),
+			Config:       specV1.DescriptorEmptyJSON,
+			Layers:       make([]specV1.Descriptor, 0),
+			Annotations:  annotations,
 		}
 	} else {
 		artifact, _, err := artifacts.GetByNameOrDigest(dest)
diff --git a/pkg/libartifact/types/config.go b/pkg/libartifact/types/config.go
@@ -13,6 +13,8 @@ type AddOptions struct {
 	// FileType describes the media type for the layer.  It is an override
 	// for the standard detection
 	FileMIMEType string `json:",omitempty"`
+	// Replace option removes existing artifact before adding new one
+	Replace bool `json:",omitempty"`
 }
 
 // FilterBlobOptions options used to filter for a single blob in an artifact
diff --git a/test/apiv2/python/rest_api/test_v2_0_0_artifact.py b/test/apiv2/python/rest_api/test_v2_0_0_artifact.py
@@ -43,6 +43,72 @@ def test_add(self):
         # Assert blob media type fallback detection is working
         self.assertEqual(artifact_layer["mediaType"], "application/octet-stream")
 
+    def test_add_with_replace(self):
+        ARTIFACT_NAME = "quay.io/myimage/myartifact:latest"
+
+        # Create first artifact
+        file1 = ArtifactFile()
+        parameters1: dict[str, str | list[str]] = {
+            "name": ARTIFACT_NAME,
+            "fileName": file1.name,
+        }
+
+        artifact1 = Artifact(self.uri(""), ARTIFACT_NAME, parameters1, file1)
+        add_response1 = artifact1.add()
+        self.assertEqual(add_response1.status_code, 201, add_response1.text)
+
+        original_digest = add_response1.json()["ArtifactDigest"]
+
+        # Create replacement artifact with replace=true
+        file2 = ArtifactFile()
+        parameters2: dict[str, str | list[str]] = {
+            "name": ARTIFACT_NAME,
+            "fileName": file2.name,
+            "replace": "true",
+        }
+
+        artifact2 = Artifact(self.uri(""), ARTIFACT_NAME, parameters2, file2)
+        add_response2 = artifact2.add()
+        self.assertEqual(add_response2.status_code, 201, add_response2.text)
+
+        new_digest = add_response2.json()["ArtifactDigest"]
+
+        # Verify artifacts were replaced (different digests)
+        self.assertNotEqual(original_digest, new_digest)
+
+        # Verify artifact exists and has the new content
+        inspect_response = artifact2.do_artifact_inspect_request()
+        self.assertEqual(inspect_response.status_code, 200)
+
+        inspect_json = inspect_response.json()
+        artifact_layer = inspect_json["Manifest"]["layers"][0]
+
+        # Should have only one layer (replaced, not appended)
+        self.assertEqual(len(inspect_json["Manifest"]["layers"]), 1)
+
+        # Verify it's the second file's content
+        self.assertEqual(artifact_layer["size"], file2.size)
+        self.assertEqual(
+            artifact_layer["annotations"]["org.opencontainers.image.title"], file2.name
+        )
+
+    def test_add_with_replace_conflict_with_append(self):
+        ARTIFACT_NAME = "quay.io/myimage/myartifact:latest"
+        file = ArtifactFile()
+        parameters: dict[str, str | list[str]] = {
+            "name": ARTIFACT_NAME,
+            "fileName": file.name,
+            "append": "true",
+            "replace": "true",
+        }
+
+        artifact = Artifact(self.uri(""), ARTIFACT_NAME, parameters, file)
+        add_response = artifact.add()
+
+        # Should fail with bad request when both append and replace are true
+        self.assertEqual(add_response.status_code, 400, add_response.text)
+        self.assertIn("append and replace options cannot be used together", add_response.text.lower())
+
     def test_add_with_append(self):
         ARTIFACT_NAME = "quay.io/myimage/myartifact:latest"
         file = ArtifactFile(name="test_file_2")
diff --git a/test/e2e/artifact_created_test.go b/test/e2e/artifact_created_test.go
diff --git a/test/e2e/artifact_test.go b/test/e2e/artifact_test.go
diff --git a/test/system/700-artifact.bats b/test/system/700-artifact.bats
diff --git a/test/system/701-artifact-created.bats b/test/system/701-artifact-created.bats

Original file line number	Diff line number	Diff line change
`@@ -62,6 +62,7 @@ type AddOptions struct {`
`62`	`62`	`ArtifactMIMEType *string`
`63`	`63`	`Append *bool`
`64`	`64`	`FileMIMEType *string`
	`65`	`+ Replace *bool`
`65`	`66`	`}`
`66`	`67`
`67`	`68`	`// ExtractOptions`
Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,7 @@ type ArtifactAddOptions struct {`
`13`	`13`	`ArtifactMIMEType string`
`14`	`14`	`Append bool`
`15`	`15`	`FileMIMEType string`
	`16`	`+ Replace bool`
`16`	`17`	`}`
`17`	`18`
`18`	`19`	`type ArtifactAddReport = entitiesTypes.ArtifactAddReport`
Original file line number	Diff line number	Diff line change
`@@ -88,6 +88,7 @@ func (ir *ImageEngine) ArtifactAdd(_ context.Context, name string, artifactBlob`
`88`	`88`	`Append: &opts.Append,`
`89`	`89`	`ArtifactMIMEType: &opts.ArtifactMIMEType,`
`90`	`90`	`FileMIMEType: &opts.FileMIMEType,`
	`91`	`+ Replace: &opts.Replace,`
`91`	`92`	`}`
`92`	`93`
`93`	`94`	`for k, v := range opts.Annotations {`