Alternatives and detailed information of nspawn

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:

For available build options run ./build.py --help

Setup Script

To setup a machine, provide and invoke executable setup.py script, for example:

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:

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

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

random-python / nspawn

Programming Languages

Labels

Projects that are alternatives of or similar to nspawn