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. For more information about bosh-bootloader, see the bosh-bootloader repository on GitHub.

Overview

This topic describes how to create:

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. A manifest is a YAML file that defines the components and properties of a BOSH deployment. For more information, see Deployment Manifest v1 in the BOSH documentation.

5. A basic cloud config. A cloud config is a YAML file that defines IaaS-specific configuration for BOSH. For more information, see Usage in the BOSH documentation.

6. An app gateway. The bosh-bootloader creates the app gateway, but you must still configure DNS to point your domains to the app gateway. For more information, see Setting Up DNS for Your Environment.

Step 1: Download Dependencies

To download the required dependencies for bosh-bootloader:

1. Download Terraform v0.9.1 or later from the Download Terraform page on the Terraform website. Unzip the file and move it to somewhere in your PATH by running:

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

2. Download the BOSH CLI v2. For more information, see Installing the CLI in the BOSH documentation. Make the binary executable and move it to somewhere in your PATH by running:

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

3. To download and install bosh-bootloader, run one of the following sets of commands:

   • On Mac OS X, use Homebrew. Run:

     brew install cloudfoundry/tap/bbl
     

   • Download the latest bosh-bootloader from Releases in the bosh-bootloader repository on GitHub. Make the binary executable and move it to somewhere in your PATH by running:

     chmod +x ~/Downloads/bbl-*
     sudo mv ~/Downloads/bbl-* /usr/local/bin/bbl
     

4. Download and install the Azure CLI. For more information, see Install the Azure CLI in the Microsoft Azure documentation.

Step 2: Create a Service Principal

To create the service principal that bosh-bootloader needs to interact with Azure:

1. If you installed the Azure CLI for the first time, run:

   az login
   

   Follow the instructions to log in.

2. To list subscriptions, run:

   az account list
   

3. From the list of your subscriptions, select a preferred subscription by running:

   az account set --subscription SUBSCRIPTION
   

   Where SUBSCRIPTION is the name or ID of your preferred subscription.

4. To create the service principal for bosh-bootloader with the Azure CLI, run:

   az ad sp create-for-rbac
   

5. You receive a JSON format object like the example below:

   {
     "appId": "YOUR-CLIENT-ID",
     "displayName": "YOUR-SERVICE-PRINCIPAL-DISPLAY-NAME",
     "name": "YOUR-SERVICE-PRINCIPAL-NAME",
     "password": "YOUR-CLIENT-SECRET",
     "tenant": "YOUR-TENANT-ID"
   }
   

   Where:

   • YOUR-CLIENT-ID is your client ID.
   • YOUR-SERVICE-PRINCIPAL-DISPLAY-NAME is the display name of your service principal.
   • YOUR-SERVICE-PRINCIPAL-NAME is the name of your service principal.
   • YOUR-CLIENT-SECRET is your client secret.
   • YOUR-TENANT-ID is your tenant ID. This is the credential for BBL to access Azure. Cloud Foundry recommends 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. For more information, see Create an Azure service principal with Azure CLI in the Microsoft Azure documentation.

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

To create the required infrastructure, deploy a BOSH Director, and create an app gateway for Cloud Foundry:

1. Run:

   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<br/>
   bbl up
   

   Where:

   • 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 is to be created, such as eastus. For more information, see Azure Regions in the Microsoft Azure documentatio.
   • 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 app gateway. For instructions on creating them, see Getting Started: Microsoft Azure in the bosh-bootloader documentation.

     Note: For test and development environments, you can generate your own CA certificate and key with a tool such as For more information about certstrap, see the certstrap repository on GitHub.

   • 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.example.com, Cloud Foundry deploys each of your apps as APP-NAME.cloud.example.com.

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

To view the full list of environmental details you can extract from the state file:

1. Navigate to the directory that contains bbl-state.json.

2. Run:

   bbl
   

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:

1. Navigate to the directory that contains bbl-state.json.

2. Run:

   bbl ENVIRONMENT-DETAIL
   

   Where:

   • ENVIRONMENT-DETAIL is the name of one of the environmental details listed when you run the bbl command.
     
     For example, to obtain your BOSH Director address, run: 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:

ns1-**.azure-dns.com.
ns2-**.azure-dns.net.
ns3-**.azure-dns.org.
ns4-**.azure-dns.info.

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 app gateway.

Step 5: Connect to the BOSH Director

To connect to the BOSH Director:

1. Run:

   eval "$(bbl print-env)"
   

Destroy the BOSH Resources

You can run 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.

• To delete only the load balancers, run:

  bbl plan
  bbl up
  

• To delete the infrastructure, BOSH Director, and load balancers, run:

  bbl destroy