mirror of
https://github.com/containers/podman.git
synced 2025-06-11 18:28:41 +08:00
quadlet: Add documentation about template use to manpage
Signed-off-by: Alexander Larsson <alexl@redhat.com>
This commit is contained in:
@ -109,16 +109,86 @@ WantedBy=default.target
|
|||||||
|
|
||||||
Currently, only the `Alias`, `WantedBy` and `RequiredBy` keys are supported.
|
Currently, only the `Alias`, `WantedBy` and `RequiredBy` keys are supported.
|
||||||
|
|
||||||
|
The Install section can be part of the main file, or it can be in a
|
||||||
|
separate drop-in file as described above. The latter allows you to
|
||||||
|
install an non-enabled unit and then later enabling it by installing
|
||||||
|
the drop-in.
|
||||||
|
|
||||||
|
|
||||||
**NOTE:** To express dependencies between containers, use the generated names of the service. In other
|
**NOTE:** To express dependencies between containers, use the generated names of the service. In other
|
||||||
words `WantedBy=other.service`, not `WantedBy=other.container`. The same is
|
words `WantedBy=other.service`, not `WantedBy=other.container`. The same is
|
||||||
true for other kinds of dependencies, too, like `After=other.service`.
|
true for other kinds of dependencies, too, like `After=other.service`.
|
||||||
|
|
||||||
|
### Template files
|
||||||
|
|
||||||
|
Systemd supports a concept of [template files](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html#Service%20Templates).
|
||||||
|
They are units with names of the form "basename@instancename.service"
|
||||||
|
when they are running, but that can be instantiated multiple times
|
||||||
|
from a single "basename@.service" file. The individual instances can
|
||||||
|
also be different by using drop-in files with the full instance name.
|
||||||
|
|
||||||
|
Quadlets support these in two ways. First of all, a quadlet unit with
|
||||||
|
a template form will generate a systemd service with a template form,
|
||||||
|
and the template systemd service can be used as a regular template.
|
||||||
|
For example, "foo@.container" will generate "foo@.service" and you can
|
||||||
|
then "systemctl start foo@bar.service".
|
||||||
|
|
||||||
|
Secondly, if you make a symlink like "foo@instance.container", that
|
||||||
|
will generate an instantiated template file. When generating this file
|
||||||
|
quadlet will read drop-in files both from the instanced directory
|
||||||
|
(foo@instance.container.d) and the template directory
|
||||||
|
(foo@.container.d). This allows customization of individual instances.
|
||||||
|
|
||||||
|
Instanced template files (like `foo@bar.container`) can be enabled
|
||||||
|
just like non-templated ones. However, templated ones
|
||||||
|
(`foo@.container`) are different, because they need to be
|
||||||
|
instantiated. If the `[Install]` section contains a `DefaultInstance=`
|
||||||
|
key, then that instance will be enabled, but if not, nothing will
|
||||||
|
happen and the options will only be used as the default for units
|
||||||
|
that are instantiated using symlinks.
|
||||||
|
|
||||||
|
An example template file `sleep@.container` might look like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
[Unit]
|
||||||
|
Description=A templated sleepy container
|
||||||
|
|
||||||
|
[Container]
|
||||||
|
Image=quay.io/fedora/fedora
|
||||||
|
Exec=sleep %i
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
# Restart service when sleep finishes
|
||||||
|
Restart=always
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
DefaultInstance=100
|
||||||
|
```
|
||||||
|
|
||||||
|
If this is installed, then on boot there will be a `sleep@100.service`
|
||||||
|
running that sleeps for 100 seconds. You can then do something like
|
||||||
|
`systemctl start sleep@50.service` to start another instance that
|
||||||
|
sleeps 50 seconds, or alternatively another service can start it via a
|
||||||
|
dependency like `Wants=sleep@50.service`.
|
||||||
|
|
||||||
|
In addition, if you do `ln -s sleep@.container sleep@10.container` you
|
||||||
|
will also have a 10 second sleep running at boot. And, if you want
|
||||||
|
that particular instance to be running with another image, you can
|
||||||
|
create a drop-in file like `sleep@10.container.d/10-image.conf`:
|
||||||
|
```
|
||||||
|
[Container]
|
||||||
|
Image=quay.io/centos/centos
|
||||||
|
```
|
||||||
|
|
||||||
### Debugging unit files
|
### Debugging unit files
|
||||||
|
|
||||||
After placing the unit file in one of the unit search paths (mentioned above), you can start it with
|
After placing the unit file in one of the unit search paths (mentioned
|
||||||
`systemctl start {--user}`. If it fails with "Failed to start example.service: Unit example.service not found.",
|
above), you can start it with `systemctl start {--user}`. If it fails
|
||||||
then it is possible that you used incorrect syntax or you used an option from a newer version of Podman
|
with "Failed to start example.service: Unit example.service not
|
||||||
Quadlet and the generator failed to create a service file.
|
found.", then it is possible that you used incorrect syntax or you
|
||||||
|
used an option from a newer version of Podman Quadlet and the
|
||||||
|
generator failed to create a service file.
|
||||||
|
|
||||||
View the generated files and/or error messages with:
|
View the generated files and/or error messages with:
|
||||||
```
|
```
|
||||||
|
Reference in New Issue
Block a user