BOSH: VM lifecycle management for distributed systems across ten IaaS platforms

Release engineering and lifecycle management for large-scale distributed systems

BOSH covers four areas according to its repository description: release engineering, deployment, lifecycle management, and monitoring of distributed systems. The intended users are infrastructure teams operating many-node services across one or more cloud environments, where keeping every VM in a declared state and rolling out updates in a controlled order are recurring needs.

Two clarifications about what this repository contains are worth making before going further. First, this repository is a Bosh Release: it provides binaries and configuration templates for deploying a new Bosh Director instance. It is not the entire BOSH system: the CLI is a separate project at github.com/cloudfoundry/bosh-cli, and the two have independent release cycles. The homepage and primary documentation are at bosh.io, the main usage guide is at bosh.io/docs, and the quick start installation steps are at bosh.io/docs/quick-start/.

The Director bootstrap: Bosh is deployed by Bosh using bosh create-env

BOSH has a self-referential deployment model. The component that manages all subsequent deployments is the Director, a long-running server that receives manifests and coordinates VM operations. To get a Director running from scratch, the Bosh CLI acts as a lightweight Bosh server using the bosh create-env command. The full invocation, including the manifest file and IaaS-specific arguments, is documented at bosh.io/docs/quick-start/.

The bosh-deployment repository at github.com/cloudfoundry/bosh-deployment holds the canonical tested set of dependency files and ops files used to deploy a Director. Once a Director is running, it takes over for all further deployments. The relationship is that bosh create-env bootstraps the Director, and the Director handles everything else.

For development environments, the VirtualBox CPI lets you run BOSH deployments locally without a cloud account, which is why the quick start documentation commonly uses it as the entry point. VirtualBox deployments do not require IaaS credentials, so the bootstrap process can be learned without connecting to a real cloud.

The BOSH release format: jobs, packages and compiled artifacts in .final_builds

A BOSH release is the unit of deployable software in the BOSH model. The repository layout here follows the standard structure visible in the top-level entries: jobs/ for job definitions, packages/ for package definitions, src/ for source code, spec/ for specifications, and .final_builds/ for compiled artifacts. The config/ directory holds release configuration, and releases/ holds the release manifests.

A job in BOSH terms is a template together with its control scripts, while a package is compiled code and its dependencies, built once and reused across deployments. When BOSH deploys a release, it places the compiled packages on VMs and runs the job scripts against them. The combination of a pinned stemcell version, a release version, and a deployment manifest produces a deterministic deployment: the same inputs produce the same set of running VMs every time.

This repository is therefore both a product of the BOSH toolchain and a reference implementation of it. Examining its jobs/ and packages/ directories is one way to understand what a well-structured BOSH release looks like from the inside, since the repository uses its own conventions throughout.

Ten Cloud Provider Interfaces cover AWS, vSphere, Google Cloud and seven more platforms

BOSH abstracts IaaS platforms through Cloud Provider Interfaces. Ten CPIs are listed in the README: AWS, Azure, Google, OpenStack, RackHD, SoftLayer, vSphere, vCloud, VirtualBox and Warden, each maintained in its own repository under the cloudfoundry or cloudfoundry-incubator organization. The CPI layer handles creating and deleting VMs, attaching and detaching disks, and any operation that requires talking to the underlying infrastructure. The Director calls the CPI; it does not talk to the IaaS directly.

Two CPI library packages support custom CPI development: bosh-cpi-ruby at github.com/cloudfoundry/bosh-cpi-ruby and bosh-cpi-go at github.com/cppforlife/bosh-cpi-go. Writing a new CPI means implementing an interface that the Director calls rather than modifying the Director itself, which keeps the core system stable as new platforms appear.

The practical consequence of the CPI model is that platform coverage depends on the health of each CPI repository, not on BOSH releases alone. A CPI that lags behind changes to an IaaS API can break deployments on that platform without any change to the Director.

