Running CoreOS Container Linux on VMware

These instructions walk through running Container Linux on VMware Fusion or ESXi. If you are familiar with another VMware product, you can use these instructions as a starting point.

Running the VM

Choosing a channel

Container Linux is designed to be updated automatically with different schedules per channel. You can disable this feature, although we don't recommend it. Read the release notes for specific features and bug fixes.

The Stable channel should be used by production clusters. Versions of Container Linux are battle-tested within the Beta and Alpha channels before being promoted. The current version is Container Linux 1353.7.0.

curl -LO https://stable.release.core-os.net/amd64-usr/current/coreos_production_vmware_ova.ova

The Alpha channel closely tracks master and is released frequently. The newest versions of system libraries and utilities will be available for testing. The current version is Container Linux 1423.0.0.

curl -LO https://alpha.release.core-os.net/amd64-usr/current/coreos_production_vmware_ova.ova

The Beta channel consists of promoted Alpha releases. The current version is Container Linux 1409.1.0.

curl -LO https://beta.release.core-os.net/amd64-usr/current/coreos_production_vmware_ova.ova

Booting with VMware ESXi

Use the vSphere Client to deploy the VM as follows:

  1. In the menu, click File > Deploy OVF Template...
  2. In the wizard, specify the location of the OVA file downloaded earlier
  3. Name your VM
  4. Choose "thin provision" for the disk format
  5. Choose your network settings
  6. Confirm the settings, then click "Finish"

Uncheck Power on after deployment in order to edit the VM before booting it the first time.

The last step uploads the files to the ESXi datastore and registers the new VM. You can now tweak VM settings, then power it on.

NB: These instructions were tested with an ESXi v5.5 host.

Booting with VMware Workstation 12 or VMware Fusion

Run VMware Workstation GUI:

  1. In the menu, click File > Open...
  2. In the wizard, specify the location of the OVA template downloaded earlier
  3. Name your VM, then click Import
  4. (Press Retry if VMware Workstation raises an "OVF specification" warning)
  5. Edit VM settings if necessary
  6. Modify the .vmx file to pass an Ignition config containing at least one valid SSH key
  7. Start your Container Linux VM

NB: These instructions were tested with a Fusion 8.1 host.

Installing via PXE or ISO image

Container Linux can also be installed by booting the virtual machine via PXE or the ISO image and then installing Container Linux to disk.

Container Linux Configs

Container Linux allows you to configure machine parameters, configure networking, launch systemd units on startup, and more via Container Linux Configs. These configs are then transpiled into Ignition configs and given to booting machines. Head over to the docs to learn about the supported features.

You can provide a raw Ignition config to Container Linux via VMware's Guestinfo interface.

As an example, this config will start etcd:

This is the human-readable config file. This should not be immediately passed to Container Linux. Learn more.
# This config is meant to be consumed by the config transpiler, which will
# generate the corresponding Ignition config. Do not pass this config directly
# to instances of Container Linux.

etcd:
  # All options get passed as command line flags to etcd.
  # Any information inside curly braces comes from the machine at boot time.

  # vmware isn't currently supported for dynamic data, so we can't use {PRIVATE_IPV4}
  advertise_client_urls:       "http://10.0.0.10:2379"
  initial_advertise_peer_urls: "http://10.0.0.10:2380"
  # listen on both the official ports and the legacy ports
  # legacy ports can be omitted if your application doesn't depend on them
  listen_client_urls:          "http://0.0.0.0:2379"
  listen_peer_urls:            "http://10.0.0.10:2380"
  # generate a new token for each unique cluster from https://discovery.etcd.io/new?size=3
  # specify the initial size of your cluster with ?size=X
  discovery:                   "https://discovery.etcd.io/<token>"
This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
{
  "ignition": {
    "version": "2.0.0",
    "config": {}
  },
  "storage": {},
  "systemd": {
    "units": [
      {
        "name": "etcd-member.service",
        "enable": true,
        "dropins": [
          {
            "name": "20-clct-etcd-member.conf",
            "contents": "[Service]\nExecStart=\nExecStart=/usr/lib/coreos/etcd-wrapper $ETCD_OPTS \\\n  --listen-peer-urls=\"http://10.0.0.10:2380\" \\\n  --listen-client-urls=\"http://0.0.0.0:2379\" \\\n  --initial-advertise-peer-urls=\"http://10.0.0.10:2380\" \\\n  --advertise-client-urls=\"http://10.0.0.10:2379\" \\\n  --discovery=\"https://discovery.etcd.io/\u003ctoken\u003e\""
          }
        ]
      }
    ]
  },
  "networkd": {},
  "passwd": {}
}

VMware Guestinfo interface

Setting Guestinfo options

The VMware guestinfo interface is a mechanism for VM configuration. Guestinfo properties are stored in the VMX file, or in the VMX representation in host memory. These properties are available to the VM at boot time. Within the VMX, the names of these properties are prefixed with guestinfo.. Guestinfo settings can be injected into VMs in one of four ways:

  • Configure guestinfo in the OVF for deployment. Software like vcloud director manipulates OVF descriptors for guest configuration. For details, check out this VMware blog post about Self-Configuration and the OVF Environment.

  • Set guestinfo keys and values from the Container Linux guest itself, by using a VMware Tools command like:

/usr/share/oem/bin/vmtoolsd --cmd "info-set guestinfo.<variable> <value>"
  • Guestinfo keys and values can be set from a VMware Service Console, using the setguestinfo subcommand:
vmware-cmd /vmfs/volumes/[...]/<VMNAME>/<VMNAME>.vmx setguestinfo guestinfo.<property> <value>
  • You can manually modify the VMX and reload it on the VMware Workstation, ESXi host, or in vCenter.

Guestinfo configuration set via the VMware API or with vmtoolsd from within the Container Linux guest itself are stored in VM process memory and are lost on VM shutdown or reboot.

This blog post has some useful details about the guestinfo interface, while Robert Labrie's blog provides a practicum specific to using VMware guestinfo to configure Container Linux VMs.

Defining the Ignition config in Guestinfo

If the guestinfo.coreos.config.data property is set, Ignition will apply the referenced config on first boot.

The Ignition config is prepared for the guestinfo facility in one of two encoding types, specified in the guestinfo.coreos.config.data.encoding variable:

Encoding Command
<elided> sed -e 's/%/%%/g' -e 's/"/%22/g' /path/to/user_data
base64 base64 -w0 /path/to/user_data && echo

Example

guestinfo.coreos.config.data = "ewogICJpZ25pdGlvbiI6IHsgInZlcnNpb24iOiAiMi4wLjAiIH0KfQo="
guestinfo.coreos.config.data.encoding = "base64"

This example will be decoded into:

{
  "ignition": { "version": "2.0.0" }
}

Logging in

Networking can take some time to start under VMware. Once it does, press enter a few times at the login prompt and you should see an IP address printed on the console:

VMware IP Address

In this case the IP is 10.0.1.81.

Now you can login to the host at that IP using your SSH key, or the password set in your cloud-config:

ssh core@10.0.1.81

Alternatively, appending coreos.autologin to the kernel parameters at boot causes the console to accept the core user's login with no password. This is handy for debugging.

Using CoreOS Container Linux

Now that you have a machine booted, it's time to explore. Check out the Container Linux Quickstart guide, or dig into more specific topics.