Picture: Rancher.com

Install RancherOS in Hyper-V

What's RancherOS ?

RancherOS is young, simplified open-source Linux distribution focused on containers. It contains only a minimum amount of software to run the most important part: Docker. The latest version - right now 1.5.0 - has only a footprint of 120 MB and starts in a few seconds. You can download RancherOS from GitHub.

By default the Docker engine is 18.06.1 but you can switch to different engine to support difference orchestrators like Kubernetes, Swarm, Mesos and their own cattle system.


RancherOS is very minimalistic but offers a full automatable configuration based on a YAML file.

The RancherOS Config File could look like:

  - ssh-rsa AAA...

    engine: docker-17.03.2-ce

This configuration contains a publish OpenSSH key; you need the private key to log into rancher via Putty. You can find here a documentation how to create an OpenSSH key pair. In this case docker version docker-17.03.2-ce is seletected. This is the latest version regarding the list of support docker versions for Kubernetes.

Set up Hyper-V VM

  1. create new virtual machine
  1. select Generation 1
  1. configure your RAM

I dont like dynamic RAM, so I use 8 GB of RAM which is enough for this sample

  1. select your network

I have created a network 'Internet' which is a bridge from Hyper-V to my network card

  1. select the ISO for first boot
  1. change settings

If you want to disable VM auto-start and increase the number of processors for your VM, open the VM settings after the VM was created

Install RancherOS

If you're ready with Hyper-V, you can start the VM. The boot from the ISO file will start a live system. This means no files are written to the disk.

To handle the shell easier, I recommend to use Putty instead of the Hyper-V viewer. Also, Putty supports Copy/Paste! But first you have to set a temporary password to use the shell. Temporary means: after a reboot the credentials gone!

sudp bash
passwd rancher

Enter your temp password now.

Afterwords you can log in via putty. The default username is rancher. If you do not know the IP address of your vm, enter ip a.

Config File

Now, if you're in Putty, you can create the config file. I use vim. The documentated config file name is cloud-config.yml

vi cloud-config.yml

Paste now your config into putty:

  - ssh-rsa AAA...

    engine: docker-17.03.2-ce

Save your file (use ESC to leave input mode, enter :w to save, :wq to save and exit VIM). Validate your config with sudo ros config validate -i ./cloud-config.yml. If no output is present, the config is valid.

Install RancherOS

Now you can install rancher to disk with: sudo ros install -c ./cloud-config.yml -d /dev/sda

RancherOS asks for a reboot, I said no. Reason: you have to shutdown the VM, detach the ISO and start the VM again. If you run a plain reboot, you are in the live system again :-/

To log into your installed RancherOS, you have to prepair a Putty session first:

  • Connection > Data: set username to rancher - this is the default user. You can also leave this blank, then you have to enter the username on log in.
  • Connection > SSH > Auth: select your private SSH key for authentication.

Now you can log into RancherOS via Putty.

You're done! You have set up RancherOS in Hyper-V :-)