Package: nspawn
nspawnContainers withsystemd-nspawnFeatures:differential imageoverlayssupports multiple inheritance for imagesprovidesdslfor imagebuildand machinesetupmachine iscompletely representedby generatedmachine.service unit fileInstallTo install python package:sudo pip install nspawnBuild ScriptTo build an image, provide and invoke executablebuild.pyscript, for example:alpine:https://github.com/random-python/nspawn/blob/master/demo/alpine/base/build.pyarchux:https://github.com/random-python/nspawn/blob/master/demo/archux/base/build.pyubuntu:https://github.com/random-python/nspawn/blob/master/demo/ubuntu/base/build.pyFor available build options run./build.py --helpSetup ScriptTo setup a machine, provide and invoke executablesetup.pyscript, for example:alpine:https://github.com/random-python/nspawn/blob/master/demo/alpine/base/setup.pyarchux:https://github.com/random-python/nspawn/blob/master/demo/archux/base/setup.pyubuntu:https://github.com/random-python/nspawn/blob/master/demo/ubuntu/base/setup.pyFor available setup options run./setup.py --helpMachine ServiceTo review provisioned, generated and running machine service, run:machinectl
systemctl status <machine>
cat /etc/systemd/system/<machine>.servicefor example, demo generated services:alpine:https://github.com/random-python/nspawn/blob/master/demo/alpine-base.servicearchux:https://github.com/random-python/nspawn/blob/master/demo/archux-base.serviceubuntu:https://github.com/random-python/nspawn/blob/master/demo/ubuntu-base.serviceMachine ResourcesLocation of machine files and folders:/etc/systemd/system/<machine>.service
/var/lib/machines/<machine>
/var/lib/nspawn/runtime/<machine>Machine ManagementTo interact with live machine:for machines registered withmachinectlfor machines withsystemdinit, 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 withmachinectlfor machines withoutsystemdinit, such asalpine linux# start interactive shell:
./setup.py --action=nsenteralternatively, use package-providednspawn-entercommand:# start interactive shell:
nspawn-enter <machine># invoke command with args:
nspawn-enter <machine> "command arg1 arg2 ..."ConfigurationAvailable configuration options are described inconfig.inifile.Useconfig/path_listoption to control configuration override file list.Image ServerPackage comes with provisioning commandnspawn-hatchwhich 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:
machinectlImage server settings:https://github.com/random-python/nspawn/tree/master/src/main/nspawn/app/hatcher/service/image-serverImage syncer settings (replicate to Amazon AWS S3):https://github.com/random-python/nspawn/tree/master/src/main/nspawn/app/hatcher/service/image-syncerBuild DSLBuild DSL is used inbuild.py, is activated byfrom nspawn.build import *and provides keywords:'TOOL',
    'IMAGE',
    'PULL',
    'EXEC',
    'WITH',
    'FETCH',
    'COPY',
    'CAST',
    'RUN',
    'SH',
    'PUSH',Setup DSLSetup DSL is used insetup.py, is activated byfrom nspawn.setup import *and provides keywords:'TOOL',
    'IMAGE',
    'MACHINE',
    'WITH',
    'EXEC',
    'COPY',
    'CAST',
    'RUN',
    'SH',DSL SyntaxTOOLExpose build/setup utility functions:https://github.com/random-python/nspawn/tree/master/src/main/nspawn/toolTOOL.<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.htmlEXEC(['/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.htmlWITH(
    SettingName1='setting 1 value a',
    SettingName2='setting 2 value b',
    ...,
)COPY()Copy local resources:when used inbuild.py: target is in the imagewhen used insetup.py: target is on the hostCOPY("/etc")
COPY(path="/etc")
COPY(source="/root/input.md", target="/root/output.md")CAST()Template local resources:when used inbuild.py: target is in the imagewhen used insetup.py: target is on the hostCAST("/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 usespython/jinjaformat, 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 inbuild.py: invoke inside the imagewhen used insetup.py: invoke on the hostRUN(['/usr/bin/env', 'ls', '-las'])
RUN(command=['/usr/bin/env', 'ls', '-las'])SH()Invoke shell script, with target depending on the context:when used inbuild.py: invoke inside the imagewhen used insetup.py: invoke on the hostSH("ls -las")
SH(script="ls -las")Note:SH(script)is equivalent toRUN(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