Aprovisionando Fedora CoreOS sobre VMware

Esta guía muestra como aprovisionar nuevos nodos Fedora CoreOS (FCOS) sobre el hipervisor VMware.

Fedora CoreOS supports VMware ESXi ≥ 7.0, VMware Workstation ≥ 16, and VMware Fusion ≥ 12. It may be possible to modify the metadata of the OVF to run in older VMware products, but compatibility and supportability cannot be guaranteed.

Requisitos previos

Antes de aprovisionar una máquina FCOS, usted debe tener un archivo de configuración Ignition que contenga sus personalizaciones. Si no tiene uno vea Produciendo un Archivo Ignition.

Fedora CoreOS tiene un usuario core predeterminado que puede ser usado para explorar el SO. Si usted desea utilizarlo finalice su configuración proporcionando una clave SSH.

Usted también necesita tener acceso a una infraestructura VMware en funcionamiento, que soporte MVs con una hardware de al menos versión 13. Los ejemplos de abajo utilizan la herramienta de línea de comandos govc para aprovisionamiento remoto vSphere y ovftool para aprovisionamiento local Workstation o Fusion.

Descargar la OVA

Fedora CoreOS está diseñado para ser actualizado automáticamente, con diferentes calendarios por flujo. Una vez que haya elegido el flujo relevante, puede descargar el último OVA:

STREAM="stable"
coreos-installer download -s "${STREAM}" -p vmware -f ova

Alternativamente, las imágenes OVA pueden ser descargadas manualmente desde la página de descargas.

Codificando la configuración Ignition

Para el proveedor vmware, Ignition requiere que estén presentes dos campos "guestinfo" la primera vez que se arranque la MV:

guestinfo.ignition.config.data.encoding: la codificación de la configuración Ignition.
guestinfo.ignition.config.data: el contenido de la configuración Ignition, codificada de acuerdo con el formato de arriba.

Para la máxima compatibilidad, se recomienda utilizar codificación base64 y prepara las configuración Ignition como tal:

CONFIG_ENCODING='base64'
CONFIG_ENCODED=$(cat example.ign | base64 -w0 -)

Una alternativa a la codificación plana base64 es gzip+base64 como se describe en plataformas soportadas por Ignition. Esto es especialmente útil cuando envía la configuración Ignition por medio de govc como argumento inline . En este caso la configuración codificada se limita a un poco menos de 128 Kb en Linux, 256 Kb en macOS y 32 Kb en Windows (8 Kb si utiliza cmd.exe o PowerShell). Si su configuración es mayor de este límite, usted puede enviarla en línea después de comprimirla con gzip.

CONFIG_ENCODING='gzip+base64'
CONFIG_ENCODED=$(cat example.ign | gzip -9 | base64 -w0 -)

If your generated Ignition configuration is still too large, you will encounter an Argument list too long error or similar. The solution to that problem depends on whether you are working with vSphere or Workstation/Fusion.

For vSphere, instead of inlining the configuration file within your shell, govc allows you to specify a path to a local file with the vm.change-command and will handle reading and writing it internally, circumventing any shell limitations.

CONFIG_ENCODING="gzip+base64"
CONFIG_FILE="example.ign"
CONFIG_FILE_ENCODED="${CONFIG_FILE}.gzip.b64"

gzip -9c "${CONFIG_FILE}" | base64 -w0 - > "${CONFIG_FILE_ENCODED}"

govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data.encoding=${CONFIG_ENCODING}"
govc vm.change -vm "${VM_NAME}" -f "guestinfo.ignition.config.data=${CONFIG_FILE_ENCODED}" # using `-f` with a file path instead of `-e`

Using gzip for this solution is optional and primarily used for consistent examples.

In the case of Workstation/Fusion, or as a last resort in general, there is the option to use a configuration file. Instead of setting an environment variable containing your Ignition configuration, create an ovftool compatible configuration file in the directory you are invoking from like so:

printf "extraConfig:guestinfo.ignition.config.data=$(cat example.ign | base64 -w0 -)\n" > ovftool.cfg

Booting a new VM on Workstation or Fusion

This section shows how to use Workstation and Fusion facilities to configure and run VMs from the command-line. Some steps can potentially be performed via the graphical UI too.

Importing the OVA

The downloaded OVA has to be imported into the Workstation or Fusion library locally. At the same time the Ignition has to be provided for it to be applied to the VM.

VM_NAME='fcos-node01'
FCOS_OVA='./ova-templates/fedora-coreos-31.20200210.3.0-vmware.x86_64.ova'
LIBRARY="$HOME/Virtual Machines.localized"
ovftool \
  --powerOffTarget \
  --name="${VM_NAME}" \
  --allowExtraConfig \
  --extraConfig:guestinfo.ignition.config.data.encoding="${CONFIG_ENCODING}" \
  --extraConfig:guestinfo.ignition.config.data="${CONFIG_ENCODED}" \
  "${FCOS_OVA}" "${LIBRARY}"

Afterwards you can refresh the list of VMs in the Workstation or Fusion UI and the new fcos-node01 VM should appear ready for booting. Its hardware configuration can be further customized at this point, and then powered-up.

Si ha establecido una clave SSH para el usuario core predeterminado, puede hacer SSH en la MV y explorar el SO:

ssh core@<ip address>

Booting a new VM on vSphere

This section shows how to use vSphere facilities to configure and run VMs from the command-line. Similar steps can be performed via the graphical UI too.

While the examples below use govc session.login to authenticate, you can also use environment variables to provide credentials. Check the official documentation for details.

Setting up a new VM

