Skip to content

Commit

Permalink
os/booting-on-vmware: Polish lang/style.
Browse files Browse the repository at this point in the history
  • Loading branch information
Josh Wood committed Nov 12, 2015
1 parent a53b7c0 commit c036ddd
Showing 1 changed file with 56 additions and 65 deletions.
121 changes: 56 additions & 65 deletions os/booting-on-vmware.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
# Running CoreOS on VMware
# Running CoreOS on VMWare

These instructions will walk you through running CoreOS on VMware Fusion or
ESXi. If you are familiar with another VMware product you can use these
instructions as a starting point.
These instructions walk through running CoreOS 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

Expand All @@ -19,7 +17,7 @@ CoreOS is released into stable, alpha and beta channels. Releases to each channe
<div class="tab-content coreos-docs-image-table">
<div class="tab-pane active" id="stable">
<div class="channel-info">
<p>Versions of CoreOS are battle-tested within the Beta and Alpha channels before being promoted. Current version is CoreOS {{site.stable-channel}}.</p>
<p>Versions of CoreOS are battle-tested within the Beta and Alpha channels before being promoted. The current version is CoreOS {{site.stable-channel}}.</p>
</div>
<pre>curl -LO http://stable.release.core-os.net/amd64-usr/current/coreos_production_vmware_ova.ova</pre>
</div>
Expand All @@ -40,84 +38,77 @@ CoreOS is released into stable, alpha and beta channels. Releases to each channe

[release notes]: https://coreos.com/releases/

### Booting with VMware Fusion
### Booting with VMWare Fusion

After downloading the proper VMware image, you will need to launch the
`coreos_production_vmware_ova.ova` file to create a VM.
After downloading the VMWare OVA image for your selected channel, open the `coreos_production_vmware_ova.ova` file to create a VM.

### Booting with VMware ESXi
### 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 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"
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"

NOTE: Unselect "Power on after deployment" so you have a chance to edit VM
settings before powering it up for the first time.
Uncheck `Power on after deployment` in order to edit the VM before booting it the first time.

The last step uploads the files to your ESXi datastore and registers your VM.
You can now tweak the VM settings, like memory and virtual cores, then power it
on. These instructions were tested to deploy to an ESXi 5.5 host.
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.

### Booting with VMware Workstation 12
*NB: These instructions were tested with an ESXi v5.5 host.*

Run VMware Workstation GUI:
### Booting with VMWare Workstation 12

1. in the menu, click "File > Open..."
2. in the wizard, specify the location of the OVA downloaded earlier
3. name your VM and then click "Import"
4. press "Retry" if VMware Workstation has raised "OVF specification" warning
5. edit VM settings if necessary
6. start up your CoreOS VM
Run VMWare Workstation GUI:

## Cloud-Config
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. Start your CoreOS VM

