cloud-images/README.md

# MSVSphere Cloud Images

[Packer](https://www.packer.io/) templates and configuration files for
building MSVSphere images for various cloud platforms.


## Build environment configuration

Supported operating systems:

  * MSVSphere 9 and other EL9-compatible distributions
  * Fedora

First install Ansible, which we use for virtual machines provisioning:

```shell
$ dnf install ansible-core
```

Then follow the Packer installation [instructions](https://developer.hashicorp.com/packer/downloads?product_intent=packer).

Alternatively, you can install a Packer binary from a Yandex
[mirror](https://hashicorp-releases.yandexcloud.net/packer/): just download a
latest version archive and unzip it somewhere in PATH (e.g. `~/.local/bin`).

Verify that Packer works:

```shell
$ packer version
1.9.4
```

In order to install required Packer plugins run the following command in the
project root:

```shell
$ packer init -upgrade .
```

Dependently on your network configuration, you may also need to open the
8000-9000 TCP port range so that Packer can serve kickstart files to VMs:

```shell
$ firewall-cmd --zone=public --add-port=8000-9000/tcp --permanent
$ firewall-cmd --reload
```

You will also need to install either QEMU/KVM or VirtualBox or
VMWare Workstation, depending on what types of images you are going to build.

For VirtualBox and VMWare Workstation just follow the official site
documentation.

The QEMU/KVM installation instructions are provided below:

```shell
# for MSVSphere 9
$ dnf install edk2-ovmf libvirt libvirt-daemon-kvm

# for Fedora
$ dnf install @virtualization
$ dnf install edk2-ovmf
```


## Building images

In order to build an image use the following command syntax:

```shell
$ packer build -only=${BUILDER}.${CONFIGURATION} .
```

where `${BUILDER}` is a Packer builder (e.g. `virtualbox-iso`) and
`${CONFIGURATION}` is an image configuration name (e.g. 
`msvsphere-9-vagrant-x86_64`).

On Fedora you might need to provide extra options because it has different
paths for qemu-kvm and edk2 firmware:

```shell
$ packer build -var qemu_binary=/usr/bin/qemu-kvm \
      -var uefi_ovmf_code=/usr/share/OVMF/OVMF_CODE.fd \
      -var uefi_ovmf_vars=/usr/share/OVMF/OVMF_VARS.fd \
      -only=${BUILDER}.${CONFIGURATION} .
```

A graphical VM console is disabled by default, but you can enable it for
debugging purposes by setting the `headless` variable to `false`:

```shell
$ packer build -only=vmware-iso.msvsphere-9-vagrant-x86_64 \
               -var headless=false .
```

See the [variables.pkr.hcl](variables.pkr.hcl) file for other supported
variables.


### Building Generic Cloud images

Generic Cloud image build command:

```shell
$ packer build -only=qemu.msvsphere-9-gencloud-x86_64 .
```


### Building Vagrant boxes

VirtualBox Vagrant box build command:

```shell
$ packer build -only=virtualbox-iso.msvsphere-9-vagrant-x86_64 .
```

VMWare Vagrant box build command:

```shell
$ packer build -only=vmware-iso.msvsphere-9-vagrant-x86_64 .
```

## Debugging image builds

Use `PACKER_LOG=1` environment variable definition to get extra debug output
from Packer:

```shell
$ PACKER_LOG=1 packer build ...
```

other Packer debugging techniques are described in the Packer
[documentation](https://developer.hashicorp.com/packer/docs/debugging).

Add `-vvvv` flag to the Ansible's `extra_arguments` block in a Packer config
in order to get verbose output from Ansible:

```hcl
build {
  provisioner "ansible" {
    ...
    extra_arguments = [..., "-vvvv"]
  }
}
```

Additionally, you can connect to Packer's VNC session using a VNC client.
For TigerVNC you will need to enable the following settings:

* Input -> View only (ignore mouse and keyboard)
* Misc -> Shared (don't disconnect other viewers)

By default Packer is running a VNC server on a random TCP port in the
5900:6000 range. But for remote build environments it might be useful
to use a specific port so that you can configure a firewall easily:

```shell
$ packer build ... -var vnc_bind_address=0.0.0.0 -var vnc_port_min=5900 \
      -var vnc_port_max=5900 .
```

## License

Licensed under the MIT license, see the [LICENSE](LICENSE) file for details.