oci-systemd-generator

README

oci-systemd-generator

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

Install

go get -u github.com/vbatts/oci-systemd-generator
sudo cp $GOPATH/bin/oci-systemd-generator /lib/systemd/system-generators/

Config

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

Usage

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.

1. the layout must be one or more sub directory under imagelayoutdir (so that it has a name associated for it)
2. it must have layers (a rootfs to be used)
3. a combination of Entrypoint and/or Cmd from the image properties so that there is enough to make an ExecStart= 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

Unit Name

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.

Service Defaults

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).

Service Modifications

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 adding ExecPre= or ExecPost= (systemd.service(5))
• setting After= and/or Before= (systemd.unit(5))
• setting resource controls on this service (systemd.resource-control(5))

Disclaimer

Do NOT run image layouts that you have not built yourself or trust thoroughly, and carefully curated.