feat(system): add nerdctl system df

Add `nerdctl system df`, the equivalent of `docker system df`, reporting how much disk
space the images, containers and local volumes of the current namespace use, plus the
BuildKit build cache.

The sizes follow the Docker v29 definitions for the containerd image store:

  - the size of an image is the content present in the content store plus its unpacked
    snapshots, which is the same value `nerdctl images` shows as DISK USAGE,
  - the SIZE of the Images row counts every snapshot and every blob once, so it is the
    space really taken on disk rather than the sum of the image sizes,
  - an image is active when a container references it, and only the part of an unused
    image that no other image shares is reclaimable,
  - containers contribute their read-write layer only, and everything not running is
    reclaimable,
  - a volume is active when a container mounts it, counted once however many paths it is
    mounted at, as the LINKS column of Docker is a count of containers,
  - a build cache record is reclaimable when it is neither in use nor shared.

An image reports when it was built, read from the config of the manifest the platform
matcher of this host selects: the platforms of an index are not necessarily built
together, and the creation time of the local record only says when the image was pulled
or tagged. The record time stays as the fallback for the images that state nothing.

Both `--format` and `-v/--verbose` are supported, including the Docker `table TEMPLATE`
format, e.g. `table {{.Type}}\t{{.Size}}`: the literal \t and \n are expanded, the chosen
columns get a header that names them whatever the template does to the values below, and
the rows stay aligned. That helper lives in pkg/formatter so that the other commands,
which all share this gap, can adopt it. Identifiers are shortened for the table output
only, so that a custom format stays usable to look a resource up.

The work is split the way `system prune` already is: `pkg/cmd/system` orchestrates,
and each kind of resource is measured by its own package.

Closes #3942

Signed-off-by: Eugene Kalinin <e.v.kalinin@gmail.com>

Author: ekalinin

cmd/nerdctl/system/system.go

@@ -33,6 +33,7 @@ func Command() *cobra.Command {
 	}
 	// versionCommand is not here
 	cmd.AddCommand(
+		dfCommand(),
 		EventsCommand(),
 		InfoCommand(),
 		pruneCommand(),

cmd/nerdctl/system/system_df.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 system
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/containerd/log"
+
+	"github.com/containerd/nerdctl/v2/cmd/nerdctl/builder"
+	"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/system"
+)
+
+func dfCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:           "df [flags]",
+		Short:         "Show nerdctl disk usage",
+		Args:          cobra.NoArgs,
+		RunE:          dfAction,
+		SilenceUsage:  true,
+		SilenceErrors: true,
+	}
+	cmd.Flags().BoolP("verbose", "v", false, "Show detailed information on space usage")
+	cmd.Flags().String("format", "", "Format the output using the given Go template, e.g, '{{json .}}'")
+	return cmd
+}
+
+func dfOptions(cmd *cobra.Command) (types.SystemDfOptions, error) {
+	globalOptions, err := helpers.ProcessRootCmdFlags(cmd)
+	if err != nil {
+		return types.SystemDfOptions{}, err
+	}
+
+	verbose, err := cmd.Flags().GetBool("verbose")
+	if err != nil {
+		return types.SystemDfOptions{}, err
+	}
+
+	format, err := cmd.Flags().GetString("format")
+	if err != nil {
+		return types.SystemDfOptions{}, err
+	}
+
+	buildkitHost, err := builder.GetBuildkitHost(cmd, globalOptions.Namespace)
+	if err != nil {
+		log.L.WithError(err).Warn("BuildKit is not running. The build cache usage will be reported as empty.")
+		buildkitHost = ""
+	}
+
+	return types.SystemDfOptions{
+		Stdout:       cmd.OutOrStdout(),
+		Stderr:       cmd.ErrOrStderr(),
+		GOptions:     globalOptions,
+		Format:       format,
+		Verbose:      verbose,
+		BuildKitHost: buildkitHost,
+	}, nil
+}
+
+func dfAction(cmd *cobra.Command, _ []string) error {
+	options, err := dfOptions(cmd)
+	if err != nil {
+		return err
+	}
+
+	client, ctx, cancel, err := clientutil.NewClient(cmd.Context(), options.GOptions.Namespace, options.GOptions.Address)
+	if err != nil {
+		return err
+	}
+	defer cancel()
+
+	return system.Df(ctx, client, options)
+}

cmd/nerdctl/system/system_df_linux_test.go

@@ -0,0 +1,70 @@
+/*
+   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 system
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/containerd/nerdctl/mod/tigron/test"
+	"github.com/containerd/nerdctl/mod/tigron/tig"
+
+	"github.com/containerd/nerdctl/v2/pkg/testutil"
+	"github.com/containerd/nerdctl/v2/pkg/testutil/nerdtest"
+)
+
+// TestSystemDfVolumes covers the Local Volumes row, which the rest of TestSystemDf cannot: a volume
+// is only counted once a container mounts it, and the target of a mount is written differently on
+// each platform.
+func TestSystemDfVolumes(t *testing.T) {
+	testCase := nerdtest.Setup()
+
+	// The counts are only meaningful when nothing else is running against the same namespace.
+	testCase.NoParallel = true
+
+	testCase.SubTests = []*test.Case{
+		{
+			Description: "mounted volume is active",
+			Require:     nerdtest.Private,
+			Setup: func(data test.Data, helpers test.Helpers) {
+				data.Labels().Set(baselineLabel, helpers.Capture("system", "df"))
+				helpers.Ensure("volume", "create", data.Identifier())
+				helpers.Ensure("run", "-d", "--name", data.Identifier(),
+					"-v", fmt.Sprintf("%s:/volume", data.Identifier()),
+					testutil.CommonImage, "sleep", nerdtest.Infinity)
+			},
+			Cleanup: func(data test.Data, helpers test.Helpers) {
+				helpers.Anyhow("rm", "-f", data.Identifier())
+				helpers.Anyhow("volume", "rm", "-f", data.Identifier())
+			},
+			Command: test.Command("system", "df"),
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: 0,
+					Output: func(stdout string, t tig.T) {
+						// The volume is created by this test and the container it runs mounts it,
+						// so both counts went up by it.
+						dfGrewBy(t, data, stdout, "Local Volumes", totalColumn, 1)
+						dfGrewBy(t, data, stdout, "Local Volumes", activeColumn, 1)
+					},
+				}
+			},
+		},
+	}
+
+	testCase.Run(t)
+}