Stemcells and the Agent: the VM image and on-VM process that BOSH controls

A stemcell is a versioned, IaaS-agnostic VM image that provides the operating system layer beneath BOSH jobs. Three stemcell builder repositories are listed: bosh-linux-stemcell-builder for Linux, bosh-windows-stemcell-builder for Windows, and aws-light-stemcell-builder for AWS. The Linux and Windows builders produce stemcells for the full range of CPIs. The AWS light stemcell builder produces stemcells that reference existing AMIs rather than bundling them, which reduces storage costs.

The Agent runs on every VM that BOSH deploys. It lives in bosh-agent at github.com/cloudfoundry/bosh-agent, receives instructions from the Director, applies configurations, runs job templates, and reports health status back. The Agent is embedded in every stemcell rather than installed separately, so the stemcell version and the agent version are the same artifact. When you upgrade a stemcell, you also upgrade the agent.

For the blobstore, which holds compiled packages and release artifacts, four options are listed: bosh-davcli (the default), bosh-s3cli for S3-compatible stores, bosh-gcscli for Google Cloud Storage, and bosh-azure-storage-cli for Azure Blob Storage.

When BOSH is the wrong choice and what container orchestration handles differently

BOSH was built for VMs. It creates them, keeps them in a declared state, patches them in place, and replaces them when they fail. It does not manage containers natively. For workloads that run as containers and benefit from bin-packing, horizontal scaling without VM churn, or a service mesh, a container orchestrator addresses a different level of the stack and requires different tooling.

There is also no built-in observability layer. Metrics, logs and alerts from BOSH-managed VMs flow to whatever external system you connect, and the README does not document a bundled monitoring integration beyond stating that monitoring is one of BOSH's four responsibilities.

BOSH is also heavyweight for small deployments. The Director itself is a VM that needs to run somewhere, and that VM is part of the infrastructure you operate. For a team managing a small number of services on a single cloud account, the operational overhead of running and patching a Director may not justify the consistency guarantees that BOSH provides.

For teams who need configuration management of existing VMs rather than full lifecycle ownership, tools like Ansible or Puppet take a different approach: they connect to machines that already exist and push configuration changes, without owning the provisioning step. BOSH owns provisioning entirely. That ownership is the feature when consistency matters and a limitation when you need to manage machines that BOSH did not create.

Version v283.1.11, Apache-2.0 and a codebase split across many repositories

The three most recent releases are v283.1.11 on 2026-09-19, v283.1.10 on 2026-09-15, and v283.1.9 also on 2026-09-15. The last push to the main branch was on 2026-10-06. Version numbering at 283.x indicates a project with a long release history.

The license is Apache-2.0, stated in the LICENSE file at the repository root. A NOTICE file also sits at the root, which Apache-licensed projects commonly use to satisfy attribution requirements from incorporated libraries.

The BOSH codebase is distributed across many repositories. Core Go utilities are in bosh-utils. The agent on every deployed VM is in bosh-agent. The CLI is in bosh-cli. Documentation source lives in docs-bosh. Following a change or a regression across the full system requires tracking multiple repositories and release cycles independently, which adds overhead to debugging cross-component issues.

Community support routes are the cf-bosh mailing list at lists.cloudfoundry.org/pipermail/cf-bosh for usage and development questions, cf-dev for Cloud Foundry platform questions, and the #bosh channel on slack.cloudfoundry.org.

Editorial conclusion

BOSH fits infrastructure teams who need deterministic VM deployments across multiple IaaS platforms, where stemcell versioning and job idempotency matter more than container density. Skip it for container-native workloads, small deployments where running a Director VM adds disproportionate overhead, or teams who need configuration management of existing machines rather than full lifecycle ownership. Before adopting, verify that the CPI for your target IaaS is actively maintained, check bosh.io/docs for the full Director setup steps, and confirm the stemcell build pipeline covers your target operating system.

Frequently asked questions

Official sources

1. cloudfoundry/bosh on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases