Try Atomist

Note

Atomist is currently in Early Access. Features and APIs are subject to change.

The quickest way to try Atomist is to run it on your local images, as a CLI tool. Trying it locally eliminates the need of having to integrate with and connect to a remote container registry. The CLI uses your local Docker daemon directly to upload the Software Bill of Materials (SBOM) to the Atomist control plane for analysis.

Prerequisites

Before you can begin the setup, you need a Docker ID. If you don’t already have one, you can register here.

Steps

Note

Only use this CLI-based method of indexing images for testing or trial purposes. For further evaluation or production use, integrate Atomist with your container registry. See get started.

1. Go to the Atomist website and sign in using your Docker ID.
2. Open the Integrations tab.
3. Under API Keys , create a new API key.

4. In your terminal of choice, invoke the Atomist CLI tool using docker run . Update the following values:

   • --workspace : the workspace ID found on the Integrations page on the Atomist website.
   • --api-key : the API key you just created.
   • --image : the Docker image that you want to index.

   docker run \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -ti atomist/docker-registry-broker:latest \
      index-image local \
      --workspace AQ1K5FIKA \
      --api-key team::6016307E4DF885EAE0579AACC71D3507BB38E1855903850CF5D0D91C5C8C6DC0 \
      --image docker.io/david/myimage:latest
   

   Note

   The image must have a tag (for example, myimage:latest ) so that you are able to identify the image later.

   The output should be similar to the following:

   [info] Starting session with correlation-id c12e08d3-3bcc-4475-ab21-7114da599eaf
   [info] Starting atomist/docker-vulnerability-scanner-skill 'index_image' (1f99caa) atomist/skill:0.12.0-main.44 (fe90e3c) nodejs:16.15.0
   [info] Indexing image python:latest
   [info] Downloading image
   [info] Download completed
   [info] Indexing completed
   [info] Mapped packages to layers
   [info] Indexing completed successfully
   [info] Transacting image manifest for docker.io/david/myimage:latest with digest sha256:a8077d2b2ff4feb1588d941f00dd26560fe3a919c16a96305ce05f7b90f388f6
   [info] Successfully transacted entities in team AQ1K5FIKA
   [info] Image URL is https://dso.atomist.com/AQ1K5FIKA/overview/images/myimage/digests/sha256:a8077d2b2ff4feb1588d941f00dd26560fe3a919c16a96305ce05f7b90f388f6
   [info] Transacting SBOM...
   [info] Successfully transacted entities in team AQ1K5FIKA
   [info] Transacting SBOM...
   

5. When the command exits, open the Atomist web UI, where you should see the image in the list.

   

6. Select the image name. This gets you to the list of image tags.

   

   Since this is your first time indexing this image, the list only has one tag for now. When you integrate Atomist with your container registry, images and tags show up in this list automatically.

7. Select the tag name. This shows you the insights for this tag.

   

   In this view, you can see how many vulnerabilities this image has, their severity levels, whether there is a fix version available, and more.

Where to go next

The tutorial ends here. Take some time to explore the different data views that Atomist presents about your image. When you’re ready, head to the get started guide to learn how to start integrating Atomist in your software supply chain.

Defining additional build contexts and linking targets

In addition to the main context key that defines the build context each target can also define additional named contexts with a map defined with key contexts . These values map to the --build-context flag in the build command.

Inside the Dockerfile these contexts can be used with the FROM instruction or --from flag.

