Deploying BOSH on Azure

Page last updated:

This topic describes how to use the bosh-bootloader command-line tool to set up an environment for Cloud Foundry on Azure and deploy a BOSH Director.


After completing this topic, you will have the following:

  1. A BOSH Director instance

  2. A set of randomly generated BOSH Director credentials

  3. A generated key pair that allows you to SSH into the BOSH Director and any instances that BOSH deploys

  4. A copy of the manifest used to deploy the BOSH Director

    Note: A manifest is a YAML file that defines the components and properties of a BOSH deployment.

  5. A basic cloud config

    Note: A cloud config is a YAML file that defines IaaS-specific configuration for BOSH.

  6. An application gateway

    Note: bosh-bootloader creates the application gateway, but you must still configure DNS to point your domains to the application gateway. See the Setting Up DNS for Your Environment topic for more information.

Step 1: Download Dependencies

Perform the following steps to download the required dependencies for bosh-bootloader:

  1. Download Terraform v0.9.1 or later. Unzip the file and move it to somewhere in your PATH:

    $ tar xvf ~/Downloads/terraform*
    $ sudo mv ~/Downloads/terraform /usr/local/bin/terraform

  2. Download the BOSH CLI v2. Make the binary executable and move it to somewhere in your PATH:

    $ chmod +x ~/Downloads/bosh-cli-*
    $ sudo mv ~/Downloads/bosh-cli-* /usr/local/bin/bosh

  3. Perform one of the following procedures to download and install bosh-bootloader:

    • On Mac OS X, use Homebrew:
      $ brew install cloudfoundry/tap/bbl
    • Download the latest bosh-bootloader from GitHub. Make the binary executable and move it to somewhere in your PATH:
      $ chmod +x ~/Downloads/bbl-*
      $ sudo mv ~/Downloads/bbl-* /usr/local/bin/bbl
  4. Download and install the Azure CLI.

Step 2: Create a Service Principal

Perform the following steps to create the service principal that bosh-bootloader needs to interact with Azure:

  1. If you installed the Azure CLI for the first time, enter az login on the command line and follow the instructions to log in:

    $ az login
    To sign in, use a web browser to open the page and enter the code YOURCODE to authenticate.

  2. Enter az account list to list subscriptions.

    $ az account list

  3. From the list of your subscriptions, run az account set --subscription SUBSCRIPTION-ID-OR-SUBSCRIPTION-NAME to select a preferred subscription.

    $ az account set --subscription SUBSCRIPTION-ID-OR-SUBSCRIPTION-NAME

  4. Enter az ad sp create-for-rbac to create the service principal for bosh-bootloader with the Azure CLI.

    $ az ad sp create-for-rbac

  5. You will receive a JSON format object:

      "appId": "YOUR-CLIENT-ID",
      "password": "YOUR-CLIENT-SECRET",
      "tenant": "YOUR-TENANT-ID"
    This is the credential for BBL to access Azure. We recommend that you copy it to a secure location. This credential is only effective in the subscription that you selected in previous step.

    Note: The service principal created above has default role Contributor. You may need more precise access control. Refer to Create an Azure service principal with Azure CLI 2.0 in the Microsoft Azure documentation for more information.

Step 3: Create Infrastructure, BOSH Director, and Application Gateway

Run the following commands to create the required infrastructure, deploy a BOSH Director, and create an application gateway for Cloud Foundry:

    $ bbl plan \
      --iaas azure \
      --azure-subscription-id YOUR-SUBSCRIPTION-ID \
      --azure-tenant-id YOUR-TENANT-ID \
      --azure-client-id YOUR-CLIENT-ID \
      --azure-client-secret YOUR-CLIENT-SECRET \
      --azure-region YOUR-AZURE-REGION \
      --lb-type cf \
      --lb-cert YOUR-CERTIFICATE.crt \
      --lb-key YOUR-KEY.key \
      --lb-domain YOUR-SYSTEM-DOMAIN
$ bbl up

In the above command, replace the placeholder text as follows:

  • YOUR-SUBSCRIPTION-ID is the subscription ID you selected in the previous section.
  • YOUR-TENANT-ID is the tenant field of your service principal credential.
  • YOUR-CLIENT-ID is the appID field of your service principal credential.
  • YOUR-CLIENT-SECRET is the password field of your service principal credential.
  • YOUR-AZURE-REGION is the region where your resource will be created, such as eastus. See Azure Regions in the Microsoft Azure documentation for more information.
  • YOUR-CERTIFICATE.crt and YOUR-KEY.key are the path to your Certificate Authority (CA) certificate and key. This enables SSL/TLS termination at your application gateway. See Getting Started: Microsoft Azure in the bosh-bootloader documentation for instruction about creating them.

    Note: For test and development environments, you can generate your own CA certificate and key with a tool such as certstrap.

  • YOUR-SYSTEM-DOMAIN is the DNS domain name for your Cloud Foundry instance. Cloud Foundry uses this domain name when deploying apps. For example, if you select the name, Cloud Foundry deploys each of your apps as

The bbl up command takes twenty to thirty minutes to complete.

When you run bbl plan or bbl up, bosh-bootloader creates, modifies, or deletes files in the --state-dir or present working directory.

Note: The bbl state directory contains credentials and other metadata related to your BOSH Director and infrastructure. Copy this directory to a secure location.

View List of Values from the State File

Run bbl to view the full list of environmental details you can extract from the state file. You must always run bbl from the directory that contains bbl-state.json. For more information about bbl commands, see the usage.go file in the bosh-bootloader repository on GitHub.

Extract Information from the bbl State

To extract information from the bbl state, run bbl ENVIRONMENT-DETAIL. Replace ENVIRONMENT-DETAIL with the name of one of the environmental details listed when you run the bbl command.

For example, to obtain your BOSH Director address, run the following command:

$ bbl director-address

Step 4: Update DNS Records

If you specify the --lb-domain flag, bbl creates an Azure DNS Zone in your resource group. You can view the records in the zone.

The nameservers have the following format:


From your domain registrar, delegate DNS authority for your hosted zone to the four Azure name servers. To do this, change the default nameservers provided by your domain registrar to Azure name servers listed in Azure DNS Zone.

After a few minutes, your system domain should resolve to your Azure application gateway.

Step 5: Connect to the BOSH Director

Run the following to connect to the BOSH Director:

$ eval "$(bbl print-env)"

Destroy the BOSH Resources

You can use bbl destroy to delete the BOSH Director infrastructure in your Azure environment. Use this command if bbl up does not complete successfully and you want to reset your environment, or if you want to destroy the resources created by bosh-bootloader for any other reason.

  • Run the following commands to delete only the load balancers:

    $ bbl plan
    $ bbl up

  • Run the following commands to delete the infrastructure, BOSH Director, and load balancers:

    $ bbl destroy

Create a pull request or raise an issue on the source for this page in GitHub