Document packaging process
High-level overview of packaging, intended for Linux distros. Closes: RUN-1356 Signed-off-by: Ed Santiago <santiago@redhat.com>
This commit is contained in:
Ed Santiago
parent
b65f3b19a5
commit
a92958eb0c
|
|
@ -1,101 +1,111 @@
|
||||||
# Podman Packaging
|
# Podman Packaging
|
||||||
|
|
||||||
This document is currently written with Fedora as a reference, intended for use
|
This document is intended for Podman *packagers*: those very few individuals
|
||||||
by packagers of other distros as well as package users.
|
responsible for building and shipping Podman on Linux distributions.
|
||||||
|
|
||||||
## Fedora Users
|
Document verified accurate as of Podman 5.2, 2024-10-16.
|
||||||
Podman v4 is available as an official Fedora package on Fedora 36 and rawhide.
|
|
||||||
This version of Podman brings with it a new container stack called
|
|
||||||
Netavark which serves as a replacement for CNI plugins
|
|
||||||
(containernetworking-plugins on Fedora), as well as Aardvark-dns, the
|
|
||||||
authoritative DNS server for container records.
|
|
||||||
|
|
||||||
Both Netavark and Aardvark-dns are available as official Fedora packages on
|
## Building Podman
|
||||||
Fedora 35 and newer versions and form the default network stack for new
|
|
||||||
installations of Podman 4.0.
|
|
||||||
|
|
||||||
On Fedora 36 and newer, fresh installations of Podman v4 will
|
This document assumes you are able to build executables up to and
|
||||||
automatically install Aardvark-dns along with Netavark.
|
including `make install`.
|
||||||
|
See [Building from Source](https://podman.io/docs/installation#building-from-source)
|
||||||
|
on podman.io for possibly-outdated instructions.
|
||||||
|
|
||||||
To install Podman v4:
|
## Package contents
|
||||||
|
|
||||||
```console
|
Everything installed by `make install`, obviously.
|
||||||
$ sudo dnf install podman
|
|
||||||
|
Upstream splits Podman into multiple subpackages and we encourage you
|
||||||
|
to consider doing likewise: some users may not want `podman-remote`
|
||||||
|
or `-machine` or the test suite.
|
||||||
|
|
||||||
|
The best starting point is the
|
||||||
|
[RPM spec file](https://github.com/containers/podman/blob/main/rpm/podman.spec).
|
||||||
|
This illustrates the subpackage breakdown as well as top-level dependencies.
|
||||||
|
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
Podman requires a *runtime*, a *runtime monitor*, a *pause process*,
|
||||||
|
and *networking tools*. In Fedora, some of these requirements are indirectly
|
||||||
|
specified via [containers-common](https://github.com/containers/common);
|
||||||
|
the nested tree looks like this:
|
||||||
|
```
|
||||||
|
Podman
|
||||||
|
├── Requires: catatonit
|
||||||
|
├── Requires: conmon
|
||||||
|
└── Requires: containers-common-extra
|
||||||
|
├── Requires: crun
|
||||||
|
├── Requires: netavark
|
||||||
|
└── Requires: passt
|
||||||
```
|
```
|
||||||
|
|
||||||
To update Podman from an older version to v4:
|
### Runtime: crun
|
||||||
|
|
||||||
```console
|
The only runtime supported upstream is [crun](https://github.com/containers/crun),
|
||||||
$ sudo dnf update podman
|
but different distros may wish to offer other options to their users. Your package
|
||||||
```
|
must, directly or indirectly, list a runtime prerequisite.
|
||||||
|
|
||||||
**NOTE:** Fedora 35 users will not be able to install Podman v4 using the default yum
|
Heads up: you may end up being responsible for packaging this runtime, or at the
|
||||||
repositories and are recommended to use the COPR repo below:
|
very least working closely with the package maintainer. The best starting point
|
||||||
|
for crun is its
|
||||||
|
[RPM spec file](https://github.com/containers/crun/blob/main/rpm/crun.spec).
|
||||||
|
|
||||||
```console
|
|
||||||
$ sudo dnf copr enable rhcontainerbot/podman4
|
|
||||||
|
|
||||||
# install or update per your needs
|
### Pause process: catatonit
|
||||||
$ sudo dnf install podman
|
|
||||||
```
|
|
||||||
|
|
||||||
After installation, if you would like to migrate all your containers to use
|
The pause process serves as a container `init`, reaping PIDs and handling signals.
|
||||||
Netavark, you will need to set `network_backend = "netavark"` under
|
|
||||||
the `[network]` section in your containers.conf, typically located at:
|
|
||||||
`/usr/share/containers/containers.conf`
|
|
||||||
|
|
||||||
### Testing the latest development version`
|
As of this writing, Podman uses an external tool,
|
||||||
|
[catatonit](https://github.com/openSUSE/catatonit). This may be subject
|
||||||
|
to change in future Podman versions.
|
||||||
|
|
||||||
If you would like to test the latest unreleased upstream code, try the
|
If you need to package catatonit, a good starting point might be its
|
||||||
podman-next COPR
|
[Fedora specfile](https://src.fedoraproject.org/rpms/catatonit/blob/rawhide/f/catatonit.spec).
|
||||||
|
|
||||||
```console
|
|
||||||
$ sudo dnf copr enable rhcontainerbot/podman-next
|
|
||||||
|
|
||||||
$ sudo dnf install podman
|
### Runtime Monitor: conmon
|
||||||
```
|
|
||||||
|
|
||||||
**CAUTION:** The podman-next COPR provides the latest unreleased sources of Podman,
|
The only working monitor is [conmon](https://github.com/containers/conmon).
|
||||||
Netavark and Aardvark-dns as rpms which would override the versions provided by
|
There is a Rust implementation in the works,
|
||||||
the official packages.
|
[conmon-rs](https://github.com/containers/conmon-rs), but efforts
|
||||||
|
to make it work with Podman have stalled for years.
|
||||||
|
|
||||||
## Distro Packagers
|
Heads up: you may end up being responsible for packaging conmon.
|
||||||
|
The best starting point is its
|
||||||
|
[RPM spec file](https://github.com/containers/conmon/blob/main/rpm/conmon.spec).
|
||||||
|
|
||||||
The Fedora packaging sources for Podman are available at the [Podman
|
|
||||||
dist-git](https://src.fedoraproject.org/rpms/podman).
|
|
||||||
|
|
||||||
The main `podman` package no longer explicitly depends on
|
### Networking Tools: netavark, aardvark-dns, passt
|
||||||
containernetworking-plugins. The network stack dependencies are now handled in
|
|
||||||
the [containers-common](https://src.fedoraproject.org/rpms/containers-common)
|
|
||||||
package which allows for a single point of dependency maintenance for Podman
|
|
||||||
and Buildah.
|
|
||||||
|
|
||||||
- containers-common
|
Networking differs between *root* and *rootless*: [passt](https://passt.top/)
|
||||||
```
|
(also referred to as "pasta") is only needed for rootless.
|
||||||
Requires: container-network-stack
|
[netavark](https://github.com/containers/netavark/) and
|
||||||
Recommends: netavark
|
[aardvark-dns](https://github.com/containers/aardvark-dns/)
|
||||||
```
|
are needed for both root and rootless podman.
|
||||||
|
|
||||||
- netavark
|
Heads up: you will probably end up being responsible for packaging
|
||||||
```
|
at least some of these. The best starting points are their respective
|
||||||
Provides: container-network-stack = 2
|
RPM spec files:
|
||||||
```
|
[netavark](https://github.com/containers/netavark/blob/main/rpm/netavark.spec),
|
||||||
|
[aardvark-dns](https://github.com/containers/aardvark-dns/blob/main/rpm/aardvark-dns.spec).
|
||||||
|
|
||||||
- containernetworking-plugins
|
Netavark and aardvark-dns must be packaged in lockstep down
|
||||||
```
|
to the major-minor level: version `X.Y` of either is only
|
||||||
Provides: container-network-stack = 1
|
guaranteed to work with `X.Y` of the other. If you are responsible
|
||||||
```
|
for packaging these, make sure you set up interpackage dependencies
|
||||||
|
appropriately to prevent version mismatches between them.
|
||||||
|
|
||||||
This configuration ensures:
|
## Metapackage: containers-common
|
||||||
- New installations of Podman will always install netavark by default.
|
|
||||||
- The containernetworking-plugins package will not conflict with netavark and
|
|
||||||
users can install them together.
|
|
||||||
|
|
||||||
## Listing bundled dependencies
|
This package provides config files, man pages, and (at the
|
||||||
If you need to list the bundled dependencies in your packaging sources, you can
|
packaging level) dependencies. There are good reasons for
|
||||||
process the `go.mod` file in the upstream source.
|
keeping this as a separate package, the most important one
|
||||||
For example, Fedora's packaging source uses:
|
being that `buildah` and `skopeo` rely on this same content.
|
||||||
|
Also important is the ability for individual distros to
|
||||||
|
fine-tune config settings and dependencies.
|
||||||
|
|
||||||
```
|
You will probably be responsible for packaging this.
|
||||||
$ awk '{print "Provides: bundled(golang("$1")) = "$2}' go.mod | sort | uniq | sed -e 's/-/_/g' -e '/bundled(golang())/d' -e '/bundled(golang(go\|module\|replace\|require))/d'
|
The best starting point is its
|
||||||
```
|
[RPM spec file](https://github.com/containers/common/blob/main/rpm/containers-common.spec).
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue