podman-farm-build

podman-farm-build(1) General Commands Manual podman-farm-build(1)

NAME

   podman-farm-build - Build images on farm nodes, then bundle them into a manifest list

SYNOPSIS

   podman farm build [options] [context]

DESCRIPTION

   podman  farm  build Builds an image on all nodes in a farm and bundles them up into a manifest list.  It executes the podman build command on the nodes in the farm with the given Con‐
   tainerfile. Once the images are built on all the farm nodes, the images will be pushed to the registry given via the --tag flag. Once all the images have been pushed, a manifest  list
   will be created locally and pushed to the registry as well.

   The manifest list will contain an image per native architecture type that is present in the farm.

   The primary function of this command is to create multi-architecture builds that will be faster than doing it via emulation using podman build --arch --platform.

   If no farm is specified, the build will be sent out to all the nodes that podman system connection knows of.

   Note: Since the images built are directly pushed to a registry, the user must pass in a full image name using the --tag option in the format registry/repository/imageName[:tag]`.

OPTIONS --add-host=hostname[;hostname[;...]]:ip

   Add a custom host-to-IP mapping to the container's /etc/hosts file.

   The  option  takes one or multiple semicolon-separated hostnames to be mapped to a single IPv4 or IPv6 address, separated by a colon. It can also be used to overwrite the IP addresses
   of hostnames Podman adds to /etc/hosts by default (also see the --name and --hostname options). This option can be specified multiple times to add additional mappings  to  /etc/hosts.
   It conflicts with the --no-hosts option and conflicts with no_hosts=true in containers.conf.

   Instead  of  an  IP  address, the special flag host-gateway can be given. This resolves to an IP address the container can use to connect to the host. The IP address chosen depends on
   your network setup, thus there's no guarantee that Podman can determine the host-gateway address automatically, which will then cause Podman to fail with an  error  message.  You  can
   overwrite this IP address using the host_containers_internal_ip option in containers.conf.

   The  host-gateway  address  is  also used by Podman to automatically add the host.containers.internal and host.docker.internal hostnames to /etc/hosts.  You can prevent that by either
   giving the --no-hosts option, or by setting host_containers_internal_ip="none" in containers.conf. If no host-gateway address was configured manually and Podman fails to determine the
   IP address automatically, Podman will silently skip adding these internal hostnames to /etc/hosts. If Podman is running in a virtual machine using podman machine  (this  includes  Mac
   and  Windows  hosts),  Podman  will silently skip adding the internal hostnames to /etc/hosts, unless an IP address was configured manually; the internal hostnames are resolved by the
   gvproxy DNS resolver instead.

   Podman will use the /etc/hosts file of the host as a basis by default, i.e.  any hostname present in this file will also be present in the /etc/hosts file of the container. A  differ‐
   ent base file can be configured using the base_hosts_file config in containers.conf.

--annotation=annotation=value

   Add an image annotation (e.g. annotation=value) to the image metadata. Can be used multiple times.

   Note: this information is not present in Docker image formats, so it is discarded when writing images in Docker formats.

--authfile=path

   Path  of  the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json on Linux, and $HOME/.config/containers/auth.json on Windows/macOS.  The file is created by podman
   login. If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using docker login.

   Note: There is also the option to override the default path of the authentication file by setting the REGISTRY_AUTH_FILE environment variable.  This  can  be  done  with  export  REG‐
   ISTRY_AUTH_FILE=path.

--build-arg=arg=value

   Specifies a build argument and its value, which is interpolated in instructions read from the Containerfiles in the same way that environment variables are, but which are not added to
   environment variable list in the resulting image's configuration.

--build-arg-file=path

   Specifies a file containing lines of build arguments of the form arg=value.  The suggested file name is argfile.conf.

   Comment lines beginning with # are ignored, along with blank lines.  All others must be of the arg=value format passed to --build-arg.

   If several arguments are provided via the --build-arg-file and --build-arg options, the build arguments are merged across all of the provided files and command line arguments.

   Any file provided in a --build-arg-file option is read before the arguments supplied via the --build-arg option.

   When  a  given  argument name is specified several times, the last instance is the one that is passed to the resulting builds. This means --build-arg values always override those in a
   --build-arg-file.

--build-context=name=value

   Specify an additional build context using its short name and its location.  Additional build contexts can be referenced in the same manner as we access different stages  in  COPY  in‐
   struction.

   Valid values are:

          • Local  directory  –  e.g. --build-context project2=../path/to/project2/src (This option is not available with the remote Podman client. On Podman machine setup (i.e macOS and
            Windows) path must exists on the machine VM)

          • HTTP URL to a tarball – e.g. --build-context src=https://example.org/releases/src.tar

          • Container image – specified with a container-image:// prefix, e.g. --build-context alpine=container-image://alpine:3.15, (also accepts docker://, docker-image://)

   On the Containerfile side, reference the build context on all commands that accept the “from” parameter. Here’s how that might look:

   FROM [name]
   COPY --from=[name] ...
   RUN --mount=from=[name] …

   The value of [name] is matched with the following priority order:

          • Named build context defined with --build-context [name]=..

          • Stage defined with AS [name] inside Containerfile

          • Image [name], either local or in a remote registry

--cache-from=image

   Repository to utilize as a potential cache source. When specified, Buildah tries to look for cache images in the specified repository and attempts to pull cache images instead of  ac‐
   tually executing the build steps locally. Buildah only attempts to pull previously cached images if they are considered as valid cache hits.

   Use the --cache-to option to populate a remote repository with cache content.

   Example

   # populate a cache and also consult it
   buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .

   Note: --cache-from option is ignored unless --layers is specified.

--cache-to=image

   Set this flag to specify a remote repository that is used to store cache images. Buildah attempts to push newly built cache image to the remote repository.

   Note: Use the --cache-from option in order to use cache content in a remote repository.

   Example

   # populate a cache and also consult it
   buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .

   Note: --cache-to option is ignored unless --layers is specified.

--cache-ttl

   Limit  the  use  of  cached  images to only consider images with created timestamps less than duration ago.  For example if --cache-ttl=1h is specified, Buildah considers intermediate
   cache images which are created under the duration of one hour, and intermediate cache images outside this duration is ignored.

   Note: Setting --cache-ttl=0 manually is equivalent to using --no-cache in the implementation since this means that the user does not want to use cache at all.

--cap-add=CAP_xxx

   When executing RUN instructions, run the command specified in the instruction with the specified capability added to its capability set.  Certain capabilities are granted by  default;
   this option can be used to add more.

--cap-drop=CAP_xxx

   When  executing  RUN  instructions,  run  the  command  specified  in  the instruction with the specified capability removed from its capability set.  The CAP_CHOWN, CAP_DAC_OVERRIDE,
   CAP_FOWNER, CAP_FSETID, CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP, and CAP_SETUID capabilities are granted by default; this option can  be  used  to  remove
   them.

   If a capability is specified to both the --cap-add and --cap-drop options, it is dropped, regardless of the order in which the options were given.

--cert-dir=path

   Use  certificates  at path (*.crt, *.cert, *.key) to connect to the registry. (Default: /etc/containers/certs.d) For details, see containers-certs.d(5).  (This option is not available
   with the remote Podman client, including Mac and Windows (excluding WSL2) machines)

--cgroup-parent=path

   Path to cgroups under which the cgroup for the container is created. If the path is not absolute, the path is considered to be relative to  the  cgroups  path  of  the  init  process.
   Cgroups are created if they do not already exist.

--cgroupns=how

   Sets the configuration for cgroup namespaces when handling RUN instructions.  The configured value can be "" (the empty string) or "private" to indicate that a new cgroup namespace is
   created, or it can be "host" to indicate that the cgroup namespace in which buildah itself is being run is reused.

--cleanup

   Remove built images from farm nodes on success (Default: false).

--compat-volumes

   Handle  directories  marked  using  the VOLUME instruction (both in this build, and those inherited from base images) such that their contents can only be modified by ADD and COPY in‐
   structions. Any changes made in those locations by RUN instructions will be reverted. Before the introduction of this option, this behavior was the default, but it is now disabled  by
   default.

--cpp-flag=flags

   Set  additional  flags  to pass to the C Preprocessor cpp(1). Containerfiles ending with a ".in" suffix is preprocessed via cpp(1). This option can be used to pass additional flags to
   cpp.Note: You can also set default CPPFLAGS by setting the BUILDAH_CPPFLAGS environment variable (e.g., export BUILDAH_CPPFLAGS="-DDEBUG").

--cpu-period=limit

   Set the CPU period for the Completely Fair Scheduler (CFS), which is a duration in microseconds. Once the container's CPU quota is used up, it will not be scheduled to run  until  the
   current period ends. Defaults to 100000 microseconds.

   On  some  systems,  changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-run‐
   ning-containers-with-resource-limits-fails-with-a-permissions-error

   This option is not supported on cgroups V1 rootless systems.

--cpu-quota=limit

   Limit the CPU Completely Fair Scheduler (CFS) quota.

   Limit the container's CPU usage. By default, containers run with the full CPU resource. The limit is a number in microseconds. If a number is provided, the container is allowed to use
   that much CPU time until the CPU period ends (controllable via --cpu-period).

   On some systems, changing the resource limits may not be allowed for non-root users. For more  details,  see  https://github.com/containers/podman/blob/main/troubleshooting.md#26-run‐
   ning-containers-with-resource-limits-fails-with-a-permissions-error

   This option is not supported on cgroups V1 rootless systems.

--cpu-shares, -c=shares

   CPU shares (relative weight).

   By  default,  all  containers get the same proportion of CPU cycles. This proportion can be modified by changing the container's CPU share weighting relative to the combined weight of
   all the running containers.  Default weight is 1024.

   The proportion only applies when CPU-intensive processes are running.  When tasks in one container are idle, other containers can use the left-over CPU time. The actual amount of  CPU
   time varies depending on the number of containers running on the system.

   For  example, consider three containers, one has a cpu-share of 1024 and two others have a cpu-share setting of 512. When processes in all three containers attempt to use 100% of CPU,
   the first container receives 50% of the total CPU time. If a fourth container is added with a cpu-share of 1024, the first container only gets 33% of the CPU. The remaining containers
   receive 16.5%, 16.5% and 33% of the CPU.

   On a multi-core system, the shares of CPU time are distributed over all CPU cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU
   core.

   For example, consider a system with more than three cores.  If the container C0 is started with --cpu-shares=512 running one process, and another container C1  with  --cpu-shares=1024
   running two processes, this can result in the following division of CPU shares:

   ┌─────┬───────────┬─────┬──────────────┐
   │ PID │ container │ CPU │ CPU share    │
   ├─────┼───────────┼─────┼──────────────┤
   │ 100 │ C0        │ 0   │ 100% of CPU0 │
   ├─────┼───────────┼─────┼──────────────┤
   │ 101 │ C1        │ 1   │ 100% of CPU1 │
   ├─────┼───────────┼─────┼──────────────┤
   │ 102 │ C1        │ 2   │ 100% of CPU2 │
   └─────┴───────────┴─────┴──────────────┘

   On  some  systems,  changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-run‐
   ning-containers-with-resource-limits-fails-with-a-permissions-error

   This option is not supported on cgroups V1 rootless systems.

--cpuset-cpus=number

   CPUs in which to allow execution. Can be specified as a comma-separated list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof (e.g. 0-3,7,11-15).

   On some systems, changing the resource limits may not be allowed for non-root users. For more  details,  see  https://github.com/containers/podman/blob/main/troubleshooting.md#26-run‐
   ning-containers-with-resource-limits-fails-with-a-permissions-error

   This option is not supported on cgroups V1 rootless systems.

--cpuset-mems=nodes

   Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.

   If there are four memory nodes on the system (0-3), use --cpuset-mems=0,1 then processes in the container only uses memory from the first two memory nodes.

   On  some  systems,  changing the resource limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-run‐
   ning-containers-with-resource-limits-fails-with-a-permissions-error

   This option is not supported on cgroups V1 rootless systems.

--creds=[username[:password]]

   The [username[:password]] to use to authenticate with the registry, if required.  If one or both values are not supplied, a command line prompt appears and the value can  be  entered.
   The password is entered without echo.

   Note  that  the  specified credentials are only used to authenticate against target registries.  They are not used for mirrors or when the registry gets rewritten (see containers-reg‐
   istries.conf(5)); to authenticate against those consider using a containers-auth.json(5) file.

--decryption-key=key[:passphrase]

   The [key[:passphrase]] to be used for decryption of images. Key can point to keys and/or certificates. Decryption is tried with all keys. If the key is protected by a  passphrase,  it
   is required to be passed in the argument and omitted otherwise.

--device=host-device[:container-device][:permissions]

   Add a host device to the container. Optional permissions parameter can be used to specify device permissions by combining r for read, w for write, and m for mknod(2).

   Example: --device=/dev/sdc:/dev/xvdc:rwm.

   Note: if host-device is a symbolic link then it is resolved first.  The container only stores the major and minor numbers of the host device.

   Podman may load kernel modules required for using the specified device. The devices that Podman loads modules for when necessary are: /dev/fuse.

   In  rootless  mode, the new device is bind mounted in the container from the host rather than Podman creating it within the container space. Because the bind mount retains its SELinux
   label on SELinux systems, the container can get permission denied when accessing the mounted device. Modify SELinux settings to allow containers to use all device labels via the  fol‐
   lowing command:

   $ sudo setsebool -P  container_use_devices=true

   Note:  if  the user only has access rights via a group, accessing the device from inside a rootless container fails. The crun(1) runtime offers a workaround for this by adding the op‐
   tion --annotation run.oci.keep_original_groups=1.

--disable-compression, -D

   Don't compress filesystem layers when building the image unless it is required by the location where the image is being written.  This is the default setting, because image layers are
   compressed automatically when they are pushed to registries, and images being written to local storage only need to be decompressed again to be stored.  Compression can be  forced  in
   all cases by specifying --disable-compression=false.

--dns=ipaddr

   Set custom DNS servers.

   This  option  can  be  used  to override the DNS configuration passed to the container. Typically this is necessary when the host DNS configuration is invalid for the container (e.g.,
   127.0.0.1). When this is the case the --dns flag is necessary for every run.

   The special value none can be specified to disable creation of /etc/resolv.conf in the container by Podman.  The /etc/resolv.conf file in the image is used without changes.

   This option cannot be combined with --network that is set to none.

   Note: this option takes effect only during RUN instructions in the build.  It does not affect /etc/resolv.conf in the final image.

--dns-option=option

   Set custom DNS options to be used during the build.

--dns-search=domain

   Set custom DNS search domains to be used during the build.

--env=env[=value]

   Add a value (e.g. env=value) to the built image.  Can be used multiple times.  If neither = nor a value are specified, but env is set in the current environment, the  value  from  the
   current environment is added to the image.  To remove an environment variable from the built image, use the --unsetenv option.

--farm

   This option specifies the name of the farm to be used in the build process.

   This option specifies the name of the farm to be used in the build process.

--file, -f=Containerfile

   Specifies  a Containerfile which contains instructions for building the image, either a local file or an http or https URL.  If more than one Containerfile is specified, FROM instruc‐
   tions are only be accepted from the last specified file.

   If a build context is not specified, and at least one Containerfile is a local file, the directory in which it resides is used as the build context.

   Specifying the option -f - causes the Containerfile contents to be read from stdin.

--force-rm

   Always remove intermediate containers after a build, even if the build fails (default true).

--format

   Control the format for the built image's manifest and configuration data.  Recognized formats include oci (OCI image-spec v1.0, the default) and docker (version 2, using schema format
   2 for the manifest).

   Note: You can also override the default format by setting the BUILDAH_FORMAT environment variable.  export BUILDAH_FORMAT=docker

--from

   Overrides the first FROM instruction within the Containerfile.  If there are multiple FROM instructions in a Containerfile, only the first is changed.

   With the remote podman client, not all container transports work as expected. For example, oci-archive:/x.tar references /x.tar on the remote machine instead of on  the  client.  When
   using podman remote clients it is best to restrict use to containers-storage, and docker:// transports.

--group-add=group | keep-groups

   Assign additional groups to the primary user running within the container process.

          • keep-groups is a special flag that tells Podman to keep the supplementary group access.

   Allows container to use the user's supplementary group access. If file systems or devices are only accessible by the rootless user's group, this flag tells the OCI runtime to pass the
   group  access  into  the container. Currently only available with the crun OCI runtime. Note: keep-groups is exclusive, other groups cannot be specified with this flag. (Not available
   for remote commands, including Mac and Windows (excluding WSL2) machines)

--help, -h

   Print usage statement

--hooks-dir=path

   Each *.json file in the path configures a hook for buildah build containers. For more details on the syntax of the JSON files and the semantics of hook  injection.  Buildah  currently
   support both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is deprecated.

   This option may be set multiple times; paths from later options have higher precedence.

   For the annotation conditions, buildah uses any annotations set in the generated OCI configuration.

   For  the bind-mount conditions, only mounts explicitly requested by the caller via --volume are considered. Bind mounts that buildah inserts by default (e.g. /dev/shm) are not consid‐
   ered.

   If --hooks-dir is unset for root callers, Buildah currently defaults to /usr/share/containers/oci/hooks.d and /etc/containers/oci/hooks.d in  order  of  increasing  precedence.  Using
   these defaults is deprecated. Migrate to explicitly setting --hooks-dir.

--http-proxy

   By  default  proxy  environment  variables  are passed into the container if set for the Podman process. This can be disabled by setting the value to false.  The environment variables
   passed in include http_proxy, https_proxy, ftp_proxy, no_proxy, and also the upper case versions of those. This option is only needed when the host system must use  a  proxy  but  the
   container  does  not  use  any proxy. Proxy environment variables specified for the container in any other way overrides the values that have been passed through from the host. (Other
   ways to specify the proxy for the container include passing the values with the --env flag, or hard coding the proxy environment at container build time.)  When used with  the  remote
   client it uses the proxy environment variables that are set on the server process.

   Defaults to true.

--identity-label

   Adds default identity label io.buildah.version if set. (default true).

--ignorefile

   Path to an alternative .containerignore file.

--iidfile=ImageIDfile

   Write the built image's ID to the file.  When --platform is specified more than once, attempting to use this option triggers an error.

--ipc=how

   Sets  the  configuration  for  IPC namespaces when handling RUN instructions.  The configured value can be "" (the empty string) or "container" to indicate that a new IPC namespace is
   created, or it can be "host" to indicate that the IPC namespace in which podman itself is being run is reused, or it can be the path to an IPC namespace which is already in use by an‐
   other process.

--isolation=type

   Controls what type of isolation is used for running processes as part of RUN instructions.  Recognized types include oci (OCI-compatible runtime, the default), rootless  (OCI-compati‐
   ble  runtime invoked using a modified configuration and its --rootless option enabled, with --no-new-keyring --no-pivot added to its create invocation, with network and UTS namespaces
   disabled, and IPC, PID, and user namespaces enabled; the default for unprivileged users), and chroot (an internal wrapper that leans more toward chroot(1) than container technology).

   Note: You can also override the default isolation type by setting the BUILDAH_ISOLATION environment variable.  export BUILDAH_ISOLATION=oci