BOSH Bootloader (BBL)

BOSH Bootloader, also known as bbl (pronounced "bubble"), is a command-line utility used to stand up CloudFoundry or Concourse installations on various Infrastructure-as-a-Service (IaaS) platforms.

Supported IaaS providers include:

• AWS
• GCP
• Microsoft Azure
• Openstack
• vSphere

Plan patches allow you to customize the IaaS environment and the BOSH director created by bbl up.

A patch is a directory containing files organized in the same hierarchy as the bbl-state directory. When you run bbl up, the bootloader attempts to merge your terraform overrides and apply provided jumpbox, director, and cloud-config ops files, provided they are placed in the correct directories.

Important Notes:

• bbl down will not delete files that were not originally created by BBL.
• Warning: Plan patches are not tested as thoroughly as the rest of the bosh-bootloader.
• Many patches require specific preparation steps or are designed for specific downstream BOSH deployments. Always read the README.md within the specific patch directory before applying it.

A plan patch is a method of applying multiple modifications to a bbl plan using override files. Instead of modifying the core bbl logic, you provide override files in specific locations that bbl reads and merges into its plan during bbl up.

Supported override locations:

• terraform/ directory
• cloud-config/ directory
• {create,delete}-{jumpbox,director}.sh scripts

Plan patches are considered experimental and should be used with caution. They are useful for complex deployments like BOSH-lite on GCP, CF Isolation Segments on public clouds, or managing K8s clusters via cfcr.

The n-cf-gcp plan patch extends the default bbl behavior, which typically supports only one Cloud Foundry (CF) deployment, to support multiple CF environments.

When using this patch:

• It creates separate load balancers and DNS records for each environment.
• Domain names for each environment are derived from the --lb-domain flag (e.g., cf0.banana-env.com, cf1.banana-env.com).
• Important: To deploy CF correctly, you must use the cf-lb-ops.yml file to ensure load balancers are set up properly.

bosh -d cf0 deploy $CF_D/cf-deployment.yml \
  -o $CF_D/operations/rename-network-and-deployment.yml \
  -v deployment_name=cf0 \
  -v network_name=default \
  -o cf-lb-ops.yml \
  -v env=0 \
  -v system_domain=cf0.banana-env.com

Use the bbl up command to pave infrastructure, create a jumpbox, and deploy a BOSH director on AWS. This process typically takes 5-8 minutes.

Upon completion, bbl will have generated:

• A BOSH director
• A jumpbox
• BOSH director credentials
• An SSH keypair for the director and deployed instances
• The deployment manifest
• A basic cloud config

Important: The bbl state directory contains all files used to create the director. You should check this directory into version control to ensure you can later destroy or update the environment.

bbl up \
	--aws-access-key-id <INSERT ACCESS KEY ID> \
	--aws-secret-access-key <INSERT SECRET ACCESS KEY> \
	--aws-region us-west-1 \
	--iaas aws

To back up the BOSH Director in a BBL environment, use the bbr director command. You need the Director's IP, the SSH username (which is jumpbox for BBL), and the path to the Director's private key.

Required Information:

• DIRECTOR-IP: The internal or public IP of the BOSH Director. Use bbl director-address to find it (remove the port number).
• BBR-USERNAME: For BBL, this is always jumpbox.
• BOSH-DIRECTOR-PRIVATE-KEY-PATH: The path to the BOSH Director's private key. Use bbl director-ssh-key to find the context/path.

Note: If using the BOSH_ALL_PROXY method, ensure your environment is correctly configured before running the command.

bbr director \
    --host DIRECTOR-IP \
    --username jumpbox \
    --private-key-path BOSH-DIRECTOR-PRIVATE-KEY-PATH \
backup

Use bbl cleanup-leftovers when bbl destroy is insufficient. This is useful if:

• bbl destroy failed and lost state information.
• You no longer have access to the bbl-state-dir.
• You want to delete resources created outside of bbl.
• Acceptance tests failed and orphaned IaaS resources.

Unlike bbl destroy, this command does not require a bbl-state-dir. It functions similarly to a forced destruction but relies on filtering resources by name or tag.

Warning: You MUST use the --filter flag. If omitted, bbl will attempt to delete ALL resources in your IaaS account.

# Example: Cleaning up AWS resources with a specific filter
export BBL_IAAS=aws
export BBL_AWS_SECRET_ACCESS_KEY=foo
export BBL_AWS_ACCESS_KEY_ID=bar

bbl cleanup-leftovers --filter malawi