Add --replace option to podman artifact add command

rhatdan · rhatdan · commit 17dcba44166a · 2025-10-02T08:16:58.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(_ *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(_ *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,10 +1,10 @@
 % 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
 
@@ -35,6 +35,11 @@ Set the media type of the artifact file instead of allowing detection to determi
 
 Print usage statement.
 
+#### **--replace**
+
+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.
+
 #### **--type**
 
 Set a type for the artifact being added.
@@ -48,25 +53,29 @@ $ podman artifact add quay.io/myartifact/myml:latest /tmp/foobar.ml
 0fe1488ecdef8cc4093e11a55bc048d9fc3e13a4ba846efd24b5a715006c95b3
 ```
 
-Add multiple files to an artifact
+Add OCI artifact to the store with type:
+
 ```
-$ podman artifact add quay.io/myartifact/myml:latest /tmp/foobar1.ml /tmp/foobar2.ml
-1487acae11b5a30948c50762882036b41ac91a7b9514be8012d98015c95ddb78
+$ podman artifact add --artifact-type application/com.example.ai --file-type application/vnd.gguf quay.io/myimage/myartifact:latest /home/user/model.gguf
 ```
 
-Set an annotation for an artifact
+Replace an existing artifact with the same name
+
 ```
-$ podman artifact add --annotation date=2025-01-30 quay.io/myartifact/myml:latest /tmp/foobar1.ml
+$ podman artifact add quay.io/myartifact/myml:latest /tmp/foobar.ml
+0fe1488ecdef8cc4093e11a55bc048d9fc3e13a4ba846efd24b5a715006c95b3
 ```
 
-Append a file to an existing artifact
+Add multiple files to an artifact
 ```
-$ podman artifact add --append quay.io/myartifact/tarballs:latest /tmp/foobar.tar.gz
+$ podman artifact add quay.io/myartifact/myml:latest /tmp/foobar1.ml /tmp/foobar2.ml
+1487acae11b5a30948c50762882036b41ac91a7b9514be8012d98015c95ddb78
 ```
 
-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
 ```
 
 
diff --git a/docs/source/markdown/podman-artifact.1.md b/docs/source/markdown/podman-artifact.1.md
@@ -17,7 +17,7 @@ from its local "artifact store".
 
 | Command | Man Page                                                   | Description                                                  |
 |---------|------------------------------------------------------------|--------------------------------------------------------------|
-| add     | [podman-artifact-add(1)](podman-artifact-add.1.md)         | Add an OCI artifact to the local store                       |
+| add     | [podman-artifact-add(1)](podman-artifact-add.1.md)         | Add an OCI artifact to local artifact store              |
 | extract | [podman-artifact-extract(1)](podman-artifact-extract.1.md) | Extract an OCI artifact to a local path                      |
 | inspect | [podman-artifact-inspect(1)](podman-artifact-inspect.1.md) | Inspect an OCI artifact                                      |
 | ls      | [podman-artifact-ls(1)](podman-artifact-ls.1.md)           | List OCI artifacts in local store                            |
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
@@ -4,6 +4,7 @@ package abi
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -12,6 +13,7 @@ import (
 	"github.com/containers/podman/v5/pkg/domain/entities"
 	"github.com/containers/podman/v5/pkg/libartifact/types"
 	"github.com/opencontainers/go-digest"
+	"github.com/sirupsen/logrus"
 	"go.podman.io/common/libimage"
 )
 
@@ -203,11 +205,19 @@ 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 {
+		if _, err = artStore.Remove(ctx, name); err != nil && !errors.Is(err, types.ErrArtifactNotExist) {
+			logrus.Debugf("Artifact %q removal failed: %s", name, err)
+		}
+	}
+
 	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/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/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 {`