Merge pull request #4442 from ChengyuZhu6/manifest-annotate

manifest: support nerdctl manifest annotate command

Author: AkihiroSuda

cmd/nerdctl/manifest/manifest.go

@@ -35,6 +35,7 @@ func Command() *cobra.Command {
 	cmd.AddCommand(
 		InspectCommand(),
 		CreateCommand(),
+		AnnotateCommand(),
 	)
 
 	return cmd

cmd/nerdctl/manifest/manifest_annotate.go

@@ -0,0 +1,98 @@
+/*
+   Copyright The containerd Authors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package manifest
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/containerd/nerdctl/v2/cmd/nerdctl/completion"
+	"github.com/containerd/nerdctl/v2/cmd/nerdctl/helpers"
+	"github.com/containerd/nerdctl/v2/pkg/api/types"
+	"github.com/containerd/nerdctl/v2/pkg/cmd/manifest"
+)
+
+func AnnotateCommand() *cobra.Command {
+	var cmd = &cobra.Command{
+		Use:               "annotate INDEX/MANIFESTLIST MANIFEST",
+		Short:             "Add additional information to a local image manifest",
+		Args:              cobra.ExactArgs(2),
+		RunE:              annotateAction,
+		ValidArgsFunction: annotateShellComplete,
+		SilenceUsage:      true,
+		SilenceErrors:     true,
+	}
+	cmd.Flags().String("os", "", "Set operating system")
+	cmd.Flags().String("arch", "", "Set architecture")
+	cmd.Flags().String("os-version", "", "Set operating system version")
+	cmd.Flags().String("variant", "", "Set operating system feature")
+	cmd.Flags().StringArray("os-features", []string{}, "Set architecture variant")
+	return cmd
+}
+
+func processAnnotateFlags(cmd *cobra.Command) (types.ManifestAnnotateOptions, error) {
+	globalOptions, err := helpers.ProcessRootCmdFlags(cmd)
+	if err != nil {
+		return types.ManifestAnnotateOptions{}, err
+	}
+
+	os, err := cmd.Flags().GetString("os")
+	if err != nil {
+		return types.ManifestAnnotateOptions{}, err
+	}
+	arch, err := cmd.Flags().GetString("arch")
+	if err != nil {
+		return types.ManifestAnnotateOptions{}, err
+	}
+	osVersion, err := cmd.Flags().GetString("os-version")
+	if err != nil {
+		return types.ManifestAnnotateOptions{}, err
+	}
+	variant, err := cmd.Flags().GetString("variant")
+	if err != nil {
+		return types.ManifestAnnotateOptions{}, err
+	}
+	osFeatures, err := cmd.Flags().GetStringArray("os-features")
+	if err != nil {
+		return types.ManifestAnnotateOptions{}, err
+	}
+
+	return types.ManifestAnnotateOptions{
+		Stdout:     cmd.OutOrStdout(),
+		GOptions:   globalOptions,
+		Os:         os,
+		Arch:       arch,
+		OsVersion:  osVersion,
+		Variant:    variant,
+		OsFeatures: osFeatures,
+	}, nil
+}
+
+func annotateAction(cmd *cobra.Command, args []string) error {
+	annotateOptions, err := processAnnotateFlags(cmd)
+	if err != nil {
+		return err
+	}
+
+	listRef := args[0]
+	manifestRef := args[1]
+
+	return manifest.Annotate(cmd.Context(), listRef, manifestRef, annotateOptions)
+}
+
+func annotateShellComplete(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	return completion.ImageNames(cmd)
+}

cmd/nerdctl/manifest/manifest_annotate_linux_test.go

@@ -0,0 +1,121 @@
+/*
+   Copyright The containerd Authors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package manifest
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/containerd/nerdctl/mod/tigron/test"
+
+	"github.com/containerd/nerdctl/v2/pkg/testutil"
+	"github.com/containerd/nerdctl/v2/pkg/testutil/nerdtest"
+)
+
+func TestManifestAnnotateErrors(t *testing.T) {
+	testCase := nerdtest.Setup()
+	manifestListName := "test-list:v1"
+	manifestName := "example.com/alpine:latest"
+	invalidName := "invalid/name/with/special@chars"
+	testCase.SubTests = []*test.Case{
+		{
+			Description: "too-few-arguments",
+			Command:     test.Command("manifest", "annotate", manifestListName),
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: 1,
+				}
+			},
+		},
+		{
+			Description: "invalid-list-name",
+			Command:     test.Command("manifest", "annotate", invalidName, manifestName),
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: 1,
+					Errors:   []error{errors.New(data.Labels().Get("error"))},
+				}
+			},
+			Data: test.WithLabels(map[string]string{
+				"error": "invalid reference format",
+			}),
+		},
+		{
+			Description: "invalid-manifest-reference",
+			Command:     test.Command("manifest", "annotate", manifestListName, invalidName),
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: 1,
+					Errors:   []error{errors.New(data.Labels().Get("error"))},
+				}
+			},
+			Data: test.WithLabels(map[string]string{
+				"error": "invalid reference format",
+			}),
+		},
+	}
+
+	testCase.Run(t)
+}
+
+func TestManifestAnnotate(t *testing.T) {
+	testCase := nerdtest.Setup()
+	manifestListName := "example.com/test-list-annotate:v1"
+	manifestRef := testutil.GetTestImageWithoutTag("alpine") + "@" + testutil.GetTestImageManifestDigest("alpine", "linux/amd64")
+
+	testCase.SubTests = []*test.Case{
+		{
+			Description: "annotate-non-existent-manifest",
+			Setup: func(data test.Data, helpers test.Helpers) {
+				cmd := helpers.Command("manifest", "create", manifestListName, manifestRef)
+				cmd.Run(&test.Expected{ExitCode: 0})
+			},
+			Command: test.Command("manifest", "annotate", manifestListName, "example.com/fake:0.0"),
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: 1,
+					Errors:   []error{errors.New(data.Labels().Get("error"))},
+				}
+			},
+			Data: test.WithLabels(map[string]string{
+				"error": "manifest for image example.com/fake:0.0 does not exist",
+			}),
+		},
+		{
+			Description: "annotate-success",
+			Setup: func(data test.Data, helpers test.Helpers) {
+				cmd := helpers.Command("manifest", "create", manifestListName+"-success", manifestRef)
+				cmd.Run(&test.Expected{ExitCode: 0})
+			},
+			Command: test.Command("manifest", "annotate",
+				manifestListName+"-success",
+				manifestRef,
+				"--os", "freebsd",
+				"--arch", "arm",
+				"--os-version", "1",
+				"--os-features", "feature1",
+				"--variant", "v7"),
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: 0,
+				}
+			},
+		},
+	}
+
+	testCase.Run(t)
+}

docs/command-reference.md

@@ -52,6 +52,7 @@ It does not necessarily mean that the corresponding features are missing in cont
   - [:nerd_face: nerdctl image encrypt](#nerd_face-nerdctl-image-encrypt)
   - [:nerd_face: nerdctl image decrypt](#nerd_face-nerdctl-image-decrypt)
 - [Manifest management](#manifest-management)
+  - [:whale: nerdctl manifest annotate](#whale-nerdctl-manifest-annotate)
   - [:whale: nerdctl manifest create](#whale-nerdctl-manifest-create)
   - [:whale: nerdctl manifest inspect](#whale-nerdctl-manifest-inspect)
 - [Registry](#registry)
@@ -1040,6 +1041,27 @@ Flags:
 
 ## Manifest management
 
+### :whale: nerdctl manifest annotate
+
+Add additional information to a local image manifest.
+
+Usage: `nerdctl manifest annotate [OPTIONS] INDEX/MANIFESTLIST MANIFEST`
+
+Flags:
+
+- :whale: `--os`: Set operating system (e.g., "linux", "windows", "freebsd")
+- :whale: `--arch`: Set architecture (e.g., "amd64", "arm64", "arm")
+- :whale: `--os-version`: Set operating system version (e.g., "10.0.19041")
+- :whale: `--variant`: Set architecture variant (e.g., "v7", "v8")
+- :whale: `--os-features`: Set operating system features (e.g., "win32k")
+
+Examples:
+
+```bash
+nerdctl manifest annotate myapp:latest alpine@sha256:eafc1edb577d2e9b458664a15f23ea1c370214193226069eb22921169fc7e43f \
+  --os linux --arch arm --variant v7 --os-features feature1,feature2
+```
+
 ### :whale: nerdctl manifest create
 
 Create a local index/manifest list.

pkg/api/types/manifest_types.go

@@ -18,6 +18,17 @@ package types
 
 import "io"
 
+// ManifestAnnotateOptions specifies options for `nerdctl manifest annotate`.
+type ManifestAnnotateOptions struct {
+	Stdout     io.Writer
+	GOptions   GlobalCommandOptions
+	Os         string
+	Arch       string
+	OsVersion  string
+	Variant    string
+	OsFeatures []string
+}
+
 // ManifestCreateOptions specifies options for `nerdctl manifest create`.
 type ManifestCreateOptions struct {
 	Stdout   io.Writer

pkg/cmd/manifest/annotate.go

@@ -0,0 +1,90 @@
+/*
+   Copyright The containerd Authors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package manifest
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+
+	"github.com/containerd/nerdctl/v2/pkg/api/types"
+	"github.com/containerd/nerdctl/v2/pkg/manifeststore"
+	"github.com/containerd/nerdctl/v2/pkg/referenceutil"
+	"github.com/containerd/nerdctl/v2/pkg/store"
+)
+
+func Annotate(ctx context.Context, listRef string, manifestRef string, options types.ManifestAnnotateOptions) error {
+	parsedListRef, err := referenceutil.Parse(listRef)
+	if err != nil {
+		return fmt.Errorf("failed to parse list reference: %w", err)
+	}
+
+	parsedManifestRef, err := referenceutil.Parse(manifestRef)
+	if err != nil {
+		return fmt.Errorf("failed to parse manifest reference: %w", err)
+	}
+
+	manifestStore, err := manifeststore.NewStore(options.GOptions.DataRoot)
+	if err != nil {
+		return fmt.Errorf("failed to create manifest store: %w", err)
+	}
+
+	imageManifest, err := manifestStore.Get(parsedListRef, parsedManifestRef)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			return fmt.Errorf("manifest for image %s does not exist in %s", manifestRef, listRef)
+		}
+		return fmt.Errorf("failed to get manifest: %w", err)
+	}
+
+	if imageManifest.Descriptor.Platform == nil {
+		imageManifest.Descriptor.Platform = new(ocispec.Platform)
+	}
+
+	if options.Os != "" {
+		imageManifest.Descriptor.Platform.OS = options.Os
+	}
+
+	if options.Arch != "" {
+		imageManifest.Descriptor.Platform.Architecture = options.Arch
+	}
+
+	if options.Variant != "" {
+		imageManifest.Descriptor.Platform.Variant = options.Variant
+	}
+
+	if options.OsVersion != "" {
+		imageManifest.Descriptor.Platform.OSVersion = options.OsVersion
+	}
+
+	for _, osFeature := range options.OsFeatures {
+		imageManifest.Descriptor.Platform.OSFeatures = appendIfUnique(imageManifest.Descriptor.Platform.OSFeatures, osFeature)
+	}
+
+	return manifestStore.Save(parsedListRef, parsedManifestRef, imageManifest)
+}
+
+func appendIfUnique(list []string, str string) []string {
+	for _, s := range list {
+		if s == str {
+			return list
+		}
+	}
+	return append(list, str)
+}