Document .build for Image .container option

$NAME.build is supported in .container to automatically build the
local image. This needs to be documented.

Also fix up other special cases to look the same in the man page.

Fixes: https://www.reddit.com/r/podman/comments/1hmhhhi/quadlet_build_units/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
This commit is contained in:
Daniel J Walsh
2025-01-02 13:51:24 -05:00
parent 03cccc7fb6
commit 418ea52e06

View File

@ -614,10 +614,10 @@ performance and robustness reasons.
The format of the name is the same as when passed to `podman pull`. So, it supports using
`:tag` or digests to guarantee the specific image version.
As a special case, if the `name` of the image ends with `.image`, Quadlet will use the image
pulled by the corresponding `.image` file, and the generated systemd service contains
a dependency on the `$name-image.service`.
Note that the corresponding `.image` file must exist.
Special Cases:
* If the `name` of the image ends with `.image`, Quadlet will use the image pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note that the corresponding `.image` file must exist.
* If the `name` of the image ends with `.build`, Quadlet will use the image built by the corresponding `.build` file, and the generated systemd service contains a dependency on the `$name-build.service`. Note: the corresponding `.build` file must exist.
### `IP=`
@ -657,11 +657,12 @@ Attach a filesystem mount to the container.
This is equivalent to the Podman `--mount` option, and
generally has the form `type=TYPE,TYPE-SPECIFIC-OPTION[,...]`.
There are two special cases.
1. For `type=volume`, if `source` ends with `.volume`, the Podman named volume generated by the corresponding `.volume` file is used.
2. For `type=image`, if `source` ends with `.image`, the image generated by the corresponding `.image` file is used.
Special cases:
In both cases, the generated systemd service will contain a dependency on the service generated for the corresponding unit.
* For `type=volume`, if `source` ends with `.volume`, the Podman named volume generated by the corresponding `.volume` file is used.
* For `type=image`, if `source` ends with `.image`, the image generated by the corresponding `.image` file is used.
In both cases, the generated systemd service will contain a dependency on the service generated for the corresponding unit. Note: the corresponding `.volume` or `.image` file must exist.
This key can be listed multiple times.
@ -671,14 +672,16 @@ Specify a custom network for the container. This has the same format as the `--n
to `podman run`. For example, use `host` to use the host network in the container, or `none` to
not set up networking in the container.
As a special case, if the `name` of the network ends with `.network`, a Podman network called
Special cases:
* If the `name` of the network ends with `.network`, a Podman network called
`systemd-$name` is used, and the generated systemd service contains
a dependency on the `$name-network.service`. Such a network can be automatically
created by using a `$name.network` Quadlet file.
created by using a `$name.network` Quadlet file. Note: the corresponding `.network` file must exist.
Another special case is that if the `name` ends with `.container`,
* If the `name` ends with `.container`,
the container will reuse the network stack of another container created by `$name.container`.
The generated systemd service contains a dependency on `$name.service`.
The generated systemd service contains a dependency on `$name.service`. Note: the corresponding `.container` file must exist.
This key can be listed multiple times.
@ -910,10 +913,9 @@ generally has the form `[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]`.
If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file.
As a special case, if `SOURCE-VOLUME` ends with `.volume`, a Podman named volume called
`systemd-$name` is used as the source, and the generated systemd service contains
a dependency on the `$name-volume.service`. Such a volume can be automatically be lazily
created by using a `$name.volume` Quadlet file.
Special case:
* If `SOURCE-VOLUME` ends with `.volume`, a Podman named volume called `systemd-$name` is used as the source, and the generated systemd service contains a dependency on the `$name-volume.service`. Note that the corresponding `.volume` file must exist.
This key can be listed multiple times.
@ -1029,10 +1031,11 @@ Specify a custom network for the pod.
This has the same format as the `--network` option to `podman pod create`.
For example, use `host` to use the host network in the pod, or `none` to not set up networking in the pod.
As a special case, if the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit.
If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used.
The generated systemd service contains a dependency on the service unit generated for that `.network` unit,
or on `$name-network.service` if the `.network` unit is not found
Special case:
* If the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used.
The generated systemd service contains a dependency on the service unit generated for that `.network` unit. Note: the corresponding `.network` file must exist.
This key can be listed multiple times.
@ -1128,10 +1131,12 @@ generally has the form `[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]`.
If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file.
As a special case, if `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit.
If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used.
Special case:
* If `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used. Note: the corresponding `.volume` file must exist.
The generated systemd service contains a dependency on the service unit generated for that `.volume` unit,
or on `$name-volume.service` if the `.volume` unit is not found
or on `$name-volume.service` if the `.volume` unit is not found.
This key can be listed multiple times.
@ -1226,10 +1231,9 @@ Specify a custom network for the container. This has the same format as the `--n
to `podman kube play`. For example, use `host` to use the host network in the container, or `none` to
not set up networking in the container.
As a special case, if the `name` of the network ends with `.network`, a Podman network called
`systemd-$name` is used, and the generated systemd service contains
a dependency on the `$name-network.service`. Such a network can be automatically
created by using a `$name.network` Quadlet file.
Special case:
* If the `name` of the network ends with `.network`, a Podman network called `systemd-$name` is used, and the generated systemd service contains a dependency on the `$name-network.service`. Such a network can be automatically created by using a `$name.network` Quadlet file. Note: the corresponding `.network` file must exist.
This key can be listed multiple times.
@ -1515,10 +1519,10 @@ performance and robustness reasons.
The format of the name is the same as when passed to `podman pull`. So, it supports using
`:tag` or digests to guarantee the specific image version.
As a special case, if the `name` of the image ends with `.image`, Quadlet will use the image
pulled by the corresponding `.image` file, and the generated systemd service contains
a dependency on the `$name-image.service`.
Note that the corresponding `.image` file must exist.
Special case:
* If the `name` of the image ends with `.image`, Quadlet will use the image
pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note: the corresponding `.image` file must exist.
### `Label=`
@ -1715,11 +1719,9 @@ Sets the configuration for network namespaces when handling RUN instructions. Th
format as the `--network` option to `podman build`. For example, use `host` to use the host network,
or `none` to not set up networking.
As a special case, if the `name` of the network ends with `.network`, Quadlet will look for the
corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the
Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the
service unit generated for that `.network` unit, or on `$name-network.service` if the `.network`
unit is not found.
Special case:
* If the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.network` unit, or on `$name-network.service` if the `.network` unit is not found. Note: the corresponding `.network` file must exist.
This key can be listed multiple times.
@ -1797,11 +1799,9 @@ the `--volume` option of `podman build`, and generally has the form
If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file.
As a special case, if `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding
`.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit,
otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the
service unit generated for that `.volume` unit, or on `$name-volume.service` if the `.volume` unit
is not found
Special case:
* If `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.volume` unit, or on `$name-volume.service` if the `.volume` unit is not found. Note: the corresponding `.volume` file must exist.
This key can be listed multiple times.