Prepare

We are going to use local BOSH environment provided by VirtualBox (known working version 5.1+). We will install BOSH server (Director) using BOSH CLI. Once VM with Director is running we are going to use BOSH CLI to send commands to the Director.

1

Setup BOSH environment

BOSH CLI is a command line interface to the Director. Follow these instructions to install it.

We are going to use bosh create-env command to install BOSH Director. bosh create-env command provides a way to install initial VM with BOSH Director on any IaaS (AWS, GCP, etc). In our case we will use VirtualBox as our infrastructure provider.

First get configuration files that specify BOSH environment in VirtualBox. And run bosh create-env as following:

$ bosh int vbox/creds.yml --path /admin_password

Log in using admin username and generated password:

$ bosh -e vbox login

Now we are ready to deploy!

Deploy

Before we proceed we need to understand what BOSH needs to deploy software.

What to deploy

Software that is deployed with BOSH needs to be packaged in a special format called a release. For each service that will be deployed, a release needs to contain source files, configuration files, installation scripts, etc. For example, a redis release would contain the source code for redis, redis configuration defaults and redis init scripts.

How to deploy

Each BOSH deployment needs to provide a specially structured configuration file - deployment manifest. This file defines what resources are going to be deployed, what services are going to be running on each of resources and properties that will be passed to services configuration files. For example, for a redis deployment manifest, there are entries for how many and what size redis VMs there should be and how redis should be configured.

$ curl 10.244.0.2:8080

Hello, you from <uuid-1>

$ curl 10.244.0.6:8080

Hello, you from <uuid-2>

3

Change properties

Every release can specify a set of properties that need to be set in deployment manifest and provided to service. For example, that can be database credentials, address of another service, etc.

Our release allows to change property port on which server is listening. You can see the list of properties that can be modified in learn-bosh-release/jobs/app/spec. Let's open manifest.yml and under the section properties set the value of port to 8888. Now we can just re-deploy our manifest changes. Note, we don't need to build new release version, configuration files will be regenerated with new properties.

2

Failing VM

What if there is a problem with instance that is running our service? BOSH offers manual and automatic recovery when there are problems with infrastructure resources like VMs or disks. In this exercise we are going to kill one of our instances and use manual recovery option.

$ wget -qO - --method=DELETE http://127.0.0.1:7777/containers/id-1

$ bosh -e vbox instances

One of the components in BOSH is the Health Monitor. It independently watches system health and will bring missing instances back up by instructing infrastructure to recreate missing resources like VMs with the required persistent disk. Keep running bosh -e vbox instances and see that instance is brought up and service is running eventually.

Now let's turn off automatic repair and manually resolve the issue.

$ bosh -e vbox update-resurrection off

Kill one of the containers again as described above. Run cloud check and select option "Recreate VM and wait for processes to start".

$ bosh -e vbox -d learn-bosh cloud-check

Cloud check command allows to manually resolve issues when resources (VMs and persistent disks) are in a bad state. Run bosh -e vbox instances to see all instances running again.

$ bosh -e vbox -d learn-bosh deploy manifest.yml

...Failed: `router/0 (...)' is not running after update.

Oh-oh, looks like deploy failed. Let's get our service logs, untar them and check stderr log.

$ bosh -e vbox -d learn-bosh logs router/0

We should find this error: "At least one server must be provided". Router fails to route because there is no servers specified.

Let's add a property to router job to specify our servers pointing to their static IPs and ports ("http://10.244.0.2:8888", "http://10.244.0.6:8888"), re-deploy and see it succeeds.

Now running curl -L http://10.244.0.10:8080 should give us responses from different servers.

Done!

In this tutorial we used BOSH to deploy services, updated our deployment with source changes, scaled the number of services and changed their properties. We recovered from failing service, failing VM and failing deploy.

We were using VirtualBox environment with Warden CPI (Cloud Provider Interface). Warden is a Linux container management tool and Warden CPI abstracts VMs as Linux containers. The Director can work with any CPI that implements a certain API to manage IaaS resources. There are several supported CPIs for different IaaS providers: AWS, GCP, Openstack, vSphere and vCloud. Read more about CPIs here: http://bosh.io/docs/cpi-api-v1.html.