This document shows how to initialize new environment on Amazon Web Services (AWS).

Step 1: Create a Deployment Manifest

  1. Create a deployment directory.

    $ mkdir ~/my-bosh
  2. Create a deployment manifest file named bosh.yml in the deployment directory based on the template below.

    In the template, you must replace the ELASTIC-IP, SUBNET-ID, REGION (e.g. us-east-1), AVAILABILITY-ZONE (e.g. us-east-1a), ACCESS-KEY-ID, and SECRET-ACCESS-KEY properties. We describe replacing these properties in Step 2: Prepare an AWS Account.

    Note: The example below uses several predefined passwords. We recommend replacing them with passwords of your choice.

name: bosh

- name: bosh
  sha1: 4da9cedbcc8fbf11378ef439fb89de08300ad091
- name: bosh-aws-cpi
  sha1: 7fc8ac0f06999b73e426d8baa0345eacaad1d4c7

- name: vms
  network: private
    sha1: 16f1aa2a272befe87a9f0805ae9d367c8e2802ea
    instance_type: m3.xlarge
    ephemeral_disk: {size: 25_000, type: gp2}
    availability_zone: AVAILABILITY-ZONE # <--- Replace with Availability Zone

- name: disks
  disk_size: 20_000
  cloud_properties: {type: gp2}

- name: private
  type: manual
  - range:
    dns: []
    cloud_properties: {subnet: SUBNET-ID} # <--- Replace with Subnet ID
- name: public
  type: vip

- name: bosh
  instances: 1

  - {name: nats, release: bosh}
  - {name: postgres, release: bosh}
  - {name: blobstore, release: bosh}
  - {name: director, release: bosh}
  - {name: health_monitor, release: bosh}
  - {name: registry, release: bosh}
  - {name: aws_cpi, release: bosh-aws-cpi}

  resource_pool: vms
  persistent_disk_pool: disks

  - name: private
    static_ips: []
    default: [dns, gateway]
  - name: public
    static_ips: [ELASTIC-IP] # <--- Replace with Elastic IP

      user: nats
      # password: nats-password # <--- Uncomment & change

    postgres: &db
      user: postgres
      # password: postgres-password # <--- Uncomment & change
      database: bosh
      adapter: postgres

      db: *db
        user: admin
        # password: admin # <--- Uncomment & change
        port: 25777
      username: admin
      # password: admin # <--- Uncomment & change
      port: 25777

      port: 25250
      provider: dav
        user: director
        # password: director-password # <--- Uncomment & change
        user: agent
        # password: agent-password # <--- Uncomment & change

      name: my-bosh
      db: *db
      cpi_job: aws_cpi
      max_threads: 10
        provider: local
          # - {name: admin, password: admin} # <--- Uncomment & change
          # - {name: hm, password: hm-password} # <--- Uncomment & change

        user: hm
        # password: hm-password # <--- Uncomment & change
      resurrector_enabled: true

    aws: &aws
      access_key_id: ACCESS-KEY-ID # <--- Replace with AWS Access Key ID
      secret_access_key: SECRET-ACCESS-KEY # <--- Replace with AWS Secret Key
      default_key_name: bosh
      default_security_groups: [bosh]
      region: REGION  # <--- Replace with Region

    # agent: {mbus: "nats://nats:nats-password@"} # <--- Uncomment & change

    ntp: &ntp [,]

  template: {name: aws_cpi, release: bosh-aws-cpi}

    host: ELASTIC-IP # <--- Replace with your Elastic IP address
    port: 22
    user: vcap
    private_key: ./bosh.pem # Path relative to this manifest file

  # mbus: "https://mbus:mbus-password@ELASTIC-IP:6868" # <--- Uncomment & change

    aws: *aws
    # agent: {mbus: "https://mbus:mbus-password@"} # <--- Uncomment & change
    blobstore: {provider: local, path: /var/vcap/micro_bosh/data/cache}
    ntp: *ntp

Step 2: Prepare an AWS Account

If you do not have an AWS account, create one.

To configure your AWS account for MicroBOSH:

Obtain AWS Credentials

Your AWS credentials consist of an Access Key ID and a Secret Access Key. Follow Creating IAM Users to create a new IAM user and replace ACCESS-KEY-ID and SECRET-ACCESS-KEY in your deployment manifest.

