init-aws.html.md.erb

---
title: Initializing BOSH environment on AWS
---

This document shows how to initialize new [environment](terminology.html#environment) on Amazon Web Services (AWS).

## <a id="create-manifest"></a>Step 1: Create a Deployment Manifest

1. Create a deployment directory.

    <pre class='terminal'>
    $ mkdir ~/my-bosh
    </pre>

1. 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`, `AVAILABILITY-ZONE`, `ACCESS-KEY-ID`, and `SECRET-ACCESS-KEY` properties. We describe replacing these properties in [Step 2: Prepare an AWS Account](#prepare-aws).

    <p class="note"><strong>Note</strong>: The example below uses several predefined password. We recommend to replace them with passwords of your choice.</p>

<pre>
---
name: bosh

releases:{{ range .Releases }}
- name: {{ .Name }}
  url: {{ .UserVisibleDownloadURL }}
  sha1: {{ .TarballSHA1 }}{{ end }}

resource_pools:
- name: vms
  network: private
  stemcell:
    url: https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-trusty-go_agent?v=3012
    sha1: 3380b55948abe4c437dee97f67d2d8df4eec3fc1
  cloud_properties:
    instance_type: m3.xlarge
    ephemeral_disk: {size: 25_000, type: gp2}
    availability_zone: AVAILABILITY-ZONE # <--- Replace with Availability Zone

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

networks:
- name: private
  type: manual
  subnets:
  - range: 10.0.0.0/24
    gateway: 10.0.0.1
    dns: [10.0.0.2]
    cloud_properties: {subnet: SUBNET-ID} # <--- Replace with Subnet ID
- name: public
  type: vip

jobs:
- name: bosh
  instances: 1

  templates:
  - {name: nats, release: bosh}
  - {name: redis, 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

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

  properties:
    nats:
      address: 127.0.0.1
      user: nats
      password: nats-password

    redis:
      listen_address: 127.0.0.1
      address: 127.0.0.1
      password: redis-password

    postgres: &db
      listen_address: 127.0.0.1
      host: 127.0.0.1
      user: postgres
      password: postgres-password
      database: bosh
      adapter: postgres

    registry:
      address: 10.0.0.6
      host: 10.0.0.6
      db: *db
      http: {user: admin, password: admin, port: 25777}
      username: admin
      password: admin
      port: 25777

    blobstore:
      address: 10.0.0.6
      port: 25250
      provider: dav
      director: {user: director, password: director-password}
      agent: {user: agent, password: agent-password}

    director:
      address: 127.0.0.1
      name: my-bosh
      db: *db
      cpi_job: aws_cpi
      max_threads: 10
      user_management:
        provider: local
        local:
          users:
          - {name: admin, password: admin}
          - {name: hm, password: hm-password}

    hm:
      director_account: {user: hm, password: hm-password}
      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: us-east-1

    agent: {mbus: "nats://nats:nats-password@10.0.0.6:4222"}

    ntp: &ntp [0.pool.ntp.org, 1.pool.ntp.org]

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

  ssh_tunnel:
    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" # <--- Replace with Elastic IP

  properties:
    aws: *aws
    agent: {mbus: "https://mbus:mbus-password@0.0.0.0:6868"}
    blobstore: {provider: local, path: /var/vcap/micro_bosh/data/cache}
    ntp: *ntp
</pre>

---
## <a id="prepare-aws"></a>Step 2: Prepare an AWS Account

If you do not have an AWS account, [create one](http://goo.gl/MaAybK).

To configure your AWS account for MicroBOSH:

* [Obtain AWS credentials](#credentials)
* [Create a Virtual Private Cloud (VPC)](#create-vpc)
* [Create an Elastic IP](#create-eip)
* [Create a Key Pair](#create-key-pair)
* [Create and Configure Security Group](#create-security)

---
### <a id="credentials"></a> Obtain AWS Credentials

Your AWS credentials consist of an Access Key ID and a Secret Access Key. Follow [Creating IAM Users](aws-iam-users.html#create) to create a new IAM user and replace `ACCESS-KEY-ID` and `SECRET-ACCESS-KEY` in your deployment manifest.

---
### <a id="create-vpc"></a> Create a Virtual Private Cloud (VPC)

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

    <%= image_tag("images/deploy-microbosh-to-aws/account-dashboard-region-menu.png") %>

1. On the AWS Console, select **VPC** to get to the VPC Dashboard.

    <%= image_tag("images/deploy-microbosh-to-aws/account-dashboard-vpc.png") %>

1. Click **Start VPC Wizard**.

    <%= image_tag("images/deploy-microbosh-to-aws/vpc-dashboard-start.png") %>

1. Select **VPC with a Single Public Subnet** and click **Select**.

1. Complete the VPC form with the following information:
    * **IP CIDR block**: 10.0.0.0/16
    * **VPC name**: bosh
    * **Public subnet**: 10.0.0.0/24
    * **Availability Zone**: us-east-1a
    * **Subnet name**: public
    * **Enable DNS hostnames**: Yes
    * **Hardware tenancy**: Default

    <%= image_tag("images/deploy-microbosh-to-aws/create-vpc.png") %>

1. Click **Create VPC** and click **OK** once VPC is successfully created.

1. 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** and **Availability Zone**.

    <%= image_tag("images/deploy-microbosh-to-aws/list-subnets.png") %>

---
### <a id="create-eip"></a> Create an Elastic IP

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

    <%= image_tag("images/deploy-microbosh-to-aws/create-elastic-ip.png") %>

1. In the Allocate Address dialog box, click **Yes, Allocate**.

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

    <%= image_tag("images/deploy-microbosh-to-aws/list-elastic-ips.png") %>

---
### <a id="create-key-pair"></a> Create a Key Pair

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

1. Click **Key Pairs** and click **Create Key Pair**.

    <%= image_tag("images/deploy-microbosh-to-aws/list-key-pairs.png") %>

1. In the Create Key Pair dialog box, enter "bosh" as the Key Pair name and click **Create**.

    <%= image_tag("images/deploy-microbosh-to-aws/create-key-pair.png") %>

    <p class="note"><strong>Note</strong>: The value for the <code>default_key_name</code> in the manifest is already set to "bosh".</p>

1. Save the `bosh.pem` file.

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

    <pre class="terminal">
    $ 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
    </pre>

    <p class="note"><strong>Note</strong>: The value for the <code>private_key</code> in the manifest is already set.</p>

---
### <a id="create-security"></a> Create and Configure Security Group

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

    <%= image_tag("images/deploy-microbosh-to-aws/list-security-groups.png") %>

1. Complete the Create Security Group form with the following information and click **Create**:
    * **Security group name**: bosh
    * **Description**: BOSH deployed VMs
    * **VPC**: Select the "bosh" VPC that you created in [Create a Virtual Private Cloud](#create-vpc).

    <%= image_tag("images/deploy-microbosh-to-aws/create-security-group.png") %>

    <p class="note"><strong>Note</strong>: The value for the <code>default_security_groups</code> in the manifest is already set to "bosh". It is the <strong>Group Name</strong> of your VPC Security Group, not the security group ID.</p>

1. Select the created security group with group name "bosh", click the **Inbound** tab and click **Edit**.

    <%= image_tag("images/deploy-microbosh-to-aws/open-edit-security-group-modal.png") %>

1. Fill out the Edit inbound rules form and click **Save**.

    <p class="note"><strong>Note</strong>: It highly discouraged to run any production environment with <code>0.0.0.0/0</code> source or to make any BOSH management ports publicly accessible.</p>

    <table border="1" class="nice">
    	<tr>
    		<th>Type</th>
    		<th>Port Range</th>
    		<th>Source</th>
    		<th>Purpose</th>
    	</tr>

      <tr><td>Custom TCP Rule</td><td>22</td><td>(My IP)</td><td>SSH access from bosh-init</td></tr>
      <tr><td>Custom TCP Rule</td><td>6868</td><td>(My IP)</td><td>BOSH Agent access from bosh-init</td></tr>
      <tr><td>Custom TCP Rule</td><td>25555</td><td>(My IP)</td><td>BOSH Director access from CLI</td></tr>

      <tr><td>All TCP</td><td>ALL</td><td>ID of this security group</td><td>Management and data access</td></tr>
      <tr><td>All UDP</td><td>ALL</td><td>ID of this security group</td><td>Management and data access</td></tr>
    </table>

    <p class="note"><strong>Note</strong>: To enter ID of the "bosh" security group just start typing "bosh" and the AWS Console will autocomplete the name with its ID.</p>

    <%= image_tag("images/deploy-microbosh-to-aws/edit-security-group-rules.png") %>

---
## <a id="deploy"></a> Step 3: Deploy

<p class="note">Note: See <a href="migrate-to-bosh-init.html">Migrating to bosh-init from the micro CLI plugin</a> if you have an existing MicroBOSH.</p>

1. Install [bosh-init](./install-bosh-init.html).

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

    <pre class='terminal'>
    $ bosh-init deploy ./bosh.yml
    ...
    </pre>

    See [AWS CPI errors](aws-cpi.html#errors) for list of common errors and resolutions.

1. Install the [BOSH Command Line Interface (CLI)](./bosh-cli.html).

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

    <pre class="terminal">
    $ bosh target 54.175.20.129

    Target set to 'bosh'
    Your username: admin
    Enter password: *****
    Logged in as 'admin'

    $ bosh vms

    No deployments
    </pre>

1. Save the deployment state file left in your deployment directory so you can later update/delete your Director. See [Deployment state](using-bosh-init.html#deployment-state) section of 'Using bosh-init' for more details.

---
[Back to Table of Contents](index.html#install)

Previous: [Bootstrapping an environment](init.html)