Deploying Cloud Foundry on AWS with BOSH AWS Bootstrap

WARNING: The command bosh aws destroy destroys everything in your AWS account, including all S3 buckets and all instances. Do not use this command unless you want to lose everything in your AWS account, including objects and files unrelated to your Cloud Foundry deployment.

Cloud Foundry tools simplify the process of deploying a Cloud Foundry instance to a variety of platforms, including Amazon Web Services (AWS). The following document guides you through using BOSH and the cf Command Line Interface (CLI) to deploy Cloud Foundry to Amazon Web Services.

Prepare a Domain

  1. Select a DNS domain name for your Cloud Foundry instance. For example, if you select the domain name cloud.example.com, Cloud Foundry deploys each of your applications as APP-NAME.cloud.example.com.

  2. Create an AWS Route 53 Hosted Zone for your domain on the AWS Route 53 control panel.

  3. Select the checkbox for a hosted zone to view the Hosted Zone Details panel. The panel displays the Name Servers section, which contains a list of addresses to which you must delegate DNS authority for your domain. For example, if you selected the domain name cloud.example.com, each address in Name Servers should become an NS record in the DNS server for example.com.

Prepare the Deployment Environment

Ruby 1.9.3 and git (1.8 or later) are prerequisites for the following steps.

  1. After you install Ruby and git, install the bundler RubyGem:

    $ gem install bundler
    
  2. Create a deployments directory with a sub-directory for your deployment.

    $ mkdir deployments
    $ cd deployments
    $ mkdir cf-example
    
  3. In the cf-example sub-directory, create a file named Gemfile with the following contents:

    source 'https://rubygems.org'
    ruby "1.9.3"
    gem "bosh_cli_plugin_aws"
    
  4. Run bundle install to install the gems you specified in the Gemfile.

    $ bundle install
    
  5. Create a file named bosh_environment and add the following contents, replacing the values in each line to match your configuration. cat Note the following:

    • The values that you add for BOSH_VPC_DOMAIN and BOSH_VPC_SUBDOMAIN must correspond to the DNS domain name that you set up when configuring Route 53. The example below uses my-subdomain.example.com.
    • The values that you add for BOSH_AWS_ACCESS_KEY_ID and BOSH_SECRET_ACCESS_KEY are the AWS credentials you established when you deployed MicroBOSH to AWS.
    • For the BOSH_VPC_PRIMARY_AZ and BOSH_VPC_SECONDARY_AZ properties, choose an availability zone that is listed as “operating normally” in the Health Status section of the AWS Console for your region.
    export BOSH_VPC_DOMAIN=example.com
    export BOSH_VPC_SUBDOMAIN=my-subdomain
    export BOSH_AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID
    export BOSH_AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
    export BOSH_AWS_REGION=us-east-1
    export BOSH_VPC_PRIMARY_AZ=us-east-1a
    export BOSH_VPC_SECONDARY_AZ=us-east-1b
    

    Note: The following steps only support deployment to the us-east-1 region of AWS.

    To deploy MicroBOSH to a different region, see this guide.

  6. Run source bosh_environment to set the environment variables required for deploying to AWS.

    $ source bosh_environment
    
  7. Run bosh aws create to create a VPC Internet Gateway, VPC subnets, three RDS databases, and a NAT VM for Cloud Foundry subnet routing. This command generates two receipt files, aws_rds_receipt.yml and aws_vpc_receipt.yml, that you use when deploying Cloud Foundry.

    $ bosh aws create
    Executing migration CreateKeyPairs
    allocating 1 KeyPair(s)
    Executing migration CreateVpc
    . . .
    details in S3 receipt: aws_rds_receipt and file: aws_rds_receipt.yml
    Executing migration CreateS3
    creating bucket xxxx-bosh-blobstore
    creating bucket xxxx-bosh-artifacts
    

    Note: RDS database creation may take 20 or more minutes.

Deploy MicroBOSH

Refer to the instructions in the BOSH Deploying MicroBOSH to AWS topic to deploy MicroBOSH to AWS.

Create a Deployment Manifest Stub

Create a manifest stub file named cf-stub.yml. Customize the manifest stub for your environment.

Deploy Cloud Foundry

  1. Clone the cf-release GitHub repository.

    $ git clone https://github.com/cloudfoundry/cf-release.git
    
  2. Use the update helper script to update the cf-release submodules:

    $ cd cf-release
    $ ./update
    
  3. Install Spiff.

  4. Run the following Spiff command from the cf-release directory to create a deployment manifest named cf-deployment.yml:

    ./generate_deployment_manifest INFRASTRUCTURE MANIFEST-STUB > cf-deployment.yml

    Replace INFRASTRUCTURE with aws and replace MANIFEST-STUB with the name and location of your cf-stub.yml file. For example:

    $ ./generate_deployment_manifest aws cf-stub.yml > cf-deployment.yml
    
  5. Use bosh target to target the BOSH Director:

    $ bosh target
    Current target is https://x.x.x.x:25555 (micro-xxxxxx)
    
  6. Set your deployment to the generated manifest:

    $ bosh deployment cf-deployment.yml
    
  7. Use bosh create release to create a Cloud Foundry release. This command prompts you for a development release name.

    $ bosh create release
    
  8. Use bosh upload release to upload the generated release to the BOSH Director:

    $ bosh upload release
    
  9. Deploy the uploaded Cloud Foundry release:

    $ bosh deploy
    

    Note: bosh deploy can take 2-3 hours to complete.

  10. Use curl to test the API endpoint of your Cloud Foundry installation.

    $ curl api.subdomain.domain/info
    

    If curl succeeds, it should return the JSON-formatted information. If curl does not succeeds, check your networking and make sure your domain has an NS record for your subdomain.

  11. You should be able to target your Cloud Foundry installation with the cf Command Line Interface (CLI) and log in as an administrator.

    The user name, admin and the password, fakepassword, are specified in the deployment manifest under uaa:scim:users.

    For more information about managing organizations, spaces, users, and applications, refer to the cf topic.

Update Cloud Foundry

  • If you make change to your manifest, run bosh deploy to update your Cloud Foundry deployment with these changes.

  • If you make changes to the cf-release directory, run bosh create release && bosh upload release && bosh deploy to update your Cloud Foundry deployment with these changes.

Deploy Cloud Foundry Services

If you want your Cloud Foundry to be able to provision services, you must deploy a services release. Refer to the services documentation.

You also might be interested in the community-managed services release.

Destroying the AWS Environment

  1. Use bosh aws destroy to destroy your AWS environment.

    WARNING: The command bosh aws destroy destroys everything in your AWS account, including all S3 buckets and all instances. Do not use this command unless you want to lose everything in your AWS account, including objects and files unrelated to your Cloud Foundry deployment.
    $ bosh aws destroy
    
  2. Remove any YAML artifacts:

    $ rm -f *.yml