You can now deploy a new VM, starting from the OVA and the encoded Ignition configuration:

FCOS_OVA='./ova-templates/fedora-coreos-31.20200210.3.0-vmware.x86_64.ova'
VM_NAME='fcos-node01'
govc session.login -u 'user:password@host'
govc import.ova -name ${VM_NAME} ${FCOS_OVA}
govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data.encoding=${CONFIG_ENCODING}"
govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data=${CONFIG_ENCODED}"

A new fcos-node01 VM is now available for booting. Its hardware configuration can be further customized at this point, and then powered-up:

govc vm.info -e "${VM_NAME}"
govc vm.power -on "${VM_NAME}"

Si ha establecido una clave SSH para el usuario core predeterminado, puede hacer SSH en la MV y explorar el SO:

ssh core@<ip address>

Using the OVA from the vSphere library

In case you want to spawn multiple, different VMs based on the same base image you can import it into the vSphere library for easy reuse:

FCOS_OVA='./ova-templates/fedora-coreos-31.20200210.3.0-vmware.x86_64.ova'
LIBRARY='fcos-images'
TEMPLATE_NAME='fcos-31.20200210.3.0'
govc session.login -u 'user:password@host'
govc library.create "${LIBRARY}"
govc library.import -n "${TEMPLATE_NAME}" "${LIBRARY}" "${FCOS_OVA}"

Creating a new instance can now be done using the govc library.deploy command:

VM_NAME='fcos-node01'
govc library.deploy "${LIBRARY}/${TEMPLATE_NAME}" "${VM_NAME}"
govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data.encoding=${CONFIG_ENCODING}"
govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data=${CONFIG_ENCODED}"

Note: If the vCenter has multiple datacenters and datastores, you must specify them explicitly:

# Get resource pool using `$ govc find / -type ResourcePool`
RESOURCE_POOL="/Datacenter6.5/host/Cluster6.5/Resources"
DATASTORE="datastore-129"
govc library.deploy -pool=${RESOURCE_POOL} -ds=${DATASTORE} "${LIBRARY}/${TEMPLATE_NAME}" "${VM_NAME}"

First-boot networking and Ignition

Ignition supports referencing remote content in configuration and fetching it at provisioning time. For this reason, on first-boot FCOS instances try to perform network autoconfiguration via DHCP.

If your VMware setup employs static network configuration instead, you can override this automatic DHCP setup with your own custom configuration. Custom networking command-line ip= parameter can be configured via guestinfo properties as shown below, before booting a VM for the first time.

The provisioning flow follows the usual steps, plus an additional guestinfo.afterburn.initrd.network-kargs entry.

if you are using a provisioning method other than govc, make sure that the guestinfo attribute is provisioned in the VM’s Advanced Configuration Parameters (also known as ExtraConfig). Some management tools may default to a vApp Property instead, which does not work in this scenario.

VM_NAME='fcos-node02'
IFACE='ens192'
IPCFG="ip=192.0.2.42::192.0.2.1:255.255.255.0:${VM_NAME}:${IFACE}:off"

govc library.deploy "${LIBRARY}/${TEMPLATE_NAME}" "${VM_NAME}"
govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data.encoding=${CONFIG_ENCODING}"
govc vm.change -vm "${VM_NAME}" -e "guestinfo.ignition.config.data=${CONFIG_ENCODED}"
govc vm.change -vm "${VM_NAME}" -e "guestinfo.afterburn.initrd.network-kargs=${IPCFG}"
govc vm.info -e "${VM_NAME}"
govc vm.power -on "${VM_NAME}"

The full syntax of the ip= parameter is documented in Dracut manpages.

For further information on first-boot networking, see Afterburn documentation.

Troubleshooting First-boot Problems

You may encounter problems with your Ignition configuration that require access to the system log which appears during first-boot. To make a copy of the system log you can attach a serial device to the VM before booting. vSphere as well as Workstation and Fusion allow this and will save the output to a file of your choice.

To attach a serial device, modify the hardware settings of the powered off VM and add a Serial Port. Select the destination and name of the file to be created. Afterwards power on the VM. When encountering an error, check the file you initially specified - it should contain a copy of the system log.

The serial device can also be added to the VM via govc as described in the official usage documentation:

VM_NAME='fcos-node01'

govc device.serial.add -vm "${VM_NAME}"
govc device.serial.connect -vm "${VM_NAME}" "[datastore] ${VM_NAME}/console.log"

Modifying OVF metadata

While we provide these instructions for modifying the OVF metadata, we cannot guarantee that any modifications to the OVF metadata will result in a usable guest VM.

Fedora CoreOS is intended to run on generally supported releases of VMware ESXi, VMware Workstation, and VMware Fusion. Accordingly, the Fedora CoreOS VMware OVA image specifies a virtual hardware version that may not be compatible with older, unsupported VMware products. However, you can modify the image’s OVF metadata to specify an older virtual hardware version.

The VMware OVA is a tarball that contains the files disk.vmdk and coreos.ovf. In order to edit the metadata used by FCOS as a guest VM, you should untar the OVA artifact, edit the OVF file, then create a new OVA file.

The example commands below change the OVF hardware version from the preconfigured value to hardware version 13.

The defaults in the OVF are subject to change.

tar -xvf fedora-coreos-41.20241027.3.0-vmware.x86_64.ova
sed -iE 's/vmx-[0-9]*/vmx-13/' coreos.ovf
tar -H posix -cvf fedora-coreos-41.20241027.3.0-vmware-vmx-13.x86_64.ova coreos.ovf disk.vmdk

Want to help? Learn how to contribute to Fedora Docs ›