Create a Virtual Private Cloud (VPC)

  1. In the upper-right corner of the AWS Console, select a Region.

  2. On the AWS Console, select VPC to get to the VPC Dashboard.

  3. Click Start VPC Wizard.

  4. Select VPC with a Single Public Subnet and click Select.

  5. Complete the VPC form with the following information:

    • IP CIDR block:
    • VPC name: bosh
    • Public subnet:
    • Availability Zone: us-east-1a
    • Subnet name: public
    • Enable DNS hostnames: Yes
    • Hardware tenancy: Default

  6. Click Create VPC and click OK once VPC is successfully created.

  7. Click Subnets and locate the “public” subnet in the VPC. Replace SUBNET-ID and AVAILABILITY-ZONE in your deployment manifest with the “public” subnet Subnet ID, Availability Zone and Region (AZ without the trailing character).

Create an Elastic IP

  1. On the VPC Dashboard, click Elastic IPs and click Allocate New Address.

  2. In the Allocate Address dialog box, click Yes, Allocate.

  3. Replace ELASTIC-IP in your deployment manifest with the allocated Elastic IP Address.

Create a Key Pair

  1. In the AWS Console, select EC2 to get to the EC2 Dashboard.

  2. Click Key Pairs and click Create Key Pair.

  3. In the Create Key Pair dialog box, enter “bosh” as the Key Pair name and click Create.

    Note: The value for the default_key_name in the manifest is already set to “bosh”.

  4. Save the bosh.pem file.

  5. Move the bosh.pem file into your deployment directory. For example, on UNIX run this command:

    $ mv ~/Downloads/bosh.pem ~/my-bosh/bosh.pem
    $ ls -la ~/my-bosh
    total 16
    drwxr-xr-x   4 pivotal  staff   136 Jan 20 10:56 .
    drwxr-xr-x+ 79 pivotal  staff  2686 Jan 20 10:46 ..
    -rw-r-----@  1 pivotal  staff  1692 Jan 20 10:55 bosh.pem
    -rw-r--r--   1 pivotal  staff   919 Jan 20 10:53 bosh.yml

    Note: The value for the private_key in the manifest is already set.

Create and Configure Security Group

  1. On the EC2 Dashboard, click Security Groups and then click Create Security Group.

  2. Complete the Create Security Group form with the following information:

  3. Click Create

    Note: The value for the default_security_groups in the manifest is already set to “bosh”. It is the Group Name of your VPC Security Group, not the security group ID.

  4. Select the created security group with group name “bosh”, click the Inbound tab and click Edit.

  5. Fill out the Edit inbound rules form and click Save.

    Note: It highly discouraged to run any production environment with source or to make any BOSH management ports publicly accessible.

    Type Port Range Source Purpose
    Custom TCP Rule22(My IP)SSH access from bosh-init
    Custom TCP Rule6868(My IP)BOSH Agent access from bosh-init
    Custom TCP Rule25555(My IP)BOSH Director access from CLI
    All TCP0 - 65535ID of this security groupManagement and data access
    All UDP0 - 65535ID of this security groupManagement and data access

    Note: To enter your security group as a *Source*, select *Custom IP*, and enter “bosh”. Note: The AWS Console should autocomplete the security group ID (e.g. “sg-12ab34cd”).

Step 3: Deploy

Note: See Migrating to bosh-init from the micro CLI plugin if you have an existing MicroBOSH.

  1. Install bosh-init.

  2. Run bosh-init deploy ./bosh.yml to start the deployment process.

    $ bosh-init deploy ./bosh.yml

    See AWS CPI errors for list of common errors and resolutions.

  3. Install the BOSH Command Line Interface (CLI).

  4. Use bosh target ELASTIC-IP to log into your new BOSH Director. The default username and password are admin and admin.

    $ bosh target
    Target set to 'bosh'
    Your username: admin
    Enter password: *****
    Logged in as 'admin'
    $ bosh vms
    No deployments
  5. Save the deployment state file left in your deployment directory so you can later update/delete your Director. See Deployment state section of ‘Using bosh-init’ for more details.

Back to Table of Contents

Previous: Bootstrapping an environment

Contribute changes to this page