general_quick_intro - OpenNebula/one-apps GitHub Wiki
OneApps Quick Intro
This page is a quick guide to:
- Install OneApps on Debian-based systems
- Build a Linux OS image
- Deploy a VM to the new image
This page presents a brief high-level outline. For complete information on installing and using one-apps please refer to Requirements and Using the build tools.
Installing Prerequisites on Debian-based Systems
Hardware:
- RAM: 8GB+
- CPU: 2+, with KVM acceleration
- Disk: 40GB+
Software
- Ruby
- The
fpmRuby gem (install withgem install fpm) dpkgrpmmakecloud-utilsqemu-utils(includesqemu-img)guestfs-tools(includesvirt-sysprep)- Packer >= 1.9.4 (install the latest version from the Hashicorp official repositories)
Install the requisites (as root):
apt install ruby rpm make cloud-utils qemu-utils guestfs-tools wixl
gem install fpm
Clone the one-apps repo:
git clone https://github.com/OpenNebula/one-apps.git
A Brief Look at the Contents of one-apps
Go to the one-apps root directory:
cd one-apps
The repo directories contain scripts for building appliances and context packages for Linux and Windows, as well as Packer scripts for building Linux distros.
one-apps$ ls
appliances build context-linux context-windows export LICENSE Makefile Makefile.config packer README.md
Notice the provided Makefile. To see build targets and available options:
make help
The distributions and services are built with the Packer scripts contained in the packer directory:
packer/
├── alma
│ ├── 10-upgrade-distro.sh
│ ├── 11-update-grub.sh
│ ├── 11-zzz.sh
│ ├── 80-install-context.sh.8
│ ├── 80-install-context.sh.9
│ ├── 81-configure-ssh.sh
│ ├── 98-collect-garbage.sh
│ ├── alma.pkr.hcl
│ ├── cloud-init.yml
│ ├── plugins.pkr.hcl -> ../plugins.pkr.hcl
│ └── variables.pkr.hcl
├── alpine
│ ├── 10-upgrade-distro.sh
│ ├── 11-update-boot.sh
│ ├── 80-install-context.sh
│ ├── 81-configure-ssh.sh
│ ├── 98-collect-garbage.sh
│ ├── alpine.init
│ ├── alpine.pkr.hcl
│ ├── plugins.pkr.hcl -> ../plugins.pkr.hcl
│ └── variables.pkr.hcl
...
The scripts in these directories define the virtual hardware for the VM, apply configuration and upgrades, and set variables for the appliance.
cat packer/alpine/alpine.pkr.hcl
source "qemu" "alpine" {
cpus = 2
memory = 2048
accelerator = "kvm"
iso_url = lookup(lookup(var.alpine, var.version, {}), "iso_url", "")
iso_checksum = lookup(lookup(var.alpine, var.version, {}), "iso_checksum", "")
headless = var.headless
...
The .init files contain commands for applying various configurations such as username and password, network, disk partitions and filesystems:
cat packer/alpine/alpine.init
#!/bin/ash
# set root password
passwd root <<'EOF'
opennebula
opennebula
EOF
cat > answers.txt <<EOT
KEYMAPOPTS="us us"
HOSTNAMEOPTS="localhost"
INTERFACESOPTS="auto lo
iface lo inet loopback
auto eth0
iface eth0 inet dhcp
hostname localhost
...
# create single partition, mount it, run setup-disk
parted /dev/vda mklabel msdos
parted /dev/vda mkpart p ext4 1MiB 100%
parted /dev/vda set 1 boot on
mkfs.ext4 /dev/vda
...
[!TIP] For further details please refer to Developer Information.
Simple Example: Build an Alpine Linux Image
[!NOTE] You must run the build process as the
rootuser (e.g.sudo make alpine320), since the user needs chroot permissions to delete the machine ID and some unnecessary data from the image. If the build is not run as root, it will fail during the postprocessing stage.
To build the Alpine 3.20 image:
From the one-apps directory, as root:
make alpine320
The build process downloads an Alpine .iso image (from the URL defined in packer/alpine/alpine.pkr.hcl -> iso_url), creates the VM, boots it, and applies commands over VNC. It will take a few minutes depending on your machine and network speed.
one-apps# make alpine320
cd context-linux; ./generate-all.sh
Created package {:path=>"out/one-context-6.10.0-2.el8.noarch.rpm"}
one-context-6.10.0-2.el8.noarch.rpm
Created package {:path=>"out/one-context-6.10.0-2.el9.noarch.rpm"}
one-context-6.10.0-2.el9.noarch.rpm
Created package {:path=>"out/one-context-6.10.0-2.fc.noarch.rpm"}
one-context-6.10.0-2.fc.noarch.rpm
...
qemu.alpine (shell-local): [ 2.7] Trimming /dev/sda1
qemu.alpine (shell-local): [ 2.9] Sparsify in-place operation completed with no errors
Build 'qemu.alpine' finished after 2 minutes 9 seconds.
==> Wait completed after 2 minutes 9 seconds
==> Builds finished. The artifacts of successful builds are:
--> qemu.alpine: VM files in directory: build/alpine320
--> qemu.alpine: VM files in directory: build/alpine320
[INFO] Packer alpine320 done
Once it's finished, by default the image is saved to the export directory:
ls export/
alpine320.qcow2
The image is ready to import and in your OpenNebula Front-end.
Deploying a VM to the Image
To use the image, copy it to your OpenNebula Front-end node.
To import the image into a datastore, as user oneadmin run:
oneimage create -d <datastore ID> --name one-apps_alpine320 --path /path/to/image/alpine320.qcow2
For example, importing to the default datastore:
oneimage create -d 1 --name one-apps_alpine320 --path /var/tmp/one/alpine320.qcow2
[!NOTE] Before copying, ensure to place the image in a directory where you are allowed to copy from. To check which directories are allowed, run the below command for the datastore you wish to copy the image to:
onedatastore show <datastore ID>In the command output check the values ofRESTRICTED_DIRSandSAFE_DIRS.
To verify that the image was properly imported, run:
oneimage list
In the output, verify that the STAT column displays rdy:
oneimage list
ID USER GROUP NAME DATASTORE SIZE TYPE PER STAT RVMS
6 oneadmin oneadmin one-apps_alpine320 default 256M OS No rdy 0
2 oneadmin oneadmin Ubuntu 22.04 default 2.2G OS No used 1
1 oneadmin oneadmin Ubuntu 24.04 default 3.5G OS No used 5
0 oneadmin oneadmin Service WordPress - KVM default 10G OS No rdy 0
In the output above notice that the image ID is 6.
Now you can select a VM template to instantiate on the image. See available templates with onetemplate list:
onetemplate list
ID USER GROUP NAME REGTIME
4 oneadmin oneadmin Alpine Linux 3.17 09/19 14:43:36
2 oneadmin oneadmin Ubuntu 22.04 08/11 12:38:48
1 oneadmin oneadmin Ubuntu 24.04 08/10 15:31:56
0 oneadmin oneadmin Service WordPress - KVM
In this example we will instantiate template 4, Alpine Linux 3.17. For the --disk parameter we will use 6, the image ID obtained with oneimage list.
onetemplate instantiate 4 --disk 6
VM ID: 34
The VM was instantiated with ID 34. Wait a few moments for it to finish the boot process, then check its status with onevm list:
onevm list
ID USER GROUP NAME STAT CPU MEM HOST TIME
34 oneadmin oneadmin Alpine Linux 3.17-34 runn 1 128M PC07 0d 00h00
Check that the STAT column displays runn.
You should now be able to connect to the VM via VNC or SSH.
[!TIP] For complete information on installing and using
one-appsplease refer to Requirements and Using the build tools.