Containers with systemd-nspawn
Features:
- differential image overlays
- supports multiple inheritance for images
- provides dsl
for image
buildand machinesetup - machine is completely represented by generated machine.service unit file
To install python package:
sudo pip install nspawn
To build an image, provide and invoke executable build.py script, for example:
- alpine: https://github.com/random-python/nspawn/blob/master/demo/alpine/base/build.py
- archux: https://github.com/random-python/nspawn/blob/master/demo/archux/base/build.py
- ubuntu: https://github.com/random-python/nspawn/blob/master/demo/ubuntu/base/build.py
For available build options run ./build.py --help
To setup a machine, provide and invoke executable setup.py script, for example:
- alpine: https://github.com/random-python/nspawn/blob/master/demo/alpine/base/setup.py
- archux: https://github.com/random-python/nspawn/blob/master/demo/archux/base/setup.py
- ubuntu: https://github.com/random-python/nspawn/blob/master/demo/ubuntu/base/setup.py
For available setup options run ./setup.py --help
To review provisioned, generated and running machine service, run:
machinectl
systemctl status <machine>
cat /etc/systemd/system/<machine>.service
for example, demo generated services:
- alpine: https://github.com/random-python/nspawn/blob/master/demo/alpine-base.service
- archux: https://github.com/random-python/nspawn/blob/master/demo/archux-base.service
- ubuntu: https://github.com/random-python/nspawn/blob/master/demo/ubuntu-base.service
Location of machine files and folders:
/etc/systemd/system/<machine>.service
/var/lib/machines/<machine>
/var/lib/nspawn/runtime/<machine>
To interact with live machine:
- for machines registered with
machinectl - for machines with
systemdinit, such asarchlinux
# start interactive shell:
sudo machinectl shell <machine>
# invoke command with args:
sudo machinectl shell <machine> /bin/command arg1 arg2 ...
- for machines not registered with
machinectl - for machines without
systemdinit, such asalpine linux
# start interactive shell:
./setup.py --action=nsenter
- alternatively, use package-provided
nspawn-entercommand:
# start interactive shell:
nspawn-enter <machine>
# invoke command with args:
nspawn-enter <machine> "command arg1 arg2 ..."
Available configuration options are described in config.ini file.
Use config/path_list option to control configuration override file list.
Package comes with provisioning command nspawn-hatch
which can build and setup local http/https image server.
# review available services:
nspawn-hatch list
# provision image server service:
nspawn-hatch update image-server
# verify image server machine status:
machinectl
Image server settings:
- https://github.com/random-python/nspawn/tree/master/src/main/nspawn/app/hatcher/service/image-server
Image syncer settings (replicate to Amazon AWS S3):
- https://github.com/random-python/nspawn/tree/master/src/main/nspawn/app/hatcher/service/image-syncer
Build DSL is used in build.py, is activated by from nspawn.build import * and provides keywords:
'TOOL',
'IMAGE',
'PULL',
'EXEC',
'WITH',
'FETCH',
'COPY',
'CAST',
'RUN',
'SH',
'PUSH',
Setup DSL is used in setup.py, is activated by from nspawn.setup import * and provides keywords:
'TOOL',
'IMAGE',
'MACHINE',
'WITH',
'EXEC',
'COPY',
'CAST',
'RUN',
'SH',
Expose build/setup utility functions:
TOOL.<function>(...)
Declare image identity:
IMAGE("http://host/path/package.tar.gz")
IMAGE(url="http://host/path/package.tar.gz")
Provision dependency image:
PULL("http://host/path/package.tar.gz")
PULL(url="http://host/path/package.tar.gz")
Declare image entry point executable i.e. COMMAND [ARGS...]:
EXEC(['/usr/bin/env', 'sh', '-c', 'echo "hello-kitty"'])
EXEC(command=['/usr/bin/env', 'sh', '-c', 'echo "hello-kitty"'])
Customize machine features using nspawn container settings:
WITH(
SettingName1='setting 1 value a',
SettingName2='setting 2 value b',
...,
)
Copy local resources:
- when used in
build.py: target is in the image - when used in
setup.py: target is on the host
COPY("/etc")
COPY(path="/etc")
COPY(source="/root/input.md", target="/root/output.md")
Template local resources:
- when used in
build.py: target is in the image - when used in
setup.py: target is on the host
CAST("/root/readme.md", variable="template varialbe", ...)
CAST(path="/root/readme.md", variable="template varialbe", ...)
CAST(source="/root/input.md", target="/root/output.md", variable="template varialbe", ...)
Template uses python/jinja format, i.e:
this template variable will be substituted: {{variable}}
Download and extract remote resource:
FETCH( # use when source and target are the same
url="http://server/package.tar.gz", # url for remote resource
path="/common-path", # path inside the package source and image target
)
FETCH( # use when source and target are different
url="http://server/package.tar.gz", # url for remote resource
source="/package-path", # path inside the package extract
target="/opt/resource", # path inside the build image target
)
Invoke command, with target depending on the context:
- when used in
build.py: invoke inside the image - when used in
setup.py: invoke on the host
RUN(['/usr/bin/env', 'ls', '-las'])
RUN(command=['/usr/bin/env', 'ls', '-las'])
Invoke shell script, with target depending on the context:
- when used in
build.py: invoke inside the image - when used in
setup.py: invoke on the host
SH("ls -las")
SH(script="ls -las")
Note:
SH(script)is equivalent toRUN(command=['/usr/bin/env', 'sh', '-c', script])
Publish image result to the declared url:
PUSH()
Declare machine service:
MACHINE('machine-name')
MACHINE(name='machine-name')
MACHINE(name='machine-name', template='/path/to/service/template/machine.service')
Provide inline service unit changes:
MACHINE(
name='machine-name',
# extra entries for [Unit] section
unit_conf=[
"Description=hello-world", # override description
],
# extra entries for [Service] section
service_conf=[
"CPUQuota=10%", # throttle processor usage
],
# extra entries for [Install] section
install_conf=[
"WantedBy=machines.target", # inject unit dependency
],
)
Design custom service templates based on package-provided defaults, for example: