vboxmanage-cloud

List the instances in the specified state belonging to the specified compartment

$ VBoxManage cloud --provider=[provider_name] --profile=[profile_name] list instances --state=[running|terminated|paused] --compartment-id=[compartment_id]

$ VBoxManage cloud --provider=[provider_name] --profile=[profile_name] instance create --domain-name=[domain_name] --image-id=[image_id]

$ VBoxManage cloud --provider=[provider_name] --profile=[profile_name] instance info --id=[unique_id]

$ VBoxManage cloud --provider=[provider_name] --profile=[profile_name] instance terminate --id=[unique_id]

$ VBoxManage cloud --provider=[provider_name] --profile=[profile_name] list images --compartment-id=[compartment_id] --state=[state_name]

$ VBoxManage cloud --provider=[provider_name] --profile=[profile_name] image create --instance-id=[instance_id] --display-name=[display_name] --compartment-id=[compartment_id]

$ VBoxManage cloud --provider=[provider_name] --profile=[profile_name] image info --id=[unique_id]

$ VBoxManage cloud --provider=[provider_name] --profile=[profile_name] image delete --id=[unique_id]

vboxmanage-cloud [OPTIONS] <input_disk_image> <output_disk_image>

<input_disk_image>
    Path to the existing VirtualBox disk image (e.g., VDI, VMDK) to be cloud-enabled.

<output_disk_image>
    Path where the new, cloud-init ready disk image will be saved.

--user-data FILE
    Specifies the path to a file containing cloud-init user-data to be injected.

--meta-data FILE
    Specifies the path to a file containing cloud-init meta-data to be injected.

--network-config FILE
    Specifies the path to a file containing cloud-init network configuration.

--force
    Overwrites the <output_disk_image> if it already exists.

--iso-path PATH
    Optional path to save the generated cloud-init ISO file, if one is used internally.

--vm-name NAME
    Optional name for any temporary VirtualBox VM created during the process.

--memory MB
    Optional memory allocation (in MB) for any temporary VirtualBox VM.

--cpus N
    Optional number of CPUs for any temporary VirtualBox VM.

--output-format FORMAT
    Optional output disk image format (e.g., VDI, VMDK, RAW).

The vboxmanage-cloud command is typically a project-specific or custom script designed to facilitate the integration of VirtualBox virtual machines with cloud-init, a widely used cross-platform cloud instance initialization system. Unlike standard VBoxManage subcommands, vboxmanage-cloud is not a universally provided utility but rather a wrapper or conceptual tool often found in development, testing, or specific automation environments (e.g., OpenStack DevStack, Vagrant setups).

Its primary purpose is to prepare a VirtualBox disk image (e.g., VDI or VMDK) so that a VM created from it can be automatically configured upon its first boot by cloud-init. This usually involves injecting or associating cloud-init configuration data such as user-data, meta-data, and network-config with the disk image. The underlying mechanism often involves creating a temporary VirtualBox VM, attaching a cloud-init generated ISO containing the configuration, and then exporting a new, 'cloud-ready' disk image, streamlining the process of creating self-provisioning VirtualBox instances.

The vboxmanage-cloud command is not a standard, universally available utility provided by Oracle VirtualBox itself. It typically refers to a custom script or a component within specific project environments (like OpenStack's DevStack or specialized cloud-image tools) that leverages VBoxManage and cloud-init functionalities. Therefore, its exact syntax, available options, and behavior can vary significantly depending on the specific implementation it comes from. Users should consult the documentation or source code of the project that provides this particular script.

This command is commonly used to take a clean, generic VirtualBox OS image and transform it into a self-configuring instance suitable for automated deployments, similar to how cloud images are consumed in AWS, OpenStack, or Azure. It's particularly useful for local development and testing cycles where quickly spinning up configured VMs is crucial.

While implementations vary, a common approach involves vboxmanage-cloud internally using VBoxManage to create a temporary VM from the input disk. It then utilizes cloud-localds (or a similar tool) to generate an ISO image containing the cloud-init data, attaches this ISO to the temporary VM, and boots it. Cloud-init inside the VM reads the configuration. After successful provisioning (or after a set time), the temporary VM is shut down, and its modified disk (or a snapshot of it) is exported as the output image.

The concept behind vboxmanage-cloud emerged from the increasing need to automate the provisioning of virtual machines in local development and testing environments using VirtualBox, mirroring the behavior of VMs in public cloud platforms. As cloud-init became the de-facto standard for cloud instance initialization, developers sought ways to easily inject cloud-init configuration into VirtualBox images. Rather than a formally developed command, vboxmanage-cloud typically represents a community-driven or project-specific effort to script this integration, often appearing in projects like OpenStack DevStack for local testing of cloud images, or within Vagrant box creation workflows.

VBoxManage(1), cloud-init(5), cloud-localds(1), virt-sysprep(1)