Cloud-config can be specified by attaching a [config-drive][config-drive] with the filesystem label `config-2`. This is commonly done through whatever interface allows for attaching CD-ROMs or new drives. Alternatively in CoreOS 801.0.0 and greater you can use [VMware GuestInfo](#vmware-backdoor).
## Cloud-config

Note that the config-drive standard was originally an OpenStack feature, which
is why you'll see strings containing `openstack`. This filepath needs to be
retained, although CoreOS supports config-drive on all platforms.
Cloud-config data can be passed into a VM by attaching a [config-drive][config-drive] with the filesystem label `config-2`. This is done in the same way as attaching CD-ROMs or other new drives.

For more information on customization that can be done with cloud-config, head
on over to the [cloud-config guide][cloud-config guide].
The config-drive standard was originally an OpenStack feature, which is why you'll see the string `openstack` in a few bits of configuration. This naming convention is retained, although CoreOS supports config-drive on all platforms.

The `$private_ipv4` and `$public_ipv4` substitution variables are fully supported in cloud-config on VMware but only in CoreOS release 801.0.0 and greater. These releases has updated [coreos-cloudinit][coreos-cloudinit] v1.6.0 which allows you to configure network using [VMware GuestInfo options][vmware backdoor] and define `public` and `private` roles for ethernet interfaces.
The cloud-config `$private_ipv4` and `$public_ipv4` substitution variables are supported on VMWare in CoreOS releases 801.0.0 and greater.

## VMware Backdoor
For details on the options available with cloud-config, see the [cloud-config guide][cloud-config guide].

### Setting GuestInfo Options
## VMWare Guestinfo Interface

Guestinfo settings are values stored in the VMX of virtual machine or in the VMX representation in host memory. The criteria for being able to read it from guest OS is to use the prefix: `guestinfo.`.
### Setting Guestinfo Options

These settings can be set in five main ways:
The VMWare guestinfo interface is an alternative to using a config-drive 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:

* You can configure them in the OVF you want to deploy. Some middlewares will help you to customize it during the deploy of the virtual machines based on this OVF (like [vcloud director][vcloud director]). For more information, you can have a look on the following post: [Self-Configuration and the OVF Environment][ovf-selfconfig]
* Configure guestinfo in the OVF for deployment. Software like [vcloud director][vcloud director] manipulates OVF descriptors for guest configuration. For details, check out this VMWare blog post about [Self-Configuration and the OVF Environment][ovf-selfconfig].

* You can set guestinfo keys and values from the CoreOS guest itself by using preinstalled vmwaretools command like:
* Set guestinfo keys and values from the CoreOS guest itself, by using a vmwaretools command like:

```sh
/usr/share/oem/bin/vmtoolsd --cmd "info-set guestinfo.<variable> <value>"
```

* You can also set guestinfo keys and values from a Service Console:
* Guestinfo keys and values can be set from a VMWare Service Console, using the `setguestinfo` subcommand:

```sh
vmware-cmd /vmfs/volumes/xxxxxxxx.../VMNAME/VMNAME.vmx setguestinfo <variable> <value>
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 the vCenter.
* You can manually modify the VMX and reload it on the VMWare Workstation, ESXi host, or in vCenter.

* If you change or set GuestInfo settings by using VMware API or CoreOS guest itself, values are only stored in VM process memory. In case of reboot or shutdown, values will be loosed.
Guestinfo configuration set via the VMWare API or with `vmtoolsd` from within the CoreOS guest itself are stored in VM process memory and are lost on VM shutdown or reboot.

You can read more about GuestInfo in [this][vmware-use-guestinfo] blog post.
[This blog post][vmware-use-guestinfo] has some useful details about the guestinfo interface, while Robert Labrie's blog provides a practicum specific to [using VMWare guestinfo to configure CoreOS VMs][labrie-guestinfo].

### GuestInfo Example
### Guestinfo Example

Example below provides hostname, DNS address, interface role, and static `192.168.178.97` IP address with `255.255.255.0` netmask on the Ethernet interface which matches `eno1*` interface name and `00:0c:29:63:92:5c` interface mac address (you can simply provide only one match option: `name` or `mac`):
This example sets the hostname, interface role, static IP address, and several other network interface parameters to the VM ethernet interface matching the `.mac` and `.name` values given in the following VMX snippet:

```
guestinfo.hostname = "coreos"
Expand All @@ -131,7 +122,7 @@ guestinfo.interface.0.dhcp = "no"
guestinfo.interface.0.ip.0.address = "192.168.178.97/24"
```

The CoreOS OVA image contains VMware tools and OEM Cloud-Config which executes `coreos-cloudinit` with `--oem=vmware` option. This option automatically sets the `-from-vmware-backdoor` and `-convert-netconf=vmware` flags. Using values above and these flags `coreos-cloudinit` will generate following systemd network unit:
The CoreOS OVA image contains the VMWare tools, and a OEM cloud-config which executes `coreos-cloudinit` with the `--oem=vmware` option. This option automatically sets the additional `--from-vmware-guestinfo` and `--convert-netconf=vmware` flags. Given the `guestinfo.*` values above and these option flags, `coreos-cloudinit` will generate the following systemd network unit:

```
[Match]
Expand All @@ -149,18 +140,20 @@ Destination=0.0.0.0/0
Gateway=192.168.178.1
```

This unit file will configure the matching network interface. If you have set `guestinfo.coreos.config.data` or `guestinfo.coreos.config.url` variables, `coreos-cloudinit` will try to apply these Cloud Configs on VM and substitute `$private_ipv4` and `$public_ipv4` variables if you've configured network interfaces' roles using `interface.<n>.role` guest variable.
This unit file will subsequently configure the matching network interface.

### Defining Cloud-Config in GuestInfo
### Defining Cloud-config in Guestinfo

There are two supported encoding types, which can be configured with the `guestinfo.coreos.config.data.encoding` variable:
If either the `guestinfo.coreos.config.data` or `guestinfo.coreos.config.url` property is set, `coreos-cloudinit` will apply the referenced cloud-config. Cloudinit will substitute the `$private_ipv4` and `$public_ipv4` variables if you've configured network interface roles using the `guestinfo.interface.<n>.role` property.

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

| Encoding | Command |
|:------------|:--------------------------------------------------|
| base64 | `base64 -w0 /path/to/user_data && echo` |
| gzip+base64 | `gzip -c /path/to/user_data | base64 -w0 && echo` |

To avoid having to `base64`, you can retrieve your Cloud-Config from a URL with the `guestinfo.coreos.config.url` variable.
To avoid having to `base64` or otherwise encode raw data into your VMX, you can retrieve your cloud-config from a URL specified in the `guestinfo.coreos.config.url` variable instead.

#### Example

Expand All @@ -177,38 +170,36 @@ ssh_authorized_keys:
- ssh-rsa mypubkey
```
Please refer to [vmware backdoor][vmware backdoor] for full options list.
Refer to the [VMWare guestinfo variables documentation][vmware guestinfo] for a full list of supported properties.
## Logging in
Networking can take a bit of time to come up under VMware and you will need to
know the IP in order to SSH in. Press enter a few times at the login prompt and
you should see an IP address pop up:
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](img/vmware-ip.png)
![VMWare IP Address](img/vmware-ip.png)
In this case the IP is `10.0.1.81`.

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

