Merge pull request #24926 from rhatdan/quadlet

Document .build for Image .container option

docs/source/markdown/podman-systemd.unit.5.md

@@ -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:
+
+* 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.
+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.