This source code is notably a command line utility to produce systemd unit files from Open Container Initiative image layouts.
Also useful are the golang libraries provided to:
- walk a directory of OCI image layouts
- extract an OCI image layout
- apply the OCI layers
go get -u github.com/vbatts/oci-systemd-generator
sudo cp $GOPATH/bin/oci-systemd-generator /lib/systemd/system-generators/
The default directory for discovering OCI image layouts (imagelayoutdir
) is
/var/lib/oci/layouts
.
The default directory for extracting these layouts for use (extractsdir
) is
/var/lib/oci/extracts
.
These paths can be overridden by setting values in /etc/oci-generator.conf
,
like:
[system]
imagelayoutdir = /mnt/data/oci/layouts
extractsdir = /mnt/data/oci/extracts
Once the imagelayoutdir
is populated, this oci-systemd-generator
is
intended to only be executed by systemd itself during boot or systemctl daemon-reload
.
For more information on this see systemd.generator(7)
.
Though the tool is usable outside of this. For instance, you can try:
dir=$(mktemp -d)
oci-systemd-generator -debug $dir $dir $dir
find $dir
There are a couple of requirements of the OCI image for a .service
unit file
to be produced for it.
- the layout must be one or more sub directory under
imagelayoutdir
(so that it has a name associated for it) - it must have layers (a rootfs to be used)
- a combination of
Entrypoint
and/orCmd
from the image properties so that there is enough to make anExecStart=
for the.service
unit
If you need fetch OCI image layouts to begin with, using a tool like skopeo to pull container images and set up the OCI image layout will get you started.
skopeo copy docker://myorg/myapp:stable oci:/var/lib/oci/layouts/myorg.com/myapp:stable
The name derived for the .service
unit files produced are derived from the
path to the image layout, relative to the imagelayoutdir
, in reverse domain
name notation.
In example: /var/lib/oci/layouts/myorg.com/myapp
with refs of stable
will
result in a unit of com.myorg.myapp.ref.stable.service
.
So you could then systemctl start com.myorg.myapp.ref.stable.service
,
journalctl -lr -u com.myorg.myapp.ref.stable.service
, etc.
All of the units generated by oci-systemd-generator
place the services in
resource group of ocl.slice
by default.
In this way, you can set drop-ins for how the overall oci.slice
is managed
(dependencies like network, etc., or resource-controls, etc).
The nature of the .service
unit files produced here are ephemeral, therefore
if you need to do drop-ins for properties on the service, you can create a
corresponding directory in /etc/systemd/systemd
.
Carrying on our example from Unit Name, the directory would be
/etc/systemd/system/com.myorg.myapp.ref.stable.service.d/
.
Use cases for this could include:
- overriding the
ExecStart=
line, or addingExecPre=
orExecPost=
(systemd.service(5)
) - setting
After=
and/orBefore=
(systemd.unit(5)
) - setting resource controls on this service (
systemd.resource-control(5)
)
Do NOT run image layouts that you have not built yourself or trust thoroughly, and carefully curated.