deploy-microbosh-to-aws.html.md.erb

---
title: Deploying MicroBOSH to AWS
---

This topic describes how to deploy MicroBOSH to Amazon Web Services (AWS).

<p class="note">Note: Micro CLI plugin is deprecated, but is still supported. To set up a new Director VM or upgrade your MicroBOSH, please follow <a href="/docs/init-aws.html">Initializing on AWS</a> document.</p>

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

The MicroBOSH deployment manifest is a YAML file that defines the components and properties of the deployment. Create a manifest for your deployment as follows:

1. Create a deployment directory to store your manifest.

    <pre class='terminal'>
    $ mkdir ~/micro-deployment
    </pre>

1. Create a deployment manifest YAML file.

    The example below is a MicroBOSH deployment manifest template. Copy and paste the template into a text editor and save the manifest to your deployment directory.

    In the template, you must replace the `ELASTIC-IP-ADDRESS`, `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 has the file name <code>manifest.yml</code>, which we reference in other examples in this topic.</p>

```yaml
---
name: microbosh

network:
  type: manual
  vip: ELASTIC-IP-ADDRESS # Replace with your Elastic IP address
  ip: 10.0.0.6
  dns: [10.0.0.2]
  cloud_properties:
    subnet: SUBNET-ID # Replace with your MicroBOSH Subnet ID

resources:
  persistent_disk: 20000
  cloud_properties:
    instance_type: m3.xlarge
    availability_zone: AVAILABILITY-ZONE # Replace with your Availability Zone

cloud:
  plugin: aws
  properties:
    aws:
      access_key_id: ACCESS-KEY-ID # Replace with your AWSAccessKeyId
      secret_access_key: SECRET-ACCESS-KEY # Replace with your AWSSecretKey
      region: us-east-1
      default_key_name: bosh
      default_security_groups: ["bosh"]
      ec2_private_key: ./bosh.pem # Path relative to this manifest file

apply_spec:
  agent:
    blobstore: {address: 10.0.0.6}
    nats: {address: 10.0.0.6}
  properties:
    registry: {address: 10.0.0.6}
```

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

To configure your AWS account for MicroBOSH:

1. [Obtain AWS credentials](#credentials)
1. [Create a Virtual Private Cloud (VPC)](#create-vpc)
1. [Create an Elastic IP](#create-eip)
1. [Create a Key Pair](#create-key-pair)
1. [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. If you already know your AWS credentials you can skip this step and replace `ACCESS-KEY-ID` and `SECRET-ACCESS-KEY` in your deployment manifest.

1. Log into the AWS console: [https://console.aws.amazon.com/console/home](https://console.aws.amazon.com/console/home).

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

1. Click your account name and select **Security Credentials**.

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

1. If the AWS IAM confirmation box appears, click **Continue to Security Credentials** to display the Security Credentials page.

1. Expand the **Access Keys** section and click **Create New Access Key**.

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

1. Replace `ACCESS-KEY-ID` and `SECRET-ACCESS-KEY` in your deployment manifest with the **Access Key ID** and **Secret Access Key** shown.

    <%= image_tag("images/deploy-microbosh-to-aws/access-keys-modal.png") %>

1. Close the dialog box.

---
### <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") %>

    <p class="note"><strong>Note</strong>: Currently, <strong>light</strong> stemcells are only available from the AWS Region of <strong>US East (N. Virginia)</strong>. If you want to use a light stemcell, you must select this region.</p>

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 subnet
    * **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 the 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-ADDRESS` 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**.

    The value for the `default_key_name` in the manifest is already set to "bosh".

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

    A bosh.pem file downloads automatically.

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

    <pre class="terminal">
    $ mv ~/Downloads/bosh.pem ~/micro-deployment/bosh.pem
    </pre>

    <p class="note"><strong>Note</strong>: The value for the <code>ec2_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**: MicroBOSH 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. Complete the **Edit inbound rules** form and click **Save**.

    <p class="note"><strong>Note</strong>: To enter the ID of the "bosh" security group for the <strong>Custom IP</strong> field, select the ID field and type the first character of the "bosh" <strong>Group ID</strong> value. The AWS Console displays an autocomplete list. Select the correct ID.</p>

    <table border="1" class="nice" >
      <tr>
        <th>Type</th>
        <th>Protocol</th>
        <th>Port Range</th>
        <th>Source</th>
      </tr>
      <tr>
        <td>Custom TCP Rule</td>
        <td>TCP</td>
        <td>6868</td>
        <td>My IP</td>
      </tr>
      <tr>
        <td>Custom TCP Rule</td>
        <td>TCP</td>
        <td>25555</td>
        <td>My IP</td>
      </tr>
      <tr>
        <td>SSH</td>
        <td>TCP</td>
        <td>22</td>
        <td>My IP</td>
      </tr>
      <tr>
        <td>All TCP</td>
        <td>TCP</td>
        <td>0-65535</td>
        <td>Custom IP</td>
      </tr>
      <tr>
        <td>All UDP</td>
        <td>UDP</td>
        <td>0-65535</td>
        <td>Custom IP</td>
      </tr>
    </table>

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

---
## <a id="download-stemcell"></a>Step 3: Download a Stemcell

1. Open [https://bosh.io/stemcells](https://bosh.io/stemcells) in a web browser
to view a list of publicly available BOSH stemcells.
The list displays the most recent build numbers of BOSH stemcells, organized by operating system, target IaaS, and hypervisor.

1. Choose a BOSH stemcell for AWS and click the build number to download.

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

1. In a terminal window, run `bosh micro deployment manifest.yml` from your deployment directory to instruct MicroBOSH to use your manifest file.

    <pre class='terminal'>
    $ cd ~/micro-deployment

    $ bosh micro deployment manifest.yml

    WARNING! Your target has been changed to https://54.175.20.129:25555!
    Deployment set to ~/micro-deployment/manifest.yml
    </pre>

    <p class="note"><strong>Note</strong>:
    BOSH displays a red <code>WARNING!</code> message that is not an error message. The message alerts you to a change in the targeted IP address.</p>

1. Run `bosh micro deploy STEMCELL-NAME` to deploy MicroBOSH.

    The `bosh micro deploy` command creates the `bosh-deployments.yml` in the deployment directory with information about the environment.

  	<p class="note"><strong>Note</strong>: BOSH may display a red <code>No bosh-deployments.yml file found</code> message. If prompted to allow MicroBOSH to the save state in the current directory, type <code>yes</code>.</p>

    <pre class='terminal'>
    $ bosh micro deploy light-bosh-stemcell-3012-aws-xen-ubuntu-trusty-go_agent.tgz

    No 'bosh-deployments.yml' file found in current directory.

    Is ~/micro-deployment a directory where you can save state? (type 'yes' to continue): yes

    Deploying new micro BOSH instance ~/micro-deployment/manifest.yml to 'https://54.175.20.129:25555' (type 'yes' to continue): yes

    Verifying stemcell...
    File exists and readable                                     OK
    Verifying tarball...
    Read tarball                                                 OK
    Manifest exists                                              OK
    Stemcell image file                                          OK
    Stemcell properties                                          OK

    Stemcell info
    -------------
    Name:    bosh-aws-xen-ubuntu-trusty-go_agent
    Version: 2818

      Started deploy micro bosh
      Started deploy micro bosh > Unpacking stemcell. Done (00:00:00)
      Started deploy micro bosh > Uploading stemcell. Done (00:00:05)
      Started deploy micro bosh > Creating VM from ami-3c8ef254 light. Done (00:00:34)
      Started deploy micro bosh > Waiting for the agent. Done (00:02:17)
      Started deploy micro bosh > Updating persistent disk
      Started deploy micro bosh > Create disk. Done (00:00:07)
      Started deploy micro bosh > Mount disk. Done (00:00:12)
         Done deploy micro bosh > Updating persistent disk (00:00:36)
      Started deploy micro bosh > Stopping agent services. Done (00:00:03)
      Started deploy micro bosh > Applying micro BOSH spec. Done (00:00:38)
      Started deploy micro bosh > Starting agent services. Done (00:00:01)
      Started deploy micro bosh > Waiting for the director. Done (00:00:38)
         Done deploy micro bosh (00:04:52)
    Deployed `manifest.yml' to `https://54.175.20.129:25555', took 00:04:52 to complete
</pre>

1. Use `bosh target ELASTIC-IP-ADDRESS` 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 'microbosh'
    Your username: admin
    Enter password: *****
    Logged in as 'admin'

    $ bosh vms

    No deployments
    </pre>

1. Save the `manifest.yml` and the `bosh-deployments.yml` in the deployment directory so you can later update MicroBOSH with a new version of the stemcell.

    <p class="note"><strong>Note</strong>: When you rerun the <code>bosh micro deploy</code> command on an existing deployment directory, it updates the <code>bosh-deployments.yml</code> in the deployment directory with information about the recreated environment and replaces the log files.</p>

---
## <a id="troubleshooting"></a> Basic Troubleshooting

If an error message displays that refers to your access key signature, check the accuracy of the `ACCESS-KEY-ID` and `SECRET-ACCESS-KEY` in the deployment manifest.

If other error messages appear:

* Check your `manifest.yml` for errors.
* Review your AWS configuration.

If you cannot determine the cause of any error, run `bosh micro delete` to remove the deployment, then reattempt the deploy.

---