Provisionando Fedora CoreOS no VMware

Este guia mostra como provisionar novos nós de Fedora CoreOS (FCOS) no 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.

Pré-requisitos

Antes de provisionar uma máquina FCOS, você deve ter um arquivo de configuração do Ignition contendo suas personalizações. Se você não tiver um, consulte Produzindo um arquivo de Ignition.

Fedora CoreOS tem um usuário padrão core que pode ser usado para explorar o sistema operacional. Se você quiser usá-lo, finalize sua configuração fornecendo, por exemplo, uma chave SSH.

You also need to have access to a working VMware infrastructure, supporting VMs with at least hardware version 13. The examples below use the govc command-line tool for remote vSphere provisioning and the ovftool for local Workstation or Fusion provisioning.

Baixando o OVA

O Fedora CoreOS é projetado para ser atualizado automaticamente, com horários diferentes por fluxo. Depois de escolher o fluxo relevante, você pode baixar o OVA mais recente:

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

Alternatively, OVA images can be manually downloaded from the download page.

Codificando a configuração do Ignition

Para o provedor vmware, o Ignition requer que dois campos "guestinfo" estejam presentes quando a VM for inicializada pela primeira vez:

  • guestinfo.ignition.config.data.encoding: a codificação da configuração do Ignition.

  • guestinfo.ignition.config.data: o conteúdo da configuração do Ignition, codificado de acordo com o formato acima.

Para compatibilidade máxima, é recomendado usar a codificação base64 e preparar a configuração do Ignition da seguinte forma:

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

An alternative to plain base64 encoding is gzip+base64 as described in the Ignition supported platforms. This is especially useful when submitting the Ignition config via govc as an inline argument. In that case the encoded config is limited to slightly under 128 KiB on Linux, 256 KiB on macOS, and 32 KiB on Windows (8 KiB if using cmd.exe or PowerShell). If your config is larger than that limit, you may be able to submit it inline after compressing it with 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

Inicializando uma nova VM no Workstation ou Fusion

Esta seção mostra como usar os recursos do Workstation e Fusion para configurar e executar VMs a partir da linha de comando. Algumas etapas podem, potencialmente, ser realizadas por meio da IU gráfica também.

Importando o OVA

O OVA baixado deve ser importado para a estação de trabalho ou biblioteca Fusion localmente. Ao mesmo tempo, a Ignition deve ser fornecida para que seja aplicada à 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}"

Depois, você pode atualizar a lista de VMs na IU do Workstation ou Fusion e a nova VM fcos-node01 deve aparecer pronta para inicialização. Sua configuração de hardware pode ser ainda mais personalizada neste ponto e, em seguida, ligada.

Se você configurar uma chave SSH para o usuário padrão core, poderá fazer um acesso via SSH para VM e explorar o sistema operacional:

ssh core@<endereço ip>

Inicializando uma nova VM no vSphere

Esta seção mostra como usar os recursos do vSphere para configurar e executar VMs a partir da linha de comando. Etapas semelhantes também podem ser realizadas por meio da IU gráfica.

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.

Configurando uma nova 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}"

Uma nova VM fcos-node01 agora está disponível para inicialização. Sua configuração de hardware pode ser ainda mais personalizada neste ponto e, em seguida, ligada:

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

Se você configurar uma chave SSH para o usuário padrão core, poderá fazer um acesso via SSH para VM e explorar o sistema operacional:

ssh core@<endereço ip>

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}"

Rede da primeira inicialização e Ignition

O Ignition oferece suporte para referenciar conteúdo remoto na configuração e buscá-lo no momento do provisionamento. Por esse motivo, na primeira inicialização, as instâncias do FCOS tentam realizar a configuração automática da rede via DHCP.

Se sua configuração do VMware emprega configuração de rede estática, você pode substituir essa configuração DHCP automática com sua própria configuração personalizada. O parâmetro ip= de linha de comando de rede personalizado pode ser configurado por meio das propriedades guestinfo conforme mostrado abaixo, antes de inicializar uma VM pela primeira vez.

O fluxo de provisionamento segue as etapas normais, além de uma entrada adicional guestinfo.afterburn.initrd.network-kargs.

se você estiver usando um método de provisionamento diferente de govc, certifique-se de que o atributo guestinfo seja provisionado nos parâmetros de configuração avançada da VM (também conhecido como ExtraConfig). Algumas ferramentas de gerenciamento podem usar como padrão uma propriedade vApp, o que não funciona neste cenário.
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}"

A sintaxe completa do parâmetro ip = está documentada nas páginas man do Dracut.

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.20241109.3.0-vmware.x86_64.ova
sed -iE 's/vmx-[0-9]*/vmx-13/' coreos.ovf
tar -H posix -cvf fedora-coreos-41.20241109.3.0-vmware-vmx-13.x86_64.ova coreos.ovf disk.vmdk