The value can be a local source directory, container image (with docker-image:// prefix), Git URL, HTTP URL or a name of another target in the Bake file (with target: prefix).

Pinning alpine image

# syntax=docker/dockerfile:1
FROM alpine
RUN echo "Hello world"

# docker-bake.hcl
target "app" {
  contexts = {
    alpine = "docker-image://alpine:3.13"
  }
}

Using a secondary source directory

# syntax=docker/dockerfile:1
FROM scratch AS src

FROM golang
COPY --from=src . .

# docker-bake.hcl
target "app" {
  contexts = {
    src = "../path/to/source"
  }
}

Using a result of one target as a base image in another target

To use a result of one target as a build context of another, specity the target name with target: prefix.

# syntax=docker/dockerfile:1
FROM baseapp
RUN echo "Hello world"

# docker-bake.hcl
target "base" {
  dockerfile = "baseapp.Dockerfile"
}

target "app" {
  contexts = {
    baseapp = "target:base"
  }
}

Please note that in most cases you should just use a single multi-stage Dockerfile with multiple targets for similar behavior. This case is recommended when you have multiple Dockerfiles that can’t be easily merged into one.

Building from Compose file

Specification

Bake uses the compose-spec to parse a compose file and translate each service to a target.

# docker-compose.yml
services:
  webapp-dev: 
    build: &build-dev
      dockerfile: Dockerfile.webapp
      tags:
        - docker.io/username/webapp:latest
      cache_from:
        - docker.io/username/webapp:cache
      cache_to:
        - docker.io/username/webapp:cache

  webapp-release:
    build:
      <<: *build-dev
      x-bake:
        platforms:
          - linux/amd64
          - linux/arm64

  db:
    image: docker.io/username/db
    build:
      dockerfile: Dockerfile.db

$ docker buildx bake --print

{
  "group": {
    "default": {
      "targets": [
        "db",
        "webapp-dev",
        "webapp-release"
      ]
    }
  },
  "target": {
    "db": {
      "context": ".",
      "dockerfile": "Dockerfile.db",
      "tags": [
        "docker.io/username/db"
      ]
    },
    "webapp-dev": {
      "context": ".",
      "dockerfile": "Dockerfile.webapp",
      "tags": [
        "docker.io/username/webapp:latest"
      ],
      "cache-from": [
        "docker.io/username/webapp:cache"
      ],
      "cache-to": [
        "docker.io/username/webapp:cache"
      ]
    },
    "webapp-release": {
      "context": ".",
      "dockerfile": "Dockerfile.webapp",
      "tags": [
        "docker.io/username/webapp:latest"
      ],
      "cache-from": [
        "docker.io/username/webapp:cache"
      ],
      "cache-to": [
        "docker.io/username/webapp:cache"
      ],
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ]
    }
  }
}

Unlike the HCL format, there are some limitations with the compose format:

• Specifying variables or global scope attributes is not yet supported
• inherits service field is not supported, but you can use YAML anchors to reference other services like the example above

.env file

You can declare default environment variables in an environment file named .env . This file will be loaded from the current working directory, where the command is executed and applied to compose definitions passed with -f .

# docker-compose.yml
services:
  webapp:
    image: docker.io/username/webapp:${TAG:-v1.0.0}
    build:
      dockerfile: Dockerfile

# .env
TAG=v1.1.0

$ docker buildx bake --print

{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "docker.io/username/webapp:v1.1.0"
      ]
    }
  }
}

Note

System environment variables take precedence over environment variables in .env file.

Extension field with x-bake

Even if some fields are not (yet) available in the compose specification, you can use the special extension field x-bake in your compose file to evaluate extra fields:

# docker-compose.yml
services:
  addon:
    image: ct-addon:bar
    build:
      context: .
      dockerfile: ./Dockerfile
      args:
        CT_ECR: foo
        CT_TAG: bar
      x-bake:
        tags:
          - ct-addon:foo
          - ct-addon:alp
        platforms:
          - linux/amd64
          - linux/arm64
        cache-from:
          - user/app:cache
          - type=local,src=path/to/cache
        cache-to:
          - type=local,dest=path/to/cache
        pull: true

  aws:
    image: ct-fake-aws:bar
    build:
      dockerfile: ./aws.Dockerfile
      args:
        CT_ECR: foo
        CT_TAG: bar
      x-bake:
        secret:
          - id=mysecret,src=./secret
          - id=mysecret2,src=./secret2
        platforms: linux/arm64
        output: type=docker
        no-cache: true

$ docker buildx bake --print

{
  "group": {
    "default": {
      "targets": [
        "aws",
        "addon"
      ]
    }
  },
  "target": {
    "addon": {
      "context": ".",
      "dockerfile": "./Dockerfile",
      "args": {
        "CT_ECR": "foo",
        "CT_TAG": "bar"
      },
      "tags": [
        "ct-addon:foo",
        "ct-addon:alp"
      ],
      "cache-from": [
        "user/app:cache",
        "type=local,src=path/to/cache"
      ],
      "cache-to": [
        "type=local,dest=path/to/cache"
      ],
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ],
      "pull": true
    },
    "aws": {
      "context": ".",
      "dockerfile": "./aws.Dockerfile",
      "args": {
        "CT_ECR": "foo",
        "CT_TAG": "bar"
      },
      "tags": [
        "ct-fake-aws:bar"
      ],
      "secret": [
        "id=mysecret,src=./secret",
        "id=mysecret2,src=./secret2"
      ],
      "platforms": [
        "linux/arm64"
      ],
      "output": [
        "type=docker"
      ],
      "no-cache": true
    }
  }
}

Complete list of valid fields for x-bake :

• cache-from
• cache-to
• contexts
• no-cache
• no-cache-filter
• output
• platforms
• pull
• secret
• ssh
• tags

Configuring builds

Bake supports loading build definition from files, but sometimes you need even more flexibility to configure this definition.

For this use case, you can define variables inside the bake files that can be set by the user with environment variables or by attribute definitions in other bake files. If you wish to change a specific value for a single invocation you can use the --set flag from the command line.

