checkpoint: support nerdctl checkpoint create command

- Create checkpoints from running containers using containerd APIs
- Support both leave-running and exit modes via --leave-running flag
- Configurable checkpoint directory via --checkpoint-dir flag

Signed-off-by: ChengyuZhu6 <[email protected]>

Author: ChengyuZhu6

cmd/nerdctl/checkpoint/checkpoint.go

@@ -0,0 +1,40 @@
+/*
+   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 checkpoint
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/containerd/nerdctl/v2/cmd/nerdctl/helpers"
+)
+
+func Command() *cobra.Command {
+	cmd := &cobra.Command{
+		Annotations:   map[string]string{helpers.Category: helpers.Management},
+		Use:           "checkpoint",
+		Short:         "Manage checkpoints.",
+		RunE:          helpers.UnknownSubcommandAction,
+		SilenceUsage:  true,
+		SilenceErrors: true,
+	}
+
+	cmd.AddCommand(
+		CreateCommand(),
+	)
+
+	return cmd
+}

cmd/nerdctl/checkpoint/checkpoint_create.go

@@ -0,0 +1,93 @@
+/*
+   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 checkpoint
+
+import (
+	"path/filepath"
+
+	"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/clientutil"
+	"github.com/containerd/nerdctl/v2/pkg/cmd/checkpoint"
+)
+
+func CreateCommand() *cobra.Command {
+	var cmd = &cobra.Command{
+		Use:               "create [OPTIONS] CONTAINER CHECKPOINT",
+		Short:             "Create a checkpoint from a running container",
+		Args:              cobra.ExactArgs(2),
+		RunE:              createAction,
+		ValidArgsFunction: createShellComplete,
+		SilenceUsage:      true,
+		SilenceErrors:     true,
+	}
+	cmd.Flags().Bool("leave-running", false, "Leave the container running after checkpointing")
+	cmd.Flags().String("checkpoint-dir", "", "Checkpoint directory")
+	return cmd
+}
+
+func processCreateFlags(cmd *cobra.Command) (types.CheckpointCreateOptions, error) {
+	globalOptions, err := helpers.ProcessRootCmdFlags(cmd)
+	if err != nil {
+		return types.CheckpointCreateOptions{}, err
+	}
+
+	leaveRunning, err := cmd.Flags().GetBool("leave-running")
+	if err != nil {
+		return types.CheckpointCreateOptions{}, err
+	}
+	checkpointDir, err := cmd.Flags().GetString("checkpoint-dir")
+	if err != nil {
+		return types.CheckpointCreateOptions{}, err
+	}
+	if checkpointDir == "" {
+		checkpointDir = filepath.Join(globalOptions.DataRoot, "checkpoints")
+	}
+
+	return types.CheckpointCreateOptions{
+		Stdout:        cmd.OutOrStdout(),
+		GOptions:      globalOptions,
+		LeaveRunning:  leaveRunning,
+		CheckpointDir: checkpointDir,
+	}, nil
+}
+
+func createAction(cmd *cobra.Command, args []string) error {
+	createOptions, err := processCreateFlags(cmd)
+	if err != nil {
+		return err
+	}
+	client, ctx, cancel, err := clientutil.NewClient(cmd.Context(), createOptions.GOptions.Namespace, createOptions.GOptions.Address)
+	if err != nil {
+		return err
+	}
+	defer cancel()
+
+	err = checkpoint.Create(ctx, client, args[0], args[1], createOptions)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func createShellComplete(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	return completion.ImageNames(cmd)
+}

cmd/nerdctl/main.go

@@ -31,6 +31,7 @@ import (
 	"github.com/containerd/log"
 
 	"github.com/containerd/nerdctl/v2/cmd/nerdctl/builder"
+	"github.com/containerd/nerdctl/v2/cmd/nerdctl/checkpoint"
 	"github.com/containerd/nerdctl/v2/cmd/nerdctl/completion"
 	"github.com/containerd/nerdctl/v2/cmd/nerdctl/compose"
 	"github.com/containerd/nerdctl/v2/cmd/nerdctl/container"
@@ -350,6 +351,9 @@ Config file ($NERDCTL_TOML): %s
 
 		// Manifest
 		manifest.Command(),
+
+		// Checkpoint
+		checkpoint.Command(),
 	)
 	addApparmorCommand(rootCmd)
 	container.AddCpCommand(rootCmd)

pkg/api/types/checkpoint_types.go

@@ -0,0 +1,29 @@
+/*
+   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 types
+
+import "io"
+
+// CheckpointCreateOptions specifies options for `nerdctl checkpoint create`.
+type CheckpointCreateOptions struct {
+	Stdout   io.Writer
+	GOptions GlobalCommandOptions
+	// Leave the container running after checkpointing
+	LeaveRunning bool
+	// Checkpoint directory
+	CheckpointDir string
+}

pkg/checkpointutil/checkpointutil.go

@@ -0,0 +1,48 @@
+/*
+   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 checkpointutil
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+func GetCheckpointDir(checkpointDir, checkpointID, containerID string, create bool) (string, error) {
+	checkpointAbsDir := filepath.Join(checkpointDir, checkpointID)
+	stat, err := os.Stat(checkpointAbsDir)
+	if create {
+		switch {
+		case err == nil && stat.IsDir():
+			err = fmt.Errorf("checkpoint with name %s already exists for container %s", checkpointID, containerID)
+		case err != nil && os.IsNotExist(err):
+			err = os.MkdirAll(checkpointAbsDir, 0o700)
+		case err != nil:
+			err = fmt.Errorf("%s exists and is not a directory", checkpointAbsDir)
+		}
+	} else {
+		switch {
+		case err != nil:
+			err = fmt.Errorf("checkpoint %s does not exist for container %s", checkpointID, containerID)
+		case stat.IsDir():
+			err = nil
+		default:
+			err = fmt.Errorf("%s exists and is not a directory", checkpointAbsDir)
+		}
+	}
+	return checkpointAbsDir, err
+}

pkg/cmd/checkpoint/create.go

@@ -0,0 +1,135 @@
+/*
+   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 checkpoint
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+
+	"github.com/containerd/containerd/api/types/runc/options"
+	containerd "github.com/containerd/containerd/v2/client"
+	"github.com/containerd/containerd/v2/core/content"
+	"github.com/containerd/containerd/v2/core/images"
+	"github.com/containerd/containerd/v2/pkg/archive"
+	"github.com/containerd/containerd/v2/plugins"
+
+	"github.com/containerd/nerdctl/v2/pkg/api/types"
+	"github.com/containerd/nerdctl/v2/pkg/checkpointutil"
+	"github.com/containerd/nerdctl/v2/pkg/idutil/containerwalker"
+)
+
+func Create(ctx context.Context, client *containerd.Client, containerID string, checkpointName string, options types.CheckpointCreateOptions) error {
+	var container containerd.Container
+
+	walker := &containerwalker.ContainerWalker{
+		Client: client,
+		OnFound: func(ctx context.Context, found containerwalker.Found) error {
+			if found.MatchCount > 1 {
+				return fmt.Errorf("multiple containers found with provided prefix: %s", found.Req)
+			}
+			container = found.Container
+			return nil
+		},
+	}
+
+	n, err := walker.Walk(ctx, containerID)
+	if err != nil {
+		return err
+	} else if n == 0 {
+		return fmt.Errorf("error creating checkpoint for container: %s, no such container", containerID)
+	}
+
+	info, err := container.Info(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to get info for container %q: %w", containerID, err)
+	}
+
+	task, err := container.Task(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("failed to get task for container %q: %w", containerID, err)
+	}
+
+	img, err := task.Checkpoint(ctx, withCheckpointOpts(info.Runtime.Name, !options.LeaveRunning))
+	if err != nil {
+		return err
+	}
+
+	defer client.ImageService().Delete(ctx, img.Name())
+
+	cs := client.ContentStore()
+
+	rawIndex, err := content.ReadBlob(ctx, cs, img.Target())
+	if err != nil {
+		return fmt.Errorf("failed to retrieve checkpoint data: %w", err)
+	}
+
+	var index ocispec.Index
+	if err := json.Unmarshal(rawIndex, &index); err != nil {
+		return fmt.Errorf("failed to decode checkpoint data: %w", err)
+	}
+
+	var cpDesc *ocispec.Descriptor
+	for _, m := range index.Manifests {
+		if m.MediaType == images.MediaTypeContainerd1Checkpoint {
+			cpDesc = &m //nolint:gosec
+			break
+		}
+	}
+	if cpDesc == nil {
+		return errors.New("invalid checkpoint")
+	}
+
+	targetPath, err := checkpointutil.GetCheckpointDir(options.CheckpointDir, checkpointName, container.ID(), true)
+	if err != nil {
+		return err
+	}
+
+	rat, err := cs.ReaderAt(ctx, *cpDesc)
+	if err != nil {
+		return fmt.Errorf("failed to get checkpoint reader: %w", err)
+	}
+	defer rat.Close()
+
+	_, err = archive.Apply(ctx, targetPath, content.NewReader(rat))
+	if err != nil {
+		return fmt.Errorf("failed to read checkpoint reader: %w", err)
+	}
+
+	fmt.Fprintf(options.Stdout, "%s\n", checkpointName)
+
+	return nil
+}
+
+func withCheckpointOpts(rt string, exit bool) containerd.CheckpointTaskOpts {
+	return func(r *containerd.CheckpointTaskInfo) error {
+
+		switch rt {
+		case plugins.RuntimeRuncV2:
+			if r.Options == nil {
+				r.Options = &options.CheckpointOptions{}
+			}
+			opts, _ := r.Options.(*options.CheckpointOptions)
+
+			opts.Exit = exit
+		}
+		return nil
+	}
+}