## nspawn
[![Travis Status][travis_icon]][travis_link]
[![Appvey Status][appvey_icon]][appvey_link]
[![Package Version][pypi_icon]][pypi_link]
[![Python Versions][python_icon]][python_link]
Containers with [`systemd-nspawn`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html)
Features:
* differential image [overlays](https://en.wikipedia.org/wiki/OverlayFS)
* supports multiple inheritance for images
* provides [dsl](https://en.wikipedia.org/wiki/Domain-specific_language)
for image `build` and machine `setup`
* machine is
[completely represented](https://github.com/random-python/nspawn/tree/master/src/main/nspawn/template)
by generated
[machine.service unit file](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)
### 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](https://github.com/random-python/nspawn/blob/master/src/main/nspawn/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](https://jinja.palletsprojects.com/en/2.10.x/)
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
[travis_icon]: https://travis-ci.org/random-python/nspawn.svg?branch=master
[travis_link]: https://travis-ci.org/random-python/nspawn/builds
[appvey_icon]: https://ci.appveyor.com/api/projects/status/fbjgg6ana9kkww6p?svg=true
[appvey_link]: https://ci.appveyor.com/project/Andrei-Pozolotin/nspawn/history
[pypi_icon]: https://badge.fury.io/py/nspawn.svg
[pypi_link]: https://pypi.python.org/pypi/nspawn
[python_icon]: https://img.shields.io/pypi/pyversions/nspawn.svg
[python_link]: https://pypi.python.org/pypi/nspawn
[tokei_icon]: https://tokei.rs/b1/github/random-python/nspawn
[tokei_link]: https://github.com/random-python/nspawn/tree/master/src
Raw data
{
"_id": null,
"home_page": "https://github.com/random-python/nspawn",
"name": "nspawn",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "",
"keywords": "nspawn,container,systemd,systemd-nspawn",
"author": "Andrei Pozolotin",
"author_email": "andrei.pozolotin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bc/e9/1b73b2df0bf1c2e2307b95c7319589e8b13c43d4c7850b9b989cf9225a1f/nspawn-0.7.0.dev1.zip",
"platform": null,
"description": "## nspawn\n\n[![Travis Status][travis_icon]][travis_link]\n[![Appvey Status][appvey_icon]][appvey_link]\n[![Package Version][pypi_icon]][pypi_link]\n[![Python Versions][python_icon]][python_link]\n\nContainers with [`systemd-nspawn`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html)\n\nFeatures:\n* differential image [overlays](https://en.wikipedia.org/wiki/OverlayFS)\n* supports multiple inheritance for images\n* provides [dsl](https://en.wikipedia.org/wiki/Domain-specific_language)\n for image `build` and machine `setup`\n* machine is\n [completely represented](https://github.com/random-python/nspawn/tree/master/src/main/nspawn/template)\n by generated\n [machine.service unit file](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)\n\n### Install\n\nTo install python package:\n\n```\nsudo pip install nspawn\n```\n\n### Build Script\n\nTo build an image, provide and invoke executable `build.py` script, for example:\n* alpine: https://github.com/random-python/nspawn/blob/master/demo/alpine/base/build.py\n* archux: https://github.com/random-python/nspawn/blob/master/demo/archux/base/build.py\n* ubuntu: https://github.com/random-python/nspawn/blob/master/demo/ubuntu/base/build.py\n\nFor available build options run `./build.py --help`\n\n### Setup Script\n\nTo setup a machine, provide and invoke executable `setup.py` script, for example:\n* alpine: https://github.com/random-python/nspawn/blob/master/demo/alpine/base/setup.py\n* archux: https://github.com/random-python/nspawn/blob/master/demo/archux/base/setup.py\n* ubuntu: https://github.com/random-python/nspawn/blob/master/demo/ubuntu/base/setup.py\n\nFor available setup options run `./setup.py --help`\n\n### Machine Service\n\nTo review provisioned, generated and running machine service, run:\n```\nmachinectl\nsystemctl status <machine>\ncat /etc/systemd/system/<machine>.service\n```\nfor example, demo generated services:\n* alpine: https://github.com/random-python/nspawn/blob/master/demo/alpine-base.service\n* archux: https://github.com/random-python/nspawn/blob/master/demo/archux-base.service\n* ubuntu: https://github.com/random-python/nspawn/blob/master/demo/ubuntu-base.service\n\n### Machine Resources\n\nLocation of machine files and folders:\n```\n/etc/systemd/system/<machine>.service\n/var/lib/machines/<machine>\n/var/lib/nspawn/runtime/<machine>\n```\n\n### Machine Management\n\nTo interact with live machine:\n* for machines registered with `machinectl`\n* for machines with `systemd` `init`, such as `archlinux`\n```\n# start interactive shell:\nsudo machinectl shell <machine> \n```\n```\n# invoke command with args:\nsudo machinectl shell <machine> /bin/command arg1 arg2 ... \n```\n* for machines not registered with `machinectl`\n* for machines without `systemd` `init`, such as `alpine linux`\n```\n# start interactive shell:\n./setup.py --action=nsenter \n```\n* alternatively, use package-provided `nspawn-enter` command:\n```\n# start interactive shell:\nnspawn-enter <machine> \n```\n```\n# invoke command with args:\nnspawn-enter <machine> \"command arg1 arg2 ...\" \n```\n\n### Configuration\n\nAvailable configuration options are described in\n[config.ini](https://github.com/random-python/nspawn/blob/master/src/main/nspawn/config.ini) \nfile.\n\nUse `config/path_list` option to control configuration override file list.\n\n### Image Server\n\nPackage comes with provisioning command `nspawn-hatch`\nwhich can build and setup local http/https image server.\n```\n# review available services:\nnspawn-hatch list\n```\n```\n# provision image server service:\nnspawn-hatch update image-server\n```\n```\n# verify image server machine status:\nmachinectl\n```\n\nImage server settings:\n* https://github.com/random-python/nspawn/tree/master/src/main/nspawn/app/hatcher/service/image-server\n\nImage syncer settings (replicate to Amazon AWS S3):\n* https://github.com/random-python/nspawn/tree/master/src/main/nspawn/app/hatcher/service/image-syncer\n\n### Build DSL\n\nBuild DSL is used in `build.py`, is activated by `from nspawn.build import *` and provides keywords:\n```\n 'TOOL',\n 'IMAGE',\n 'PULL',\n 'EXEC',\n 'WITH',\n 'FETCH',\n 'COPY',\n 'CAST',\n 'RUN',\n 'SH',\n 'PUSH',\n```\n\n### Setup DSL\n\nSetup DSL is used in `setup.py`, is activated by `from nspawn.setup import *` and provides keywords:\n```\n 'TOOL',\n 'IMAGE',\n 'MACHINE',\n 'WITH',\n 'EXEC',\n 'COPY',\n 'CAST',\n 'RUN',\n 'SH',\n```\n\n### DSL Syntax\n\n#### `TOOL`\n\nExpose build/setup utility functions:\n* https://github.com/random-python/nspawn/tree/master/src/main/nspawn/tool\n```\nTOOL.<function>(...)\n```\n\n#### `IMAGE()`\n\nDeclare image identity:\n```\nIMAGE(\"http://host/path/package.tar.gz\")\nIMAGE(url=\"http://host/path/package.tar.gz\")\n```\n\n#### `PULL()`\n\nProvision dependency image:\n```\nPULL(\"http://host/path/package.tar.gz\")\nPULL(url=\"http://host/path/package.tar.gz\")\n```\n\n#### `EXEC()`\n\nDeclare image entry point executable i.e. `COMMAND [ARGS...]`:\n* https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html\n```\nEXEC(['/usr/bin/env', 'sh', '-c', 'echo \"hello-kitty\"'])\nEXEC(command=['/usr/bin/env', 'sh', '-c', 'echo \"hello-kitty\"'])\n```\n\n#### `WITH()`\n\nCustomize machine features using nspawn container settings:\n* https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html\n```\nWITH(\n SettingName1='setting 1 value a',\n SettingName2='setting 2 value b',\n ...,\n)\n```\n\n#### `COPY()`\n\nCopy local resources:\n* when used in `build.py`: target is in the image\n* when used in `setup.py`: target is on the host\n```\nCOPY(\"/etc\")\nCOPY(path=\"/etc\")\nCOPY(source=\"/root/input.md\", target=\"/root/output.md\")\n```\n\n#### `CAST()`\n\nTemplate local resources:\n* when used in `build.py`: target is in the image\n* when used in `setup.py`: target is on the host\n```\nCAST(\"/root/readme.md\", variable=\"template varialbe\", ...)\nCAST(path=\"/root/readme.md\", variable=\"template varialbe\", ...)\nCAST(source=\"/root/input.md\", target=\"/root/output.md\", variable=\"template varialbe\", ...)\n```\n\nTemplate uses [python/jinja](https://jinja.palletsprojects.com/en/2.10.x/)\nformat, i.e:\n```\nthis template variable will be substituted: {{variable}}\n```\n\n#### `FETCH()`\n\nDownload and extract remote resource:\n```\nFETCH( # use when source and target are the same\n url=\"http://server/package.tar.gz\", # url for remote resource\n path=\"/common-path\", # path inside the package source and image target\n)\nFETCH( # use when source and target are different\n url=\"http://server/package.tar.gz\", # url for remote resource\n source=\"/package-path\", # path inside the package extract\n target=\"/opt/resource\", # path inside the build image target\n)\n```\n\n#### `RUN()`\n\nInvoke command, with target depending on the context:\n* when used in `build.py`: invoke inside the image\n* when used in `setup.py`: invoke on the host\n```\nRUN(['/usr/bin/env', 'ls', '-las'])\nRUN(command=['/usr/bin/env', 'ls', '-las'])\n```\n\n#### `SH()`\n\nInvoke shell script, with target depending on the context:\n* when used in `build.py`: invoke inside the image\n* when used in `setup.py`: invoke on the host\n```\nSH(\"ls -las\")\nSH(script=\"ls -las\")\n```\nNote:\n* `SH(script)` is equivalent to `RUN(command=['/usr/bin/env', 'sh', '-c', script])`\n\n#### `PUSH()`\n\nPublish image result to the declared url:\n```\nPUSH()\n```\n\n#### `MACHINE()`\n\nDeclare machine service:\n```\nMACHINE('machine-name')\nMACHINE(name='machine-name')\nMACHINE(name='machine-name', template='/path/to/service/template/machine.service')\n```\n\nProvide inline service unit changes:\n```\nMACHINE(\n name='machine-name',\n # extra entries for [Unit] section\n unit_conf=[\n \"Description=hello-world\", # override description\n ],\n # extra entries for [Service] section\n service_conf=[\n \"CPUQuota=10%\", # throttle processor usage\n ],\n # extra entries for [Install] section\n install_conf=[\n \"WantedBy=machines.target\", # inject unit dependency\n ],\n)\n```\n\nDesign custom service templates based on package-provided defaults, for example:\n* https://github.com/random-python/nspawn/tree/master/src/main/nspawn/template\n\n\n\n\n[travis_icon]: https://travis-ci.org/random-python/nspawn.svg?branch=master\n[travis_link]: https://travis-ci.org/random-python/nspawn/builds\n\n[appvey_icon]: https://ci.appveyor.com/api/projects/status/fbjgg6ana9kkww6p?svg=true\n[appvey_link]: https://ci.appveyor.com/project/Andrei-Pozolotin/nspawn/history \n\n[pypi_icon]: https://badge.fury.io/py/nspawn.svg\n[pypi_link]: https://pypi.python.org/pypi/nspawn\n\n[python_icon]: https://img.shields.io/pypi/pyversions/nspawn.svg\n[python_link]: https://pypi.python.org/pypi/nspawn\n\n[tokei_icon]: https://tokei.rs/b1/github/random-python/nspawn\n[tokei_link]: https://github.com/random-python/nspawn/tree/master/src\n\n",
"bugtrack_url": null,
"license": "Apache-2",
"summary": "Containers with systemd-nspawn",
"version": "0.7.0.dev1",
"project_urls": {
"Homepage": "https://github.com/random-python/nspawn"
},
"split_keywords": [
"nspawn",
"container",
"systemd",
"systemd-nspawn"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bce91b73b2df0bf1c2e2307b95c7319589e8b13c43d4c7850b9b989cf9225a1f",
"md5": "49ee25776661a8e079c58cbb78e8cc44",
"sha256": "19017c272c4ff9ef2772be1f7596cd5cfd1d0ba4a4c01298872f8c437bd1050a"
},
"downloads": -1,
"filename": "nspawn-0.7.0.dev1.zip",
"has_sig": false,
"md5_digest": "49ee25776661a8e079c58cbb78e8cc44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 242489,
"upload_time": "2023-05-07T17:00:44",
"upload_time_iso_8601": "2023-05-07T17:00:44.092900Z",
"url": "https://files.pythonhosted.org/packages/bc/e9/1b73b2df0bf1c2e2307b95c7319589e8b13c43d4c7850b9b989cf9225a1f/nspawn-0.7.0.dev1.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-07 17:00:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "random-python",
"github_project": "nspawn",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"appveyor": true,
"requirements": [],
"tox": true,
"lcname": "nspawn"
}
JSON
