opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-05-17 15:18:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

Quadlet: Add support for .build files

Browse Source 
.build files allow to build an image via Quadlet. The keys from a .build
file are translated to arguments of a `podman build` command by Quadlet.

Minimal keys for .build files are `ImageTag=` and a context directory,
see `SetWorkingDirectory=`, or a `File=` pointing to a Containerfile.

After sorting .build files into the Quadlet dependency order, there
remains a possible dependency cycle issue between .volume and .build
files: A .volume can have `Image=some.build`, and a .build can have
`Volume=some.volume:/some/volume`.

We solve this dependency cycle by prefilling resourceNames with all
image names from .build files before converting all the unit files.

This results in an issue for the test suite though: For .volume's
depending on *.image or *.build, we need to copy these additional
dependencies to the test's quadletDir, otherwise the test will fail.
This is necessary, because `handleImageSource()` actually needs to know
the image name defined in the referenced *.{build,image} file. It cannot
fall back on the default names, as it is done for networks or volumes,
for example.

Signed-off-by: Johannes Maibaum <jmaibaum@gmail.com>
This commit is contained in:
Johannes Maibaum
2024-05-14 00:09:46 +02:00
parent 7ec22abb1c
commit 9f823ecb25
45 changed files with 985 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

275
docs/source/markdown/podman-systemd.unit.5.md
View File

@ -6,7 +6,7 @@ podman\-systemd.unit - systemd units using Podman Quadlet
## SYNOPSIS
*name*.container, *name*.volume, *name*.network, *name*.kube *name*.image, *name*.pod
*name*.container, *name*.volume, *name*.network, *name*.kube *name*.image, *name*.build *name*.pod
### Podman rootful unit search path
@ -30,7 +30,7 @@ Symbolic links below the search paths are not supported.
## DESCRIPTION
Podman supports starting containers (and creating volumes) via systemd by using a
Podman supports building, and starting containers (and creating volumes) via systemd by using a
[systemd generator](https://www.freedesktop.org/software/systemd/man/systemd.generator.html).
These files are read during boot (and when `systemctl daemon-reload` is run) and generate
corresponding regular systemd service unit files. Both system and user systemd units are supported.
@ -39,7 +39,7 @@ the [Service] table and [Install] tables pass directly to systemd and are handle
See systemd.unit(5) man page for more information.
The Podman generator reads the search paths above and reads files with the extensions `.container`
`.volume`, `.network`, `.pod` and `.kube`, and for each file generates a similarly named `.service` file. Be aware that
`.volume`, `.network`, `.build`, `.pod` and `.kube`, and for each file generates a similarly named `.service` file. Be aware that
existing vendor services (i.e., in `/usr/`) are replaced if they have the same name. The generated unit files can
be started and managed with `systemctl` like any other systemd service. `systemctl {--user} list-unit-files`
lists existing unit files on the system.
@ -65,7 +65,7 @@ session gets started. For unit files placed in subdirectories within
/etc/containers/systemd/user/${UID}/ and the other user unit search paths,
Quadlet will recursively search and run the unit files present in these subdirectories.
Note: When a Quadlet is starting, Podman often pulls one more container images which may take a considerable amount of time.
Note: When a Quadlet is starting, Podman often pulls or builds one more container images which may take a considerable amount of time.
Systemd defaults service start time to 90 seconds, or fails the service. Pre-pulling the image or extending
the systemd timeout time for the service using the *TimeoutStartSec* Service option can fix the problem.
@ -82,7 +82,7 @@ Quadlet requires the use of cgroup v2, use `podman info --format {{.Host.Cgroups
By default, the `Type` field of the `Service` section of the Quadlet file does not need to be set.
Quadlet will set it to `notify` for `.container` and `.kube` files,
`forking` for `.pod` files, and `oneshot` for `.volume`, `.network` and `.image` files.
`forking` for `.pod` files, and `oneshot` for `.volume`, `.network`, `.build`, and `.image` files.
However, `Type` may be explicitly set to `oneshot` for `.container` and `.kube` files when no containers are expected
to run once `podman` exits.
@ -1324,6 +1324,251 @@ The (optional) name of the Podman volume. If this is not specified, the default
`systemd-%N` is used, which is the same as the unit name but with a `systemd-` prefix to avoid
conflicts with user-managed volumes.
## Build units [Build]
Build files are named with a `.build` extension and contain a section `[Build]` describing the image
build command. The generated service is a one-time command that ensures that the image is built on
the host from a supplied Containerfile and context directory. Subsequent (re-)starts of the
generated built service will usually finish quickly, as image layer caching will skip unchanged
build steps.
A minimal `.build` unit needs at least the `ImageTag=` key, and either of `File=` or
`SetWorkingDirectory=` keys.
Using build units allows containers and volumes to depend on images being built locally. This can be
interesting for creating container images not available on container registries, or for local
testing and development.
Valid options for `[Build]` are listed below:
| **[Build] options** | **podman build equivalent** |
|-------------------------------------|---------------------------------------------|
| Annotation=annotation=value | --annotation=annotation=value |
| Arch=aarch64 | --arch=aarch64 |
| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json |
| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf |
| DNS=192.168.55.1 | --dns=192.168.55.1 |
| DNSOption=ndots:1 | --dns-option=ndots:1 |
| DNSSearch=foo.com | --dns-search=foo.com |
| Environment=foo=bar | --env foo=bar |
| File=/path/to/Containerfile | --file=/path/to/Containerfile |
| ForceRM=false | --force-rm=false |
| GlobalArgs=--log-level=debug | --log-level=debug |
| GroupAdd=keep-groups | --group-add=keep-groups |
| ImageTag=localhost/imagename | --tag=localhost/imagename |
| Label=label | --label=label |
| Network=host | --network=host |
| PodmanArgs=--add-host foobar | --add-host foobar |
| Pull=never | --pull=never |
| Secret=secret | --secret=id=mysecret,src=path |
| SetWorkingDirectory=unit | Set `WorkingDirectory` of systemd unit file |
| Target=my-app | --target=my-app |
| TLSVerify=false | --tls-verify=false |
| Variant=arm/v7 | --variant=arm/v7 |
| Volume=/source:/dest | --volume /source:/dest |
### `Annotation=`
Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple
times.
This is equivalant to the `--annotation` option of `podman build`.
### `Arch=`
Override the architecture, defaults to hosts', of the image to be built.
This is equivalent to the `--arch` option of `podman build`.
### `AuthFile=`
Path of the authentication file.
This is equivalent to the `--authfile` option of `podman build`.
### `ContainersConfModule=`
Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option.
This key can be listed multiple times.
### `DNS=`
Set network-scoped DNS resolver/nameserver for the build container.
This key can be listed multiple times.
This is equivalent to the `--dns` option of `podman build`.
### `DNSOption=`
Set custom DNS options.
This key can be listed multiple times.
This is equivalent to the `--dns-option` option of `podman build`.
### `DNSSearch=`
Set custom DNS search domains. Use **DNSSearch=.** to remove the search domain.
This key can be listed multiple times.
This is equivalent to the `--dns-search` option of `podman build`.
### `Environment=`
Add a value (e.g. env=*value*) to the built image. This uses the same format as [services in
systemd](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Environment=) and can be
listed multiple times.
### `File=`
Specifies a Containerfile which contains instructions for building the image. A URL starting with
`http(s)://` allows you to specify a remote Containerfile to be downloaded. Note that for a given
relative path to a Containerfile, or when using a `http(s)://` URL, you also must set
`SetWorkingDirectory=` in order for `podman build` to find a valid context directory for the
resources specified in the Containerfile.
Note that setting a `File=` field is mandatory for a `.build` file, unless `SetWorkingDirectory` (or
a `WorkingDirectory` in the `Service` group) has also been set.
This is equivalent to the `--file` option of `podman build`.
### `ForceRM=`
Always remove intermediate containers after a build, even if the build fails (default true).
This is equivalent to the `--force-rm` option of `podman build`.
### `GlobalArgs=`
This key contains a list of arguments passed directly between `podman` and `build` in the generated
file. It can be used to access Podman features otherwise unsupported by the generator. Since the
generator is unaware of what unexpected interactions can be caused by these arguments, it is not
recommended to use this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
### `GroupAdd=`
Assign additional groups to the primary user running within the container process. Also supports the
`keep-groups` special flag.
This is equivalent to the `--group-add` option of `podman build`.
### `ImageTag=`
Specifies the name which is assigned to the resulting image if the build process completes
successfully.
This is equivalent to the `--tag` option of `podman build`.
### `Label=`
Add an image *label* (e.g. label=*value*) to the image metadata. Can be used multiple times.
This is equivalent to the `--label` option of `podman build`.
### `Network=`
Sets the configuration for network namespaces when handling RUN instructions. This has the same
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.
This key can be listed multiple times.
### `PodmanArgs=`
This key contains a list of arguments passed directly to the end of the `podman build` command
in the generated file (right before the image name in the command line). It can be used to
access Podman features otherwise unsupported by the generator. Since the generator is unaware
of what unexpected interactions can be caused by these arguments, it is not recommended to use
this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
### `Pull=`
Set the image pull policy.
This is equivalent to the `--pull` option of `podman build`.
### `Secret=`
Pass secret information used in Containerfile build stages in a safe way.
This is equivalent to the `--secret` option of `podman build` and generally has the form
`secret[,opt=opt ...]`.
### `SetWorkingDirectory=`
Provide context (a working directory) to `podman build`. Supported values are a path, a URL, or the
special keys `file` or `unit` to set the context directory to the parent directory of the file from
the `File=` key or to that of the Quadlet `.build` unit file, respectively. This allows Quadlet to
resolve relative paths.
When using one of the special keys (`file` or `unit`), the `WorkingDirectory` field of the `Service`
group of the Systemd service unit will also be set to accordingly. Alternatively, users can
explicitly set the `WorkingDirectory` field of the `Service` group in the `.build` file. Please note
that if the `WorkingDirectory` field of the `Service` group is set by the user, Quadlet will not
overwrite it even if `SetWorkingDirectory` is set to `file` or `unit`.
By providing a URL to `SetWorkingDirectory=` you can instruct `podman build` to clone a Git
repository or download an archive file extracted to a temporary location by `podman build` as build
context. Note that in this case, the `WorkingDirectory` of the Systemd service unit is left
untouched by Quadlet.
Note that providing context directory is mandatory for a `.build` file, unless a `File=` key has
also been provided.
### `Target=`
Set the target build stage to build. Commands in the Containerfile after the target stage are
skipped.
This is equivalent to the `--target` option of `podman build`.
### `TLSVerify=`
Require HTTPS and verification of certificates when contacting registries.
This is equivalent to the `--tls-verify` option of `podman build`.
### `Variant=`
Override the default architecture variant of the container image to be built.
This is equivalent to the `--variant` option of `podman build`.
### `Volume=`
Mount a volume to containers when executing RUN instructions during the build. This is equivalent to
the `--volume` option of `podman build`, and 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. 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
This key can be listed multiple times.
## Image units [Image]
Image files are named with a `.image` extension and contain a section `[Image]` describing the
@ -1510,6 +1755,26 @@ Yaml=/opt/k8s/deployment.yml
WantedBy=multi-user.target default.target
```
Example for locally built image to be used in a container:
`test.build`
```
[Build]
# Tag the image to be built
ImageTag=localhost/imagename
# Set the working directory to the path of the unit file,
# expecting to find a Containerfile/Dockerfile
# + other files needed to build the image
SetWorkingDirectory=unit
```
`test.container`
```
[Container]
Image=test.build
```
Example `test.volume`:
```