Indeed, it seems worthwhile to write down the few steps necessary to install BOSH Lite, to deploy Cloud Foundry (cf), and to push a web console for Cloud Foundry to your local space.
As a software developer you might be interested in a complete and working installation. As a computer geek as myself you might be more kin to know the ingredients of this recipe and the way they combine with each other. In this article I have tried to serve both clients.
In this mixture a few generally available components have found their usage, by the time of writing they were:
$ uname -mrs
Linux 4.15.0-58-generic x86_64
$ lsb_release -ds
Ubuntu 18.04.3 LTS
$ vboxmanage --version
6.0.10r132072
$ vboxmanage list extpacks | grep Version -B1
Pack no. 0: Oracle VM VirtualBox Extension Pack
Version: 6.0.10
$ bosh --version
version 6.0.0-5240e8aa-2019-08-05T22:16:39Z
$ credhub --version
CLI Version: 2.5.2
$ cf --version
cf version 6.46.0+29d6257f1.2019-07-09
Not all of these components need to be versioned at these exact levels. However, as your mileage may vary, it is a good idea to get as close as possible to these versions. So let's start.
1. Linux Ubuntu OS
Be sure to be à jour. Update apt package management sysem.
sudo apt update && sudo apt upgradeIt may be necessary to install gcc, make and ruby.
sudo apt install ruby
3. VirtualBox and its Extension Pack
VirtualBox is a general-purpose full virtualizer for x86 hardware, targeted at server, desktop and embedded use.
curl -Lo virtualbox.deb https://download.virtualbox.org/virtualbox/6.0.10/virtualbox-6.0_6.0.10-132072~Ubuntu~bionic_amd64.deb
sudo dpkg -i virtualbox.deb
sudo apt --fix-broken install
rm virtualbox.deb
wget https://download.virtualbox.org/virtualbox/6.0.10/Oracle_VM_VirtualBox_Extension_Pack-6.0.10.vbox-extpack --no-check-certificate
sudo vboxmanage extpack install Oracle_VM_VirtualBox_Extension_Pack-6.0.10.vbox-extpack
rm Oracle_VM_VirtualBox_Extension_Pack-6.0.10.vbox-extpack4. BOSH CLI for Linux
The bosh CLI is the command line interface for interacting with what BOSH does, from deployment operations to software release management. BOSH is purposefully used to deploy Cloud Foundry at large, whereas, BOSH Lite is used for local instances of Cloud Foundry, like the one in this article.
curl -Lo bosh https://github.com/cloudfoundry/bosh-cli/releases/download/v6.0.0/bosh-cli-6.0.0-linux-amd64
chmod +x bosh && sudo chown root:root bosh && sudo mv bosh /usr/local/bin/CredHub provides a CLI and API to manage credentials (usernames, passwords, certificates, keys and other arbitrary values) in a secure fashion. The API exposed by the CredHub server for BOSH are also accessed by the credhub CLI.
curl -L https://github.com/cloudfoundry-incubator/credhub-cli/releases/download/2.5.2/credhub-linux-2.5.2.tgz | tar -zx
sudo chown root:root credhub && sudo mv credhub /usr/local/bin/6. Cloud Foundry CLI for Linux
Cloud Foundry CLI, aka cf, is the official command line client for Cloud Foundry.
curl -L "https://cli.run.pivotal.io/stable?release=linux64-binary&source=github" | tar -zx
sudo chown root:root cf && sudo mv cf /usr/local/bin/Following docs and tutorials of BOSH, we begin by cloning (i.e. downloading) the bosh-deployment repository.
mkdir -p bosh
cd bosh
git clone https://github.com/cloudfoundry/bosh-deployment
cd bosh-deploymentYou might need some more power (cpus, memory or ephemeral_disk) for your Cloud Foundry deployment. Therefor set these cloud_properties to boost performance. Below you can see the difference between the default values found within the virtualbox/cpi.yml file at the line 15 and the minimum requirement performance settings:
- path: /resource_pools/name=vms/cloud_properties?
type: replace
value:- cpus: 4
+ cpus: 7
- ephemeral_disk: 16384
+ ephemeral_disk: 51200
- memory: 6144
+ memory: 12288
Note 1: These performance settings assume a machine with 8 (v)CPUs, 16GB RAM and a 64GB DISK. Furthermore, a single CPU nominal frequency is assumed to be at around 3 GHz, or at a total of circa 24 GHz.
Note 2: The property paravirtprovider is not explicitly assigned, which leads to its default minimal value. That opens the case to further experimenting. As the standard stemcell (see below) hosting the BOSH Director virtual machine is a Linux Ubuntu one, appending the property and value paravirtprovider: kvm might bring some little performance boost. Here it implies that your host exposes the CPU vmx flag the the guest OS. By the way, feel free to fork this article and experiment further.
By now, let's just perform these three steps:
- Create the BOSH Director virtual machine
bosh create-env bosh.yml --state state.json -o virtualbox/cpi.yml -o virtualbox/outbound-network.yml -o bosh-lite.yml -o uaa.yml -o credhub.yml -o jumpbox-user.yml --vars-store creds.yml -v director_name=bosh-lite -v internal_ip=192.168.50.6 -v internal_gw=192.168.50.1 -v internal_cidr=192.168.50.0/24 -v outbound_network_name=NatNetwork
Note: Non-wrapping in the command is intended. This step will take some time.
- Set a route and environment variables
sudo ip route add 10.244.0.0/16 via 192.168.50.6
export BOSH_CA_CERT=`bosh int creds.yml --path /director_ssl/ca`
export BOSH_ENVIRONMENT=vbox
export BOSH_CLIENT=admin
export BOSH_CLIENT_SECRET=`bosh int creds.yml --path /admin_password`
export BOSH_DEPLOYMENT_SHA=`git rev-parse --short HEAD`
export CREDHUB_SERVER=https://192.168.50.6:8844
export CREDHUB_CLIENT=credhub-admin
export CREDHUB_SECRET=`bosh int creds.yml --path=/credhub_admin_client_secret`
export CREDHUB_CA_CERT="$(bosh int creds.yml --path=/credhub_tls/ca)"$'\n'"$(bosh int creds.yml --path=/uaa_ssl/ca)"Note: More details on the create-env.sh script.
- Set alias and then login
$ bosh alias-env vbox -e 192.168.50.6
Using environment '192.168.50.6' as client 'admin'
Name bosh-lite
UUID 4af3ebe6-0390-4d3f-bbb3-531013f01b9d
Version 270.5.0 (00000000)
Director Stemcell ubuntu-xenial/456.3
CPI warden_cpi
Features compiled_package_cache: disabled
config_server: enabled
local_dns: enabled
power_dns: disabled
snapshots: disabled
User admin
SucceededNote: As all necessary environment variables are pre-set on the previous step, bosh login may not be needed.
Now, it is Cloud Foundry deployment time. Let's give it a run in few steps:
- Download and update Cloud Foundry
cd ..
git clone https://github.com/cloudfoundry/cf-deployment
cd cf-deployment
bosh update-cloud-config iaas-support/bosh-lite/cloud-config.yml
bosh update-runtime-config ../bosh-deployment/runtime-configs/dns.yml --name dnsNote: create-env.sh proposes a default warden cloud-config at ../bosh-deployment/warden/cloud-config.yml.
- Upload a stemcell
Before BOSH can deploy your Cloud Foundry Application Runtime, it needs a base VM image to start with. In the BOSH ecosystem, these images are called stemcells.
export STEMCELL_VERSION=$(bosh int cf-deployment.yml --path=/stemcells/alias=default/version)
bosh upload-stemcell https://bosh.io/d/stemcells/bosh-warden-boshlite-ubuntu-xenial-go_agent?v=${STEMCELL_VERSION}- Deploy Cloud Foundry on BOSH
export BOSH_DEPLOYMENT=cf
# export SYSTEM_DOMAIN=bosh-lite.com # No need #
bosh deploy cf-deployment.yml -o operations/bosh-lite.yml -o operations/use-compiled-releases.yml -v system_domain=bosh-lite.com
cd ..Note: deploy may take a while. If compilation time is not a concern, then leave this option out -o operations/use-compiled-releases.yml.
- Login with
cf loginand create your own local space
export CF_ADMIN_PASSWORD=`credhub get -n /bosh-lite/cf/cf_admin_password -q`
cf api https://api.bosh-lite.com --skip-ssl-validation
cf login -u admin -p $CF_ADMIN_PASSWORD -o system
cf create-space local && cf target -s localWell done. Congratulations! You're in. 😄
$ cf target
api endpoint: https://api.bosh-lite.com
api version: 2.138.0
user: admin
org: system
space: local
Stratos is an Open Source Web-based UI (Console) for managing Cloud Foundry. It allows users and administrators to both manage applications running in the Cloud Foundry cluster and perform cluster management tasks.
So let's install it.
- Getting started
git clone https://github.com/cloudfoundry-incubator/stratos
cd stratos- Install
npmpackages
sudo apt install npm
npm install
- Pre-build the UI before pushing
npm run prebuild-ui- Push the app
cf push
cd ~
- Enjoy Stratos!
Fire up your favourite browser and go to https://console.bosh-lite.com.
The username is admin, whereas the password is the output of echo $CF_ADMIN_PASSWORD.
If your machine has direct access from the Internet, then you may also be interested in configuring your HAproxy. That's how it goes.
sudo apt install haproxyExport bosh server certificate
cd bosh/bosh-deployment
bosh int creds.yml --path /director_ssl/private_key > site.pem
bosh int creds.yml --path /director_ssl/certificate >> site.pem
bosh int creds.yml --path /director_ssl/ca >> site.pem
sudo mv site.pem /etc/haproxy/
cd ~Then append the follwing lines to /etc/haproxy/haproxy.cfg
frontend bosh
bind *:443 ssl crt /etc/haproxy/site.pem
default_backend bosh-backend
backend bosh-backend
http-request replace-value Host ([^\s\.]*)\.(.*) \1.bosh-lite.com
server bosh-backend bosh-lite.com:443 check ssl verify none
Now restart the HAproxy service
sudo service haproxy restart
Note: You can check service activitiy state with service haproxy status.
Your CF endpoints are now reachabe from the Internet. For example, if your domain is example.com your Stratos login URL shall be found at https://console.example.com, whereas your CF API shall be called with cf api https://api.example.com --skip-ssl-validation.
And now what? Well there are many ways to enjoy your local Cloud Foundry meal 🍲. One of those is obviously to push your apps. As a developer you have for sure a couple of ideas in mind by now. If instead you just would like to try something out, then have a look at these links:
- Cloud Foundry Sample Applications
- Deploy a Sample Ruby on Rails Application
- Example Service Brokers
- Getting Started Deploying Spring Apps
Besides, there are several areas of research that could be tackled further. For instance:
- Find out how to configure BOSH Lite to accept direct access from the Internet. If so, make sure that the involved DNS server resolves any name under *.<SYSTEM_DOMAIN> (*.bosh-lite.com is taken) and points it at the IP of BOSH Director, which in our case is 192.168.50.6 on the outer side and 10.244.0.34 on the inner one - the router instance.
- Install and configure
bosh-bootloaderin order to gain access to other IaaS resources rather than the local instance. This will allow running BOSH Lite on AWS, GCP or Azure, and in so doing it will make use of remote infrastructure rather than your Mac or PC. That comes at some costs though.
It is a good practice to get acquainted with your newly installed system. For your convenience here follows a table of the most common List commands for the bosh CLI:
Run these commands just for getting to know your system:
bosh vms
bosh instances
bosh deployments
#bosh configs
#bosh disks --orphaned
#bosh environments
#bosh errands
#bosh run-errand smoke-tests
#bosh events
#bosh inspect-release diego/2.24.0 # (inspect-release requires args `NAME/VERSION` #
#bosh inspect-release cf-cli/1.11.0
#bosh locks
#bosh networks --orphaned
#bosh orphaned-vms
#bosh releases
#bosh snapshots
#bosh stemcells
#bosh tasks
#bosh variablesA side note from the provider:
In case VirtualBox VM shuts down or reboots, you will have to re-run
create-envcommand from above with--recreateflag. The containers will be lost after a VM restart, but you can restore your deployment withbosh cckcommand. Alternatively Pause the VM from the VirtualBox UI before shutting down VirtualBox host, or making your computer sleep.
A couple of hints for your VM:
export BOSH=$HOME/bosh/bosh-deployment
export BOSH_VMID=`bosh int $BOSH/state.json --path /current_vm_cid`
vboxmanage controlvm $BOSH_VMID savestate # Stop
vboxmanage startvm $BOSH_VMID --type headless # StartTo better get to know your Cloud Foundry, just have a look at the table below:
| Command | Description |
|---|---|
| apps | List all apps in the target space |
| tasks | List tasks of an app |
| stacks | List all stacks |
| marketplace | List available offerings in the marketplace |
| services | List all service instances in the target space |
| service-keys | List keys for a service instance |
| orgs | List all orgs |
| spaces | List all spaces in an org |
| domains | List domains in the target org |
| router-groups | List router groups |
| routes | List all routes in the current space or the current organization |
| network-policies | List direct network traffic policies |
| buildpacks | List all buildpacks |
| quotas | List available usage quotas |
| space-quotas | List available space resource quotas |
| service-auth-tokens | List service auth tokens |
| service-brokers | List service brokers |
| service-access | List service access settings |
| security-groups | List all security groups |
| staging-security-groups | List security groups in the staging set for applications |
| running-security-groups | List security groups in the set of security groups for running applications |
| isolation-segments | List all isolation segments |
| list-plugin-repos | List all the added plugin repositories |
| repo-plugins | List all available plugins in specified repository or in all added repositories |
| plugins | List commands of installed plugins |
| v3-apps | List all apps in the target space |
| v3-droplets | List droplets of an app |
| v3-packages | List packages of an app |
You can find out more of your cf-depoyment with some of these listing commands:
cf apps
cf stacks
cf orgs
cf spaces
cf domains
cf router-groups
cf routes
cf buildpacks
cf security-groups
cf isolation-segments
cf list-plugin-repos
cf repo-plugins
cf v3-apps
#cf marketplace
#cf services
#cf org-users system
#cf network-policies
#cf space-quotas
#cf service-auth-tokens
#cf service-brokers
#cf service-access
#cf pluginsSource:
- Cloud Foundry BOSH, VirtualBox (2018) https://bosh.io/docs/bosh-lite
- Deploying Cloud Foundry with
cf-deployment(2018) https://docs.cloudfoundry.org/deploying/cf-deployment - CF-WebUI (2015) https://icclab.github.io/cf-webui
References / Acknowledgments:
[1] Iryna Shustava, et al.: Deploying CF (2018)
https://github.com/cloudfoundry/cf-deployment/blob/master/deployment-guide.md
[2] Nic Williams & Jelle vd Kooij: Ultimate Guide to BOSH, bosh-lite on VirtualBox (2018) https://ultimateguidetobosh.com/tutorials/bosh-lite-virtualbox
[3] Lidia Fernández Garcés, et al.: Announcing CF WebUI – an open source web interface to Cloud Foundry (2015) https://blog.zhaw.ch/icclab/announcing-cf-webui-an-open-source-web-interface-to-cloud-foundry
[4] Peter Pilgrim: How to deploy BOSH-Lite and Cloud Foundry locally on Mac Book Pro (2018) http://www.xenonique.co.uk/blog/2018/01/19/how-to-deploy-bosh-lite-and-cloud-foundry-locally-on-mac-book-pro
About the author:
Della Porta is fascinated by computer sciences, distributed systems and cloud technologies.
source .envrc