GitLocker: The Coding Marketplace

Description:

nspawn 0.7.0.dev1

nspawn

Containers with systemd-nspawn
Features:

differential image overlays
supports multiple inheritance for images
provides dsl
for image build and machine setup
machine is
completely represented
by generated
machine.service unit file

Install
To install python package:
sudo pip install nspawn

Build Script
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
Setup Script
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
Machine Service
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

Machine Resources
Location of machine files and folders:
/etc/systemd/system/<machine>.service
/var/lib/machines/<machine>
/var/lib/nspawn/runtime/<machine>

Machine Management
To interact with live machine:

for machines registered with machinectl
for machines with systemd init, such as archlinux

# 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 systemd init, such as alpine linux

# start interactive shell:
./setup.py --action=nsenter

alternatively, use package-provided nspawn-enter command:

# start interactive shell:
nspawn-enter <machine>

# invoke command with args:
nspawn-enter <machine> "command arg1 arg2 ..."

Configuration
Available configuration options are described in
config.ini
file.
Use config/path_list option to control configuration override file list.
Image Server
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
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
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',

DSL Syntax
TOOL
Expose build/setup utility functions:

https://github.com/random-python/nspawn/tree/master/src/main/nspawn/tool

TOOL.<function>(...)

IMAGE()
Declare image identity:
IMAGE("http://host/path/package.tar.gz")
IMAGE(url="http://host/path/package.tar.gz")

PULL()
Provision dependency image:
PULL("http://host/path/package.tar.gz")
PULL(url="http://host/path/package.tar.gz")

EXEC()
Declare image entry point executable i.e. COMMAND [ARGS...]:

https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html

EXEC(['/usr/bin/env', 'sh', '-c', 'echo "hello-kitty"'])
EXEC(command=['/usr/bin/env', 'sh', '-c', 'echo "hello-kitty"'])

WITH()
Customize machine features using nspawn container settings:

https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html

WITH(
SettingName1='setting 1 value a',
SettingName2='setting 2 value b',
...,
)

COPY()
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")

CAST()
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}}

FETCH()
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
)

RUN()
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'])

SH()
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 to RUN(command=['/usr/bin/env', 'sh', '-c', script])

PUSH()
Publish image result to the declared url:
PUSH()

MACHINE()
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:

https://github.com/random-python/nspawn/tree/master/src/main/nspawn/template