============
gen-vm-image
============
This package can be used for generating and configuring virtual machine images.
------------
Dependencies
------------
The dependencies required to use this package to generate virtual machine images
can be found in the `dep` directory for the supported distributions.
-----
Setup
-----
The `qemu-kvm` command might not be available in the default PATH.
This can be determined via the `which` command::
which qemu-kvm
If the command is not available, the qemu-kvm might be in a different location that is not part of
your current PATH. In this case, you can create a symbolic link to the qemu-kvm command in a directory
An example of this could be::
ln -s /usr/share/bash-completion/completions/qemu-kvm /usr/local/bin/qemu-kvm
The `gen-vm-image` command can be used to generate virtual machine images for the supported distributions.
To define which images should be generated, architecture.yml file should be created and defined beforehand.
-----------------------------
Build a Virtual Machine Image
-----------------------------
Before an image can be generated, you first have to create an architecture file that defines which images should be built.
What name this architecture file is given is not important, but it should be in YAML format and contain the following structure::
owner: <string> # The owner of the image
images: <key-value pair> # The images to be generated
<image-name>:
name: <string> # The name of the image
version: <string> # The version of the image
get_url: <string> # The URL to download the image from
checksum:
type: <string> # The type of checksum that should be used to validate the image. For valid types, see the supported algorithms `Here <https://docs.python.org/3/library/hashlib.html#hashlib.new>`_
value: <string> # The checksum value that should be used to validate the image
size: <string> # The size of the to be generated vm image disk, can use suffixes such as 'K', 'M', 'G', 'T'.
An example of such a file can be found in the `examples` directory.
Upon creating such a file, the `gen-vm-image` command can be used to generate the virtual machine image.
The totality of the command can be seen below::
usage: gen-vm-image [-h] [--architecture-path ARCHITECTURE_PATH]
[--image-output-path IMAGE_OUTPUT_PATH]
[--generated-image-owner GENERATED_IMAGE_OWNER]
[--generate-gocd-config]
[--gocd-config-name GOCD_CONFIG_NAME]
[--gocd-build-branch GOCD_BUILD_BRANCH]
optional arguments:
-h, --help show this help message and exit
--architecture-path ARCHITECTURE_PATH
The path to the architecture file that is used to configure the images to be built (default: architecture.yml)
--image-output-path IMAGE_OUTPUT_PATH
The output path of the built image (default: generated-images/image.qcow2)
--generated-image-owner GENERATED_IMAGE_OWNER
Set the uid owner of the configured image (default: qemu)
--generate-gocd-config
Generate a GoCD config based on the architecture file (default: False)
--gocd-config-name GOCD_CONFIG_NAME
Name of the generated gocd config file (default: 1.gocd.yml)
--gocd-build-branch GOCD_BUILD_BRANCH
The branch that GoCD should use to build images (default: main)
When the ``gen-vm-image`` command is executed, the generated VM disk image will be placed in the ``--image-output-path`` directory.
If every default value is acceptable, the VM image can be built by simply running ``make build`` in the root directory of the project::
make build
---------------------------------
Configure a Virtual Machine Image
---------------------------------
To configure a built VM image disk, the `configure-vm-image` command can be used.
This tool uses cloud-init to configure the image, and the configuration files for cloud-init should be defined beforehand.
Therefore, the tool requires that the to be configured image supports cloud-init, a list of various distributions cloud-init images can be found below.
- `Rocky <https://download.rockylinux.org/pub/rocky/>`_
- `Debian <https://cloud.debian.org/images/cloud/>`_
- `Ubuntu <https://cloud-images.ubuntu.com/>`_
- `Fedora <https://mirrors.dotsrc.org/fedora-enchilada/linux/releases/39/Cloud/>`_
The default location from where these are expected to be found can be discovered by running the command with the ``--help`` flag::
usage: configure_image.py [-h] [--image-input-path IMAGE_INPUT_PATH]
[---image-qemu-socket-path IMAGE_QEMU_SOCKET_PATH]
[--config-user-data-path CONFIG_USER_DATA_PATH]
[--config-meta-data-path CONFIG_META_DATA_PATH]
[--config-vendor-data-path CONFIG_VENDOR_DATA_PATH]
[--config-seed-output-path CONFIG_SEED_OUTPUT_PATH]
[--qemu-cpu-model QEMU_CPU_MODEL]
optional arguments:
-h, --help show this help message and exit
--image-input-path IMAGE_INPUT_PATH
The path to the image that is to be configured (default: generated-images/image.qcow2)
---image-qemu-socket-path IMAGE_QEMU_SOCKET_PATH
The path to where the QEMU monitor socket should be placed which is used to send commands to the running image while it is being configured. (default:
generated-images/qemu-monitor-socket)
--config-user-data-path CONFIG_USER_DATA_PATH
The path to the cloud-init user-data configuration file (default: cloud-init-config/user-data)
--config-meta-data-path CONFIG_META_DATA_PATH
The path to the cloud-init meta-data configuration file (default: cloud-init-config/meta-data)
--config-vendor-data-path CONFIG_VENDOR_DATA_PATH
The path to the cloud-init vendor-data configuration file (default: cloud-init-config/vendor-data)
--config-seed-output-path CONFIG_SEED_OUTPUT_PATH
The path to the cloud-init output seed image file that is generated based on the data defined in the user-data, meta-data, and vendor-data configs
(default: image-config/seed.img)
--qemu-cpu-model QEMU_CPU_MODEL
The default cpu model for configuring the image (default: host)
To configure the image, the `configure-vm-image` tool starts an instance of the image and sends commands to the running image via the QEMU monitor socket.
The configuration files for cloud-init should be defined beforehand and the tool requires that the to be configured image supports cloud-init.
To configure the built VM image disk with the default values, `make configure` can be run in the root directory of the project::
make configure
------------------------
Putting it all togeather
------------------------
To build and configure a VM image disk with the default values, `make` can be run in the root directory of the project::
make
The build and configure steps can be specialized via each of the respected Makefile parameters `BUILD_ARGS` and `CONFIGURE_ARGS`.
An example of this can be seen below::
make BUILD_ARGS="--architecture-path examples/architecture.yml" CONFIGURE_ARGS="--image-input-path output-images/image.qcow2"
Raw data
{
"_id": null,
"home_page": "https://github.com/ucphhpc/gen-vm-image",
"name": "gen-vm-image",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Virtual Machine, VM, Images",
"author": "Rasmus Munk",
"author_email": "munk1@live.dk",
"download_url": "https://files.pythonhosted.org/packages/68/db/510addb3e132563288d79a47772e0ff4922e6c7f0acd70532e684525bad0/gen-vm-image-0.0.0a0.tar.gz",
"platform": null,
"description": "============\ngen-vm-image\n============\n\nThis package can be used for generating and configuring virtual machine images.\n\n------------\nDependencies\n------------\n\nThe dependencies required to use this package to generate virtual machine images\ncan be found in the `dep` directory for the supported distributions.\n\n-----\nSetup\n-----\n\nThe `qemu-kvm` command might not be available in the default PATH.\nThis can be determined via the `which` command::\n\n which qemu-kvm\n\nIf the command is not available, the qemu-kvm might be in a different location that is not part of\nyour current PATH. In this case, you can create a symbolic link to the qemu-kvm command in a directory\n\nAn example of this could be::\n\n ln -s /usr/share/bash-completion/completions/qemu-kvm /usr/local/bin/qemu-kvm\n\nThe `gen-vm-image` command can be used to generate virtual machine images for the supported distributions.\nTo define which images should be generated, architecture.yml file should be created and defined beforehand.\n\n-----------------------------\nBuild a Virtual Machine Image\n-----------------------------\n\nBefore an image can be generated, you first have to create an architecture file that defines which images should be built.\nWhat name this architecture file is given is not important, but it should be in YAML format and contain the following structure::\n\n owner: <string> # The owner of the image\n images: <key-value pair> # The images to be generated\n <image-name>:\n name: <string> # The name of the image\n version: <string> # The version of the image\n get_url: <string> # The URL to download the image from\n checksum:\n type: <string> # The type of checksum that should be used to validate the image. For valid types, see the supported algorithms `Here <https://docs.python.org/3/library/hashlib.html#hashlib.new>`_\n value: <string> # The checksum value that should be used to validate the image\n size: <string> # The size of the to be generated vm image disk, can use suffixes such as 'K', 'M', 'G', 'T'.\n\nAn example of such a file can be found in the `examples` directory.\n\nUpon creating such a file, the `gen-vm-image` command can be used to generate the virtual machine image.\nThe totality of the command can be seen below::\n\n usage: gen-vm-image [-h] [--architecture-path ARCHITECTURE_PATH]\n [--image-output-path IMAGE_OUTPUT_PATH]\n [--generated-image-owner GENERATED_IMAGE_OWNER]\n [--generate-gocd-config]\n [--gocd-config-name GOCD_CONFIG_NAME]\n [--gocd-build-branch GOCD_BUILD_BRANCH]\n\n optional arguments:\n -h, --help show this help message and exit\n --architecture-path ARCHITECTURE_PATH\n The path to the architecture file that is used to configure the images to be built (default: architecture.yml)\n --image-output-path IMAGE_OUTPUT_PATH\n The output path of the built image (default: generated-images/image.qcow2)\n --generated-image-owner GENERATED_IMAGE_OWNER\n Set the uid owner of the configured image (default: qemu)\n --generate-gocd-config\n Generate a GoCD config based on the architecture file (default: False)\n --gocd-config-name GOCD_CONFIG_NAME\n Name of the generated gocd config file (default: 1.gocd.yml)\n --gocd-build-branch GOCD_BUILD_BRANCH\n The branch that GoCD should use to build images (default: main)\n\nWhen the ``gen-vm-image`` command is executed, the generated VM disk image will be placed in the ``--image-output-path`` directory.\n\nIf every default value is acceptable, the VM image can be built by simply running ``make build`` in the root directory of the project::\n\n make build\n\n\n---------------------------------\nConfigure a Virtual Machine Image\n---------------------------------\n\nTo configure a built VM image disk, the `configure-vm-image` command can be used.\nThis tool uses cloud-init to configure the image, and the configuration files for cloud-init should be defined beforehand.\nTherefore, the tool requires that the to be configured image supports cloud-init, a list of various distributions cloud-init images can be found below.\n\n- `Rocky <https://download.rockylinux.org/pub/rocky/>`_\n- `Debian <https://cloud.debian.org/images/cloud/>`_\n- `Ubuntu <https://cloud-images.ubuntu.com/>`_\n- `Fedora <https://mirrors.dotsrc.org/fedora-enchilada/linux/releases/39/Cloud/>`_\n\n\nThe default location from where these are expected to be found can be discovered by running the command with the ``--help`` flag::\n\n usage: configure_image.py [-h] [--image-input-path IMAGE_INPUT_PATH]\n [---image-qemu-socket-path IMAGE_QEMU_SOCKET_PATH]\n [--config-user-data-path CONFIG_USER_DATA_PATH]\n [--config-meta-data-path CONFIG_META_DATA_PATH]\n [--config-vendor-data-path CONFIG_VENDOR_DATA_PATH]\n [--config-seed-output-path CONFIG_SEED_OUTPUT_PATH]\n [--qemu-cpu-model QEMU_CPU_MODEL]\n\n optional arguments:\n -h, --help show this help message and exit\n --image-input-path IMAGE_INPUT_PATH\n The path to the image that is to be configured (default: generated-images/image.qcow2)\n ---image-qemu-socket-path IMAGE_QEMU_SOCKET_PATH\n The path to where the QEMU monitor socket should be placed which is used to send commands to the running image while it is being configured. (default:\n generated-images/qemu-monitor-socket)\n --config-user-data-path CONFIG_USER_DATA_PATH\n The path to the cloud-init user-data configuration file (default: cloud-init-config/user-data)\n --config-meta-data-path CONFIG_META_DATA_PATH\n The path to the cloud-init meta-data configuration file (default: cloud-init-config/meta-data)\n --config-vendor-data-path CONFIG_VENDOR_DATA_PATH\n The path to the cloud-init vendor-data configuration file (default: cloud-init-config/vendor-data)\n --config-seed-output-path CONFIG_SEED_OUTPUT_PATH\n The path to the cloud-init output seed image file that is generated based on the data defined in the user-data, meta-data, and vendor-data configs\n (default: image-config/seed.img)\n --qemu-cpu-model QEMU_CPU_MODEL\n The default cpu model for configuring the image (default: host)\n\nTo configure the image, the `configure-vm-image` tool starts an instance of the image and sends commands to the running image via the QEMU monitor socket.\nThe configuration files for cloud-init should be defined beforehand and the tool requires that the to be configured image supports cloud-init.\n\nTo configure the built VM image disk with the default values, `make configure` can be run in the root directory of the project::\n\n make configure\n\n------------------------\nPutting it all togeather\n------------------------\n\nTo build and configure a VM image disk with the default values, `make` can be run in the root directory of the project::\n\n make\n\nThe build and configure steps can be specialized via each of the respected Makefile parameters `BUILD_ARGS` and `CONFIGURE_ARGS`.\nAn example of this can be seen below::\n\n make BUILD_ARGS=\"--architecture-path examples/architecture.yml\" CONFIGURE_ARGS=\"--image-input-path output-images/image.qcow2\"\n",
"bugtrack_url": null,
"license": "MIT",
"summary": null,
"version": "0.0.0a0",
"project_urls": {
"Homepage": "https://github.com/ucphhpc/gen-vm-image"
},
"split_keywords": [
"virtual machine",
" vm",
" images"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "348f4754e035e5a62d3c907f88d7bc0329677714f1cfdbac595ef05ca83343d6",
"md5": "1a852c0a5f192da9f10a2b8848a49c85",
"sha256": "45da42a33c7f0e1eeae031c1ac98a5c3a5654c21c5d665b2a27fe24c577c73ad"
},
"downloads": -1,
"filename": "gen_vm_image-0.0.0a0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a852c0a5f192da9f10a2b8848a49c85",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12765,
"upload_time": "2024-04-11T11:06:29",
"upload_time_iso_8601": "2024-04-11T11:06:29.270664Z",
"url": "https://files.pythonhosted.org/packages/34/8f/4754e035e5a62d3c907f88d7bc0329677714f1cfdbac595ef05ca83343d6/gen_vm_image-0.0.0a0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "68db510addb3e132563288d79a47772e0ff4922e6c7f0acd70532e684525bad0",
"md5": "3027c37707dcdcec7f1a8a95db599cf7",
"sha256": "0a87f52fd4fa7a91c33c2be43618098cbdc57f11a2c8181da62550ee7eaab66d"
},
"downloads": -1,
"filename": "gen-vm-image-0.0.0a0.tar.gz",
"has_sig": false,
"md5_digest": "3027c37707dcdcec7f1a8a95db599cf7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10969,
"upload_time": "2024-04-11T11:06:31",
"upload_time_iso_8601": "2024-04-11T11:06:31.519577Z",
"url": "https://files.pythonhosted.org/packages/68/db/510addb3e132563288d79a47772e0ff4922e6c7f0acd70532e684525bad0/gen-vm-image-0.0.0a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-11 11:06:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ucphhpc",
"github_project": "gen-vm-image",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "PyYaml",
"specs": []
},
{
"name": "argparse",
"specs": []
},
{
"name": "jinja2",
"specs": []
},
{
"name": "wget",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "tqdm",
"specs": []
}
],
"lcname": "gen-vm-image"
}
JSON
