A console frontend for Distrobuilder to build custom LXD / LXC images
Project description
distrobuilder-menu
-
A python console frontend to Distrobuilder for building standard or customised LXD / LXC images
-
Main Menus (LXD | LXC)
dbmenu || dbmenu --lxc
:arrow_right: Features
-
Download / update the latest Distrobuilder templates via the Github REST API
-
Create:
- cloud-init
per-once
/ standard configuration - template overrides to include custom files / scripts
- custom templates by merging the template override / cloud-init
yaml
- cloud-init
-
Automatic selective caching of
json
output from LXDimages:
json
read speed improved from1mb
/0.65
seconds ===>30kb
/0.0083
seconds- Fast
yaml
reading withyaml.CSafeLoader
- Fast menu generation (typically
0.03
seconds or less) - Auto generated menus for the available container versions your
platform
can build:
-
Version Menu
- Optionally
import
the built LXD image intoincus
orlxd
- To disable automatic LXD imports Show User Configuration from the Main Menu & edit / set
import_into_lxd
toFalse
:arrow_right: Command line options:
usage: dbmenu [-h] [--lxd | --lxc | -o | -g | -i | -c | -e | -d | -m | -y | -u] [-s] [-t]
[--rate] [--reset]
Menu driven LXD / LXC images for Distrobuilder
options:
-h, --help show this help message and exit
--lxd build LXD container / vm image (default)
--lxc build LXC container image
-o, --override create new template override
-g, --generate generate custom template from override
-i, --init create / edit cloud-init configuration
-c, --copy copy existing template / override
-e, --edit edit existing template / override
-d, --delete delete template / override
-m, --move move / rename template or override
-y, --merge merge cloudinit configuration with yq
-u, --update force update templates (default auto weekly)
-s, --show show configuration settings
-t, --timer debug timer used in testing
--rate show current Github API Rate Limit
--reset reset dbmenu base directory configuration
:arrow_right: User Configuration:
- User configuration is stored under
~/.config/dbmenu.yaml
& is auto generated with sensible defaults on the first run ofdbmenu
- The base directory of the distrobuilder area can be optionally changed from the default
~/distrobuilder
on first run or at any time via thedbmenu --reset
command line option
[~]$ cat ~/.config/dbmenu.yaml
config_dir: /home/stuart/.config
main_dir: /home/stuart/devops/distrobuilder
target_dir: /home/stuart/devops/distrobuilder/build
files_dir: /home/stuart/devops/distrobuilder/files
template_dir: /home/stuart/devops/distrobuilder/templates
cloudinit_dir: /home/stuart/devops/distrobuilder/cloudinit
dbmenu_config: /home/stuart/.config/dbmenu.yaml
gh_owner: lxc
gh_repo: lxc-ci
gh_api_url: https://api.github.com
github_token: ''
cache_dir: false
cleanup: true
compression: xz
console_editor: nano
debug: false
disable_overlay: false
import_into_lxd: true
json_cachefile: /home/stuart/devops/distrobuilder/templates/cache.json
lxd_json: /home/stuart/devops/distrobuilder/templates/lxd.json
lxd_output_type: unified
subdir_custom: /home/stuart/devops/distrobuilder/templates/custom
subdir_images: /home/stuart/devops/distrobuilder/templates/images
subdir_overrides: /home/stuart/devops/distrobuilder/templates/overrides
cloudinit_network_dir: /home/stuart/devops/distrobuilder/cloudinit/network-data
cloudinit_user_dir: /home/stuart/devops/distrobuilder/cloudinit/user-data
cloudinit_vendor_dir: /home/stuart/devops/distrobuilder/cloudinit/vendor-data
timeout: false
yq_check: true
- For normal operation it's not necessary to add a Github Personal Access Token to your User Configuration
- Unauthenticated Github API Rate Limits are not normally exceeded due to
connection-pooling
inurllib3
& the API calls being made by asingleton
instance ofGethub
- To check your current Github API rate limit run
dbmenu --rate
:arrow_right: Dependencies
- python
3.10+
/pyyaml
/urllib3
- Golang version
4+
ofyq
(go-yq
in Arch Linux) incus
orlxd
distrobuilder-git
in Arch Linux (or Distrobuilder version2.1.r255.g4ebc3cb
or higher)
:arrow_right: Installation
-
✅ Isolated app:
pipx install git+https://github.com/itoffshore/distrobuilder-menu.git
- size on disk
4mb
- upgrade release with
--force
-
‼️ System module:
pip install git+https://github.com/itoffshore/distrobuilder-menu.git
- size on disk
900kb
- upgrade release with
--force
-
⚠️ Under
lxd
ensure Distrobuilder can findunix.socket
ln -s /var/lib/lxd /var/lib/incus
❓ Creating Override Templates
dbmenu
was inspired by & follows a similar methodology to Hashicorp Packer which builds / creates templates in layers:
-
Create a base image override for your chosen distribution with your
shell
/ package customizations that overrides a standard template -
Distribution Menu
-
This will generate an override template with an example
files
&packages
sections to customise & optionally open in your configuredconsole_editor
(nano
by default) -
⚠️ An override only needs the extra packages you wish to include (& not all of the packages that are included as an example of the
yaml
from theSOURCE
template you are overriding) -
Override Template
- Create a specific override /
cloud-init
config for your custom service container that contains customizations not in your base image template (e.g web services / database) - Generate a Custom Template which uses your custom base image template as the
SOURCE
template & merges your specific overrides / cloud-init for your custom service container
📰 Template Examples
-
This repo's
examples
directory is also packaged undersite-packages
- e.g forpipx
installs:~/.local/pipx/venvs/distrobuilder-menu/lib/python3.11/site-packages/examples
-
These
examples
show how to create images for:- Alpine Linux / Ubuntu base images
- Alpine Linux build environment (
21mb
) that installsalpine-sdk
on first boot via cloud-init & most of the steps for contributing packages to Alpine - See the alpine-abuild cloud-init
bootcmd
for how to build an Alpine Linux cloud image & remove cloud-init & it's dependencies on first boot - Ubuntu Gitlab container that installs Gitlab on first
boot
viacloud-init
🏗️ Creating / Building a Custom Template
-
Empty input for each menu option / choice will
return
you to the Main Menu (main event loop
) -
Create Custom Override
-
Optionally - Create cloud-init Config
-
Generate Custom Template
- this option gives choices to merge a Custom Override & cloud-init configuration
- you could also just Merge cloud-init Config into an existing template if you only need that option
-
Build image - choosing the template type:
- LXD images are built by
default
- to build
lxc
images start the app withdbmenu --lxc
- default container (LXC & LXD)
- cloud container (LXC & LXD)
- vm (LXD only)
- LXD images are built by
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for distrobuilder_menu-0.2.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e4be5f0dddaaaf73457ca5a5007153ca0705cfdd195158f6b0b5e1de6f7362f5 |
|
MD5 | ca2edaa3df1678a13fca8d22f80bca0b |
|
BLAKE2b-256 | a24dd526d94c08bea7e7197ddd3fa187f37b849d01a84e7dacf04dfb6e8a1567 |