Skip to content

Latest commit

 

History

History
241 lines (174 loc) · 11 KB

buildx_create.md

File metadata and controls

241 lines (174 loc) · 11 KB
Raw

buildx create

docker buildx create [OPTIONS] [CONTEXT|ENDPOINT]

Create a new builder instance

Options

Name Type Default Description
--append Append a node to builder instead of changing it
--bootstrap Boot builder after creation
--buildkitd-flags string Flags for buildkitd daemon
--config string BuildKit config file
--driver string Driver to use (available: docker-container, kubernetes, remote)
--driver-opt stringArray Options for the driver
--leave Remove a node from builder instead of changing it
--name string Builder instance name
--node string Create/modify node with given name
--platform stringArray Fixed platforms for current node
--use Set the current builder instance

Description

Create makes a new builder instance pointing to a docker context or endpoint, where context is the name of a context from docker context ls and endpoint is the address for docker socket (eg. DOCKER_HOST value).

By default, the current Docker configuration is used for determining the context/endpoint value.

Builder instances are isolated environments where builds can be invoked. All Docker contexts also get the default builder instance.

Examples

Append a new node to an existing builder (--append)

The --append flag changes the action of the command to append a new node to an existing builder specified by --name. Buildx will choose an appropriate node for a build based on the platforms it supports.

$ docker buildx create mycontext1
eager_beaver

$ docker buildx create --name eager_beaver --append mycontext2
eager_beaver

Specify options for the buildkitd daemon (--buildkitd-flags)

--buildkitd-flags FLAGS

Adds flags when starting the buildkitd daemon. They take precedence over the configuration file specified by --config. See buildkitd --help for the available flags.

--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'

Specify a configuration file for the buildkitd daemon (--config)

--config FILE

Specifies the configuration file for the buildkitd daemon to use. The configuration can be overridden by --buildkitd-flags. See an example buildkitd configuration file.

If the configuration file is not specified, will look for one by default in:

  • $BUILDX_CONFIG/buildkitd.default.toml
  • $DOCKER_CONFIG/buildx/buildkitd.default.toml
  • ~/.docker/buildx/buildkitd.default.toml

Note that if you create a docker-container builder and have specified certificates for registries in the buildkitd.toml configuration, the files will be copied into the container under /etc/buildkit/certs and configuration will be updated to reflect that.

Set the builder driver to use (--driver)

--driver DRIVER

Sets the builder driver to be used. There are two available drivers, each have their own specificities.

docker driver

Uses the builder that is built into the docker daemon. With this driver, the --load flag is implied by default on buildx build. However, building multi-platform images or exporting cache is not currently supported.

docker-container driver

Uses a BuildKit container that will be spawned via docker. With this driver, both building multi-platform images and exporting cache are supported.

Unlike docker driver, built images will not automatically appear in docker images and build --load needs to be used to achieve that.

kubernetes driver

Uses a kubernetes pods. With this driver, you can spin up pods with defined BuildKit container image to build your images.

Unlike docker driver, built images will not automatically appear in docker images and build --load needs to be used to achieve that.

remote driver

Uses a remote instance of buildkitd over an arbitrary connection. With this driver, you manually create and manage instances of buildkit yourself, and configure buildx to point at it.

Unlike docker driver, built images will not automatically appear in docker images and build --load needs to be used to achieve that.

Set additional driver-specific options (--driver-opt)

--driver-opt OPTIONS

Passes additional driver-specific options.

Note: When using quoted values for the nodeselector, annotations, labels or tolerations options, ensure that quotes are escaped correctly for your shell.

docker driver

No driver options.

docker-container driver

  • image=IMAGE - Sets the BuildKit image to use for the container.
  • memory=MEMORY - Sets the amount of memory the container can use.
  • memory-swap=MEMORY_SWAP - Sets the memory swap limit for the container.
  • cpu-quota=CPU_QUOTA - Imposes a CPU CFS quota on the container.
  • cpu-period=CPU_PERIOD - Sets the CPU CFS scheduler period for the container.
  • cpu-shares=CPU_SHARES - Configures CPU shares (relative weight) of the container.
  • cpuset-cpus=CPUSET_CPUS - Limits the set of CPU cores the container can use.
  • cpuset-mems=CPUSET_MEMS - Limits the set of CPU memory nodes the container can use.
  • network=NETMODE - Sets the network mode for the container.
  • cgroup-parent=CGROUP - Sets the cgroup parent of the container if docker is using the "cgroupfs" driver. Defaults to /docker/buildx.

Before you configure the resource limits for the container, read about configuring runtime resource constraints for containers.

kubernetes driver

  • image=IMAGE - Sets the container image to be used for running buildkit.
  • namespace=NS - Sets the Kubernetes namespace. Defaults to the current namespace.
  • replicas=N - Sets the number of Pod replicas. Defaults to 1.
  • requests.cpu - Sets the request CPU value specified in units of Kubernetes CPU. Example requests.cpu=100m, requests.cpu=2
  • requests.memory - Sets the request memory value specified in bytes or with a valid suffix. Example requests.memory=500Mi, requests.memory=4G
  • limits.cpu - Sets the limit CPU value specified in units of Kubernetes CPU. Example limits.cpu=100m, limits.cpu=2
  • limits.memory - Sets the limit memory value specified in bytes or with a valid suffix. Example limits.memory=500Mi, limits.memory=4G
  • serviceaccount - Sets the created pod's service account. Example serviceaccount=example-sa
  • "nodeselector=label1=value1,label2=value2" - Sets the kv of Pod nodeSelector. No Defaults. Example nodeselector=kubernetes.io/arch=arm64
  • "annotations=domain/thing1=value1,domain/thing2=value2" - Sets additional annotations on the deployments and pods. No Defaults. Example annotations=example.com/owner=sarah
  • "labels=domain/thing1=value1,domain/thing2=value2" - Sets additional labels on the deployments and pods. No Defaults. Example labels=example.com/team=rd
  • "tolerations=key=foo,value=bar;key=foo2,operator=exists;key=foo3,effect=NoSchedule" - Sets the Pod tolerations. Accepts the same values as the kube manifest tolera>tions. Key-value pairs are separated by ,, tolerations are separated by ;. No Defaults. Example tolerations=operator=exists
  • rootless=(true|false) - Run the container as a non-root user without securityContext.privileged. Needs Kubernetes 1.19 or later. Using Ubuntu host kernel is recommended. Defaults to false.
  • loadbalance=(sticky|random) - Load-balancing strategy. If set to "sticky", the pod is chosen using the hash of the context path. Defaults to "sticky"
  • qemu.install=(true|false) - Install QEMU emulation for multi platforms support.
  • qemu.image=IMAGE - Sets the QEMU emulation image. Defaults to tonistiigi/binfmt:latest

remote driver

  • key=KEY - Sets the TLS client key.
  • cert=CERT - Sets the TLS client certificate to present to buildkitd.
  • cacert=CACERT - Sets the TLS certificate authority used for validation.
  • servername=SERVER - Sets the TLS server name to be used in requests (defaults to the endpoint hostname).

Remove a node from a builder (--leave)

The --leave flag changes the action of the command to remove a node from a builder. The builder needs to be specified with --name and node that is removed is set with --node.

$ docker buildx create --name mybuilder --node mybuilder0 --leave

Specify the name of the builder (--name)

--name NAME

The --name flag specifies the name of the builder to be created or modified. If none is specified, one will be automatically generated.

Specify the name of the node (--node)

--node NODE

The --node flag specifies the name of the node to be created or modified. If none is specified, it is the name of the builder it belongs to, with an index number suffix.

Set the platforms supported by the node (--platform)

--platform PLATFORMS

The --platform flag sets the platforms supported by the node. It expects a comma-separated list of platforms of the form OS/architecture/variant. The node will also automatically detect the platforms it supports, but manual values take priority over the detected ones and can be used when multiple nodes support building for the same platform.

$ docker buildx create --platform linux/amd64
$ docker buildx create --platform linux/arm64,linux/arm/v7

Automatically switch to the newly created builder (--use)

The --use flag automatically switches the current builder to the newly created one. Equivalent to running docker buildx use $(docker buildx create ...).