Global scope attributes

You can define global scope attributes in HCL/JSON and use them for code reuse and setting values for variables. This means you can do a “data-only” HCL file with the values you want to set/override and use it in the list of regular output files.

# docker-bake.hcl
variable "FOO" {
  default = "abc"
}

target "app" {
  args = {
    v1 = "pre-${FOO}"
  }
}

You can use this file directly:

$ docker buildx bake --print app

{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "v1": "pre-abc"
      }
    }
  }
}

Or create an override configuration file:

# env.hcl
WHOAMI="myuser"
FOO="def-${WHOAMI}"

And invoke bake together with both of the files:

$ docker buildx bake -f docker-bake.hcl -f env.hcl --print app

{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "v1": "pre-def-myuser"
      }
    }
  }
}

From command line

You can also override target configurations from the command line with the --set flag:

# docker-bake.hcl
target "app" {
  args = {
    mybuildarg = "foo"
  }
}

$ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm64 app --print

{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "mybuildarg": "bar"
      },
      "platforms": [
        "linux/arm64"
      ]
    }
  }
}

Pattern matching syntax defined in https://golang.org/pkg/path/#Match is also supported:

$ docker buildx bake --set foo*.args.mybuildarg=value  # overrides build arg for all targets starting with "foo"
$ docker buildx bake --set *.platform=linux/arm64      # overrides platform for all targets
$ docker buildx bake --set foo*.no-cache               # bypass caching only for targets starting with "foo"

Complete list of overridable fields:

• args
• cache-from
• cache-to
• context
• dockerfile
• labels
• no-cache
• output
• platform
• pull
• secrets
• ssh
• tags
• target

Using variables in variables across files

When multiple files are specified, one file can use variables defined in another file.

# docker-bake1.hcl
variable "FOO" {
  default = upper("${BASE}def")
}

variable "BAR" {
  default = "-${FOO}-"
}

target "app" {
  args = {
    v1 = "pre-${BAR}"
  }
}

# docker-bake2.hcl
variable "BASE" {
  default = "abc"
}

target "app" {
  args = {
    v2 = "${FOO}-post"
  }
}

$ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app

{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "v1": "pre--ABCDEF-",
        "v2": "ABCDEF-post"
      }
    }
  }
}

Bake file definition

buildx bake supports HCL, JSON and Compose file format for defining build groups, targets as well as variables and functions. It looks for build definition files in the current directory in the following order:

• docker-compose.yml
• docker-compose.yaml
• docker-bake.json
• docker-bake.override.json
• docker-bake.hcl
• docker-bake.override.hcl

Specification

Inside a bake file you can declare group, target and variable blocks to define project specific reusable build flows.

Target

A target reflects a single docker build invocation with the same options that you would specify for docker build :

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
}

$ docker buildx bake webapp-dev

Note

In the case of compose files, each service corresponds to a target. If compose service name contains a dot it will be replaced with an underscore.

Complete list of valid target fields available for HCL and JSON definitions:

Group

A group is a grouping of targets:

# docker-bake.hcl
group "build" {
  targets = ["db", "webapp-dev"]
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  tags = ["docker.io/username/db"]
}

$ docker buildx bake build

Variable

Similar to how Terraform provides a way to define variables, the HCL file format also supports variable block definitions. These can be used to define variables with values provided by the current environment, or a default value when unset:

# docker-bake.hcl
variable "TAG" {
  default = "latest"
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:${TAG}"]
}

$ docker buildx bake webapp-dev          # will use the default value "latest"
$ TAG=dev docker buildx bake webapp-dev  # will use the TAG environment variable value

Tip

See also the Configuring builds page for advanced usage.

Functions

A set of generally useful functions provided by go-cty are available for use in HCL files:

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    buildno = "${add(123, 1)}"
  }
}

In addition, user defined functions are also supported:

# docker-bake.hcl
function "increment" {
  params = [number]
  result = number + 1
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    buildno = "${increment(123)}"
  }
}

Note

See User defined HCL functions page for more details.

Built-in variables

• BAKE_CMD_CONTEXT can be used to access the main context for bake command from a bake file that has been imported remotely.
• BAKE_LOCAL_PLATFORM returns the current platform’s default platform specification (e.g. linux/amd64 ).

Merging and inheritance

Multiple files can include the same target and final build options will be determined by merging them together:

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
}

# docker-bake2.hcl
target "webapp-dev" {
  tags = ["docker.io/username/webapp:dev"]
}

$ docker buildx bake -f docker-bake.hcl -f docker-bake2.hcl webapp-dev

A group can specify its list of targets with the targets option. A target can inherit build options by setting the inherits option to the list of targets or groups to inherit from:

# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:${TAG}"]
}

target "webapp-release" {
  inherits = ["webapp-dev"]
  platforms = ["linux/amd64", "linux/arm64"]
}

default target/group

When you invoke bake you specify what targets/groups you want to build. If no arguments is specified, the group/target named default will be built:

# docker-bake.hcl
target "default" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
}

$ docker buildx bake

Definitions

HCL definition

HCL definition file is recommended as its experience is more aligned with buildx UX and also allows better code reuse, different target groups and extended features.

# docker-bake.hcl
variable "TAG" {
  default = "latest"
}

group "default" {
  targets = ["db", "webapp-dev"]
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:${TAG}"]
}

target "webapp-release" {
  inherits = ["webapp-dev"]
  platforms = ["linux/amd64", "linux/arm64"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  tags = ["docker.io/username/db"]
}

JSON definition

{
  "variable": {
    "TAG": {
      "default": "latest"
    }
  },
  "group": {
    "default": {
      "targets": [
        "db",
        "webapp-dev"
      ]
    }
  },
  "target": {
    "webapp-dev": {
      "dockerfile": "Dockerfile.webapp",
      "tags": [
        "docker.io/username/webapp:${TAG}"
      ]
    },
    "webapp-release": {
      "inherits": [
        "webapp-dev"
      ],
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ]
    },
    "db": {
      "dockerfile": "Dockerfile.db",
      "tags": [
        "docker.io/username/db"
      ]
    }
  }
}

Compose file

# docker-compose.yml
services:
  webapp:
    image: docker.io/username/webapp:latest
    build:
      dockerfile: Dockerfile.webapp

  db:
    image: docker.io/username/db
    build:
      dockerfile: Dockerfile.db

Note

See Building from Compose file page for more details.

Remote definition

You can also build bake files directly from a remote Git repository or HTTPS URL:

$ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print
#1 [internal] load git source https://github.com/docker/cli.git#v20.10.11
#1 0.745 e8f1871b077b64bcb4a13334b7146492773769f7       refs/tags/v20.10.11
#1 2.022 From https://github.com/docker/cli
#1 2.022  * [new tag]         v20.10.11  -> v20.10.11
#1 DONE 2.9s

{
  "group": {
    "default": {
      "targets": [
        "binary"
      ]
    }
  },
  "target": {
    "binary": {
      "context": "https://github.com/docker/cli.git#v20.10.11",
      "dockerfile": "Dockerfile",
      "args": {
        "BASE_VARIANT": "alpine",
        "GO_STRIP": "",
        "VERSION": ""
      },
      "target": "binary",
      "platforms": [
        "local"
      ],
      "output": [
        "build"
      ]
    }
  }
}

As you can see the context is fixed to https://github.com/docker/cli.git even if no context is actually defined in the definition.

If you want to access the main context for bake command from a bake file that has been imported remotely, you can use the BAKE_CMD_CONTEXT built-in var.

$ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl

target "default" {
  context = BAKE_CMD_CONTEXT
  dockerfile-inline = <<EOT
FROM alpine
WORKDIR /src
COPY . .
RUN ls -l && stop
EOT
}

$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" --print

{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
    }
  }
}

$ touch foo bar
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test"

...
 > [4/4] RUN ls -l && stop:
#8 0.101 total 0
#8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 bar
#8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 foo
#8 0.102 /bin/sh: stop: not found

$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11" --print
#1 [internal] load git source https://github.com/tonistiigi/buildx.git#remote-test
#1 0.429 577303add004dd7efeb13434d69ea030d35f7888       refs/heads/remote-test
#1 CACHED

{
  "target": {
    "default": {
      "context": "https://github.com/docker/cli.git#v20.10.11",
      "dockerfile": "Dockerfile",
      "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
    }
  }
}

$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11"

...
 > [4/4] RUN ls -l && stop:
#8 0.136 drwxrwxrwx    5 root     root          4096 Jul 27 18:31 kubernetes
#8 0.136 drwxrwxrwx    3 root     root          4096 Jul 27 18:31 man
#8 0.136 drwxrwxrwx    2 root     root          4096 Jul 27 18:31 opts
#8 0.136 -rw-rw-rw-    1 root     root          1893 Jul 27 18:31 poule.yml
#8 0.136 drwxrwxrwx    7 root     root          4096 Jul 27 18:31 scripts
#8 0.136 drwxrwxrwx    3 root     root          4096 Jul 27 18:31 service
#8 0.136 drwxrwxrwx    2 root     root          4096 Jul 27 18:31 templates
#8 0.136 drwxrwxrwx   10 root     root          4096 Jul 27 18:31 vendor
#8 0.136 -rwxrwxrwx    1 root     root          9620 Jul 27 18:31 vendor.conf
#8 0.136 /bin/sh: stop: not found