```sh
ssh [email protected]
```

Alternatively, if you append `coreos.autologin` to the kernel parameters on
boot, the console won't prompt for a password. This is handy for debugging.
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

Now that you have a machine booted it is time to play around. Check out the
[CoreOS Quickstart][quickstart] guide or dig into [more specific topics][docs].
Now that you have a machine booted, it's time to explore. Check out the [CoreOS Quickstart][quickstart] guide, or dig into [more specific topics][docs].

[quickstart]: quickstart.md
[docs]: https://github.com/coreos/docs
[config-drive]: https://github.com/coreos/coreos-cloudinit/blob/master/Documentation/config-drive.md
[cloud-config guide]: https://github.com/coreos/coreos-cloudinit/blob/master/Documentation/cloud-config.md
[coreos-cloudinit]: https://github.com/coreos/coreos-cloudinit
[vmware backdoor]: https://github.com/coreos/coreos-cloudinit/blob/master/Documentation/vmware-guestinfo.md
[vmware guestinfo]: https://github.com/coreos/coreos-cloudinit/blob/master/Documentation/vmware-guestinfo.md
[vcloud director]: http://blogs.vmware.com/vsphere/2012/06/leveraging-vapp-vm-custom-properties-in-vcloud-director.html
[ovf-selfconfig]: http://blogs.vmware.com/vapp/2009/07/selfconfiguration-and-the-ovf-environment.html
[vmware-use-guestinfo]: http://blog-lrivallain.rhcloud.com/2014/08/15/vmware-use-guestinfo-variables-to-customize-guest-os/
[labrie-guestinfo]: https://robertlabrie.wordpress.com/2015/09/27/coreos-on-vmware-using-vmware-guestinfo-api/

0 comments on commit c036ddd

Please sign in to comment.