Skip to content

imagetools: metadata-file flag #3638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
crazy-max wants to merge 1 commit into
base: master
Choose a base branch
from
+84 −14
Open

imagetools: metadata-file flag #3638

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions commands/imagetools/create.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ import (
"github.com/docker/buildx/util/imagetools"
"github.com/docker/buildx/util/progress"
"github.com/docker/cli/cli/command"
"github.com/moby/buildkit/exporter/containerimage/exptypes"
"github.com/moby/buildkit/util/progress/progressui"
"github.com/moby/sys/atomicwriter"
"github.com/opencontainers/go-digest"
ocispecs "github.com/opencontainers/image-spec/specs-go/v1"
"github.com/pkg/errors"
Expand All @@ -34,6 +36,7 @@ type createOptions struct {
progress string
preferIndex bool
platforms []string
metadataFile string
}

func runCreate(ctx context.Context, dockerCli command.Cli, in createOptions, args []string) error {
Expand Down Expand Up @@ -241,6 +244,14 @@ func runCreate(ctx context.Context, dockerCli command.Cli, in createOptions, arg
err = err1
}

if err == nil && len(in.metadataFile) > 0 {
if err := writeMetadataFile(in.metadataFile, map[string]any{
exptypes.ExporterImageDigestKey: desc.Digest.String(),
Copy link
Member

@tonistiigi tonistiigi Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe already better to just add ExporterImageDescriptorKey ?

}); err != nil {
return err
}
}

return err
}

Expand Down Expand Up @@ -348,6 +359,7 @@ func createCmd(dockerCli command.Cli, opts RootOptions) *cobra.Command {
flags.StringArrayVarP(&options.annotations, "annotation", "", []string{}, "Add annotation to the image")
flags.BoolVar(&options.preferIndex, "prefer-index", true, "When only a single source is specified, prefer outputting an image index or manifest list instead of performing a carbon copy")
flags.StringArrayVarP(&options.platforms, "platform", "p", []string{}, "Filter specified platforms of target image")
flags.StringVar(&options.metadataFile, "metadata-file", "", "Write create result metadata to a file")

return cmd
}
Expand All @@ -367,3 +379,11 @@ func mergeDesc(d1, d2 ocispecs.Descriptor) (ocispecs.Descriptor, error) {
}
return d1, nil
}

func writeMetadataFile(filename string, dt any) error {
b, err := json.MarshalIndent(dt, "", " ")
if err != nil {
return err
}
return atomicwriter.WriteFile(filename, b, 0o644)
}
42 changes: 30 additions & 12 deletions docs/reference/buildx_imagetools_create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,19 @@ Create a new image based on source images

### Options

| Name | Type | Default | Description |
|:---------------------------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------------------------|
| [`--annotation`](#annotation) | `stringArray` | | Add annotation to the image |
| [`--append`](#append) | `bool` | | Append to existing manifest |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--dry-run`](#dry-run) | `bool` | | Show final image instead of pushing |
| [`-f`](#file), [`--file`](#file) | `stringArray` | | Read source descriptor from file |
| `-p`, `--platform` | `stringArray` | | Filter specified platforms of target image |
| `--prefer-index` | `bool` | `true` | When only a single source is specified, prefer outputting an image index or manifest list instead of performing a carbon copy |
| `--progress` | `string` | `auto` | Set type of progress output (`auto`, `none`, `plain`, `rawjson`, `tty`). Use plain to show container output |
| [`-t`](#tag), [`--tag`](#tag) | `stringArray` | | Set reference for new image |
| Name | Type | Default | Description |
|:------------------------------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------------------------|
| [`--annotation`](#annotation) | `stringArray` | | Add annotation to the image |
| [`--append`](#append) | `bool` | | Append to existing manifest |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--dry-run`](#dry-run) | `bool` | | Show final image instead of pushing |
| [`-f`](#file), [`--file`](#file) | `stringArray` | | Read source descriptor from file |
| [`--metadata-file`](#metadata-file) | `string` | | Write create result metadata to a file |
| `-p`, `--platform` | `stringArray` | | Filter specified platforms of target image |
| `--prefer-index` | `bool` | `true` | When only a single source is specified, prefer outputting an image index or manifest list instead of performing a carbon copy |
| `--progress` | `string` | `auto` | Set type of progress output (`auto`, `none`, `plain`, `rawjson`, `tty`). Use plain to show container output |
| [`-t`](#tag), [`--tag`](#tag) | `stringArray` | | Set reference for new image |


<!---MARKER_GEN_END-->
Expand Down Expand Up @@ -100,6 +101,23 @@ The descriptor in the file is merged with existing descriptor in the registry if

The supported fields for the descriptor are defined in [OCI spec](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#properties) .

### <a name="metadata-file"></a> Write create result metadata to a file (--metadata-file)

To output metadata such as the image digest, pass the `--metadata-file` flag.
The metadata will be written as a JSON object to the specified file. The
directory of the specified file must already exist and be writable.

```console
$ docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2 --metadata-file metadata.json
$ cat metadata.json
```

```json
{
"containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}
```

### <a name="tag"></a> Set reference for new image (-t, --tag)

```text
Expand Down
36 changes: 34 additions & 2 deletions tests/imagetools.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,17 @@ package tests

import (
"encoding/json"
"os"
"os/exec"
"path"
"path/filepath"
"testing"

"github.com/containerd/containerd/v2/core/images"
"github.com/containerd/continuity/fs/fstest"
"github.com/containerd/platforms"
"github.com/moby/buildkit/util/testutil/integration"
"github.com/opencontainers/go-digest"
ocispecs "github.com/opencontainers/image-spec/specs-go/v1"
"github.com/pkg/errors"
"github.com/stretchr/testify/require"
Expand Down Expand Up @@ -50,10 +54,24 @@ func testImagetoolsCopyManifest(t *testing.T, sb integration.Sandbox) {
require.NoError(t, err)
target2 := registry2 + "/buildx/imtools2-manifest:latest"

cmd = buildxCmd(sb, withArgs("imagetools", "create", "-t", target2, target))
cmd = buildxCmd(sb, withArgs("imagetools", "create", "--metadata-file", path.Join(dir, "md.json"), "-t", target2, target))
dt, err = cmd.CombinedOutput()
require.NoError(t, err, string(dt))

mddt, err := os.ReadFile(filepath.Join(dir, "md.json"))
require.NoError(t, err)

type mdT struct {
ImageDigest string `json:"containerimage.digest"`
}
var md mdT
err = json.Unmarshal(mddt, &md)
require.NoError(t, err)

require.NotEmpty(t, md.ImageDigest)
_, err = digest.Parse(md.ImageDigest)
require.NoError(t, err)

cmd = buildxCmd(sb, withArgs("imagetools", "inspect", target2, "--raw"))
dt, err = cmd.CombinedOutput()
require.NoError(t, err, string(dt))
Expand Down Expand Up @@ -123,10 +141,24 @@ func testImagetoolsCopyIndex(t *testing.T, sb integration.Sandbox) {
require.NoError(t, err)
target2 := registry2 + "/buildx/imtools2:latest"

cmd = buildxCmd(sb, withArgs("imagetools", "create", "-t", target2, target))
cmd = buildxCmd(sb, withArgs("imagetools", "create", "--metadata-file", path.Join(dir, "md.json"), "-t", target2, target))
dt, err = cmd.CombinedOutput()
require.NoError(t, err, string(dt))

mddt, err := os.ReadFile(filepath.Join(dir, "md.json"))
require.NoError(t, err)

type mdT struct {
ImageDigest string `json:"containerimage.digest"`
}
var md mdT
err = json.Unmarshal(mddt, &md)
require.NoError(t, err)

require.NotEmpty(t, md.ImageDigest)
_, err = digest.Parse(md.ImageDigest)
require.NoError(t, err)

cmd = buildxCmd(sb, withArgs("imagetools", "inspect", target2, "--raw"))
dt, err = cmd.CombinedOutput()
require.NoError(t, err, string(dt))
Expand Down