Merge pull request #20051 from umohnani8/fbuild-doc

[CI:DOCS] Add podman farm build doc

docs/source/markdown/options/annotation.image.md

@@ -0,0 +1,11 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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.

docs/source/markdown/options/authfile.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman auto update, build, container runlabel, create, image sign, kube play, login, logout, manifest add, manifest inspect, manifest push, pull, push, run, search
+####>   podman auto update, build, container runlabel, create, farm build, image sign, kube play, login, logout, manifest add, manifest inspect, manifest push, pull, push, run, search
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--authfile**=*path*

docs/source/markdown/options/build-arg-file.md

@@ -0,0 +1,22 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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`.

docs/source/markdown/options/build-arg.md

@@ -0,0 +1,8 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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.

docs/source/markdown/options/build-context.md

@@ -0,0 +1,30 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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 instruction.
+
+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 Winows) 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:
+
+```dockerfile
+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

docs/source/markdown/options/cache-from.md

@@ -0,0 +1,21 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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 actually
+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
+
+```bash
+# 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.

docs/source/markdown/options/cache-to.md

@@ -0,0 +1,19 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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
+
+```bash
+# 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.

docs/source/markdown/options/cache-ttl.md

@@ -0,0 +1,12 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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 dones not want to use cache at all.

docs/source/markdown/options/cap-add.image.md

@@ -0,0 +1,10 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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.

docs/source/markdown/options/cap-drop.image.md

@@ -0,0 +1,16 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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.

docs/source/markdown/options/cert-dir.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, container runlabel, image sign, kube play, login, manifest add, manifest push, pull, push, search
+####>   podman build, container runlabel, farm build, image sign, kube play, login, manifest add, manifest push, pull, push, search
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--cert-dir**=*path*

docs/source/markdown/options/cgroup-parent.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, create, pod clone, pod create, run
+####>   podman build, create, farm build, pod clone, pod create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--cgroup-parent**=*path*

docs/source/markdown/options/cgroupns.image.md

@@ -0,0 +1,10 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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.

docs/source/markdown/options/cpp-flag.md

@@ -0,0 +1,7 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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").

docs/source/markdown/options/cpu-period.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, container clone, create, run, update
+####>   podman build, container clone, create, farm build, run, update
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--cpu-period**=*limit*

docs/source/markdown/options/cpu-quota.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, container clone, create, run, update
+####>   podman build, container clone, create, farm build, run, update
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--cpu-quota**=*limit*

docs/source/markdown/options/cpu-shares.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, container clone, create, pod clone, pod create, run, update
+####>   podman build, container clone, create, farm build, pod clone, pod create, run, update
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--cpu-shares**, **-c**=*shares*

docs/source/markdown/options/cpuset-cpus.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, container clone, create, pod clone, pod create, run, update
+####>   podman build, container clone, create, farm build, pod clone, pod create, run, update
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--cpuset-cpus**=*number*

docs/source/markdown/options/cpuset-mems.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, container clone, create, pod clone, pod create, run, update
+####>   podman build, container clone, create, farm build, pod clone, pod create, run, update
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--cpuset-mems**=*nodes*

docs/source/markdown/options/creds.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, container runlabel, kube play, manifest add, manifest push, pull, push, search
+####>   podman build, container runlabel, farm build, kube play, manifest add, manifest push, pull, push, search
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--creds**=*[username[:password]]*

docs/source/markdown/options/decryption-key.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman create, pull, run
+####>   podman build, create, farm build, pull, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--decryption-key**=*key[:passphrase]*

docs/source/markdown/options/device.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, create, pod clone, pod create, run
+####>   podman build, create, farm build, pod clone, pod create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--device**=*host-device[:container-device][:permissions]*

docs/source/markdown/options/disable-compression.md

@@ -0,0 +1,12 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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**.

docs/source/markdown/options/dns-option.image.md

@@ -0,0 +1,7 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--dns-option**=*option*
+
+Set custom DNS options to be used during the build.

docs/source/markdown/options/dns-search.image.md

@@ -0,0 +1,7 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--dns-search**=*domain*
+
+Set custom DNS search domains to be used during the build.

docs/source/markdown/options/dns.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, create, run
+####>   podman build, create, farm build, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--dns**=*ipaddr*

docs/source/markdown/options/env.image.md

@@ -0,0 +1,11 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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.

docs/source/markdown/options/file.md

@@ -0,0 +1,16 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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* instructions 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.

docs/source/markdown/options/force-rm.md

@@ -0,0 +1,7 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--force-rm**
+
+Always remove intermediate containers after a build, even if the build fails (default true).

docs/source/markdown/options/format.md

@@ -0,0 +1,12 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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`

docs/source/markdown/options/from.md

@@ -0,0 +1,13 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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*.

docs/source/markdown/options/group-add.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman create, run
+####>   podman build, create, farm build, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--group-add**=*group* | *keep-groups*

docs/source/markdown/options/help.md

@@ -0,0 +1,7 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--help**, **-h**
+
+Print usage statement

docs/source/markdown/options/hooks-dir.md

@@ -0,0 +1,15 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--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 considered.
+
+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.

docs/source/markdown/options/http-proxy.md

@@ -1,5 +1,5 @@
 ####> This option file is used in:
-####>   podman build, create, run
+####>   podman build, create, farm build, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
 #### **--http-proxy**

docs/source/markdown/options/identity-label.md

@@ -0,0 +1,7 @@
+####> This option file is used in:
+####>   podman build, farm build
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+#### **--identity-label**
+
+Adds default identity label `io.buildah.version` if set. (default true).