Installation Steps

In “Installation Steps”, I described the prerequisites for installing Cloud Foundry:

1. Create and configure the IaaS environment (including any networks, security groups, blobstores, and load balancers).¹

2. Set up the required external dependencies; this includes additional enterprise services (such as LDAP, syslog endpoints, monitoring and metrics dashboards).

After the prerequisites are in place, here is the next set of steps to actually install Cloud Foundry and BOSH:

1. Deploy the BOSH Director.

2. Create an IaaS/infrastructure-specific BOSH configuration such as cloud configuration.

3. Create a deployment manifest to deploy Cloud Foundry.

4. Integrate Cloud Foundry with the required enterprise services (via the deployment manifest).

5. Deploy Cloud Foundry.²

The rest of this chapter explores the necessary considerations for each step.

Installing Cloud Foundry

To install Cloud Foundry, you need an infrastructure (in our case, an AWS VPC) and a BOSH Director. bosh-bootloader was created to bootstrap both of these concerns.

A single BOSH environment consists of both the Director and the deployments that it orchestrates. Therefore, to create an empty BOSH environment, we first need a Director. The Director VM includes all necessary BOSH components that will be used to manage different IaaS resources.

Bootstrapping just the Director was solved by the BOSH CLI, through:

$ bosh create-env

create-env provides only the Director, there still remains the requirement to provision and configure the VPC, subnets, security groups, ELB, databases, and blobstores.

You can install both BOSH and the required IaaS environment using bosh-bootloader. Bosh-bootloader is a command-line utility for setting up Cloud Foundry (and Concourse) on an IaaS. Under the hood, bosh-bootloader uses the BOSH CLI to set up the BOSH Director.

Before using bosh-bootloader, be sure to do the following:

• Create and change into a clean directory by running the following commands:

  $ mkdir bosh-bootloader;cd bosh-bootloader

• Download the latest stable release and add it to a directory on your PATH, as in this example (assuming /usr/local/bin is on your PATH):

  $ wget https://github.com/cloudfoundry/bosh-bootloader/releases/
  download/v2.3.0/bbl-v2.3.0_osx
  $ chmod +x bbl-v2.3.0_osx
  $ mv bbl-v2.3.0_osx /usr/local/bin/bbl

• Add the correct inline policy to your AWS user (see the bosh-bootloader repository for details)

• Export any required environment variables (see repo for details), such as the following:

  $ export BBL_AWS_ACCESS_KEY_ID=<YOUR ACCESS KEY>
  $ export BBL_AWS_SECRET_ACCESS_KEY=<YOUR SECRET KEY>
  $ export BBL_AWS_REGION=<YOUR AWS DEPLOYMENT REGION>

Now you are going to focus on bosh-bootloader:

1. To set up the AWS VPC and deploy the BOSH Director, run the following:

   $ bbl up

   You should now have a BOSH Director residing in a new VPC with the appropriate subnets, security groups, and NAT in place.

   Tip

   The BOSH team recommends updating your BOSH environment frequently to be sure you’re using the latest version of BOSH. The sequence of steps that follows assumes that you are using BOSH 2.0.

2. Pull out the Director IP, ca-cert, username, and password from the bbl CLI and then log in to your BOSH Director. BOSH requires a ca-cert because the BOSH v2 CLI connects over HTTPS to the Director.

   A typical approach is to alias the BOSH environment (Director IP address) and log in as follows:

   $ bosh alias-env my-bosh -e <YOUR-BOSH-IP>
     Using environment '<YOUR-BOSH-IP>' as user 'user-********'
   
   $ bosh -e my-bosh --ca-cert <(bbl director-ca-cert) 
     login --user $(bbl director-username)
     --password $(bbl director-password)

   Alternatively, you might find it advantageous to set the Director credentials as environment variables and log in as follows:

   $ export BOSH_CLIENT=$(bbl director-username)
   $ export BOSH_CLIENT_SECRET=$(bbl director-password)
   $ export BOSH_ENVIRONMENT=$(bbl director-address)
   $ export BOSH_CA_CERT=$(bbl director-ca-cert)
   
   # check if the above environment is set up correctly
   $ $ bosh env
   
   # At this point you can login to your BOSH Director
   $ bosh login

   You need only provide the credentials the first time you log in to BOSH.

   Warning

   For any of the aforementioned bbl query commands to work, you need to run them from the same directory as your bbl-state.json file. This file is created in the directory where you first ran bbl up.

3. Create the ELB using the key and certificate you created in “Setting Up Domains and Certificates”:

   $ bbl create-lbs --type cf --cert <YOUR-cert.pem> --key <YOUR-KEY.pem>

   This command updates your bbl-state.json. Save this file in a secure location such as Lastpass after this step.

   Cloud Foundry approaches deploying the platform in an unique way. Open source software often resides in a single repository and can be distributed as either a single binary or a set of binaries.

   The Cloud Foundry cf-deployment does not ship as a single binary or even a set of binaries that you first compile then deploy. Instead, cf-deployment is a set of software packages pulled from other Git repositories. These software packages are automatically compiled from source as part of the BOSH deployment process.

   As part of the deployment process, BOSH sets up separate, temporary VMs to compile packages and automatically store the results for subsequent distribution. These VMs are known as compilation VMs.

   Before beginning a new installation of Cloud Foundry, be sure to use the latest stable BOSH v2 CLI obtained from http://bosh.io.

4. BOSH provides a way to capture all OS dependencies as one image, known as a stemcell (discussed later in “Stemcells”). Upload the appropriate stemcell for your IaaS environment; for example:

   $ bosh -e my-bosh upload-stemcell 
   https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-trusty-go_agent

5. Deploy Cloud Foundry. You can obtain the canonical manifest for deploying Cloud Foundry from the cf-deployment Git repository. In time, this repo will also contain tooling for aiding deployment.

   To deploy Cloud Foundry, run the following:

   $ bosh -e my-env -d cf deploy cf-deployment/cf-deployment.yml 
     --vars-store env-repo/deployment-vars.yml 
     -v system_domain=<YOUR-CFDomain.com>

   The cf-deployment.yml manifest requires two additional parameter types:

   • Environment-specific data; as of this writing, this is just your system domain

   • Sensitive configuration information such as credentials

     You should propagate all other configurations by using option fields. For additional information, see cf-deployment.

     To import these datasets, the BOSH CLI currently uses the --vars-store flag. This flag reads in .yml files and extracts the values present in those files to fill out the template represented by cf-deployment. The BOSH v2 CLI generates this .yml file with all of the necessary variables to populate the cf-deployment manifest. In the command in the previous example, the --vars-store env-repo/deployment-vars.yml -v system_domain=$SYSTEM_DOMAIN generates a deployment-vars.yml file based on custom variables such as your Cloud Foundry system domain. Note that for production deployments, you should use config-server instead of var-store.

     Note

     cf-deployment contains all required BOSH releases for deploying Cloud Foundry; for example:

     releases:
     - name: capi
       url: https://bosh.io/d/github.com/cloudfoundry/
       capi-release?v=1.15.0
       version: 1.15.0
       sha1: 2008137d5bb71e701cedba96cb363e1bfbdebd45

     The BOSH CLI will inspect the release URL and then retrieve and upload releases to the Director’s blobstore. There is no requirement to explicitly upload a release to the Director. Instead of linking to a tarball on bosh.io, as in the example here, you can link to a Git repository that then links to a release blobstore. This detail is explained further in “Packaging a Release”.

6. Use the following command to view your deployed environment:

   $ bosh instances --ps #view everything deployed

   Figure 5-1 shows the output.

   Warning

   One important point: be sure to register your chosen wildcard domain names in a DNS such as Route53, and create the appropriate records to point to your load balancer.

   

   Figure 5-1. Deployed instance groups that comprise Cloud Foundry

7. Target the cf api domain and then log in as follows:

   $ cf api api.<YOUR-CFDomain.com> --skip-ssl-validation

8. Log in via cf login. For the administrator username and password, use the following values from the deployment-vars.yml file:

   user:

   Pull uaa_scim_users_admin_name out of deployment-vars. This currently defaults to admin: password:. Pull uaa_scim_users_admin_password out of deployment-vars.yml. The final deployment should look something like that shown in Figure 5-2.

Figure 5-2. bbl and cf-deployment topology on AWS spanning two AZs (three AZs are preferable, but at the time of writing only two AZs are available in us-west)

Changing Stacks

As we discussed in “Stacks”, a stack is a prebuilt rootfs used along with droplets to provide the container filesystem used for running applications. The following Cloud Foundry command lists all the stacks available in a deployment:

$ cf stacks

To change a stack and restage an application, use this command:

$ cf push APPNAME -s STACKNAME

Growing the Platform

bosh-bootloader provides a reasonable, default configuration for getting started with Cloud Foundry. However, over time, your deployment and platform requirements are likely to grow in scope and external integration points. You will also need to upgrade the platform to take advantage of both security updates and new features.

As a distributed platform with many moving parts, Cloud Foundry supports rolling upgrades, which make it possible for you to make changes to platform configuration and underlying infrastructure. If you need additional or bigger Cells, you can resize them and/or increase their number and then simply redeploy Cloud Foundry using BOSH’s ability to perform rolling upgrades. If you need additional IaaS capacity, you can grow your infrastructure to support your existing Cloud Foundry deployment. You can also deploy additional Cloud Foundry environments, as required.

The key is that you must make some important design decisions at the outset, but you are not locked into a static configuration and are free to grow and develop your Cloud Foundry environment, as needed.

Validating Platform Integrity in Production

This section discusses how to validate the health and integrity of your production environment. After you have successfully deployed Cloud Foundry, you should run the smoke tests and Cloud Foundry acceptance tests (CATS) to ensure that your environment is working properly. You should also maintain a dedicated sandbox to test any changes prior to altering any development or production environment.

Logical Environment Structure

Earlier, in “IaaS and Infrastructure Design”, we described the need to both design and provision the infrastructure and IaaS layer to support a single Cloud Foundry foundation. After deploying Cloud Foundry, the next task is to divide the IaaS resources into logical environments for various teams, products, and users to utilize. These logical environments within Cloud Foundry are known as Orgs and Spaces.

As discussed in “Organizations and Spaces”, Orgs and Spaces provide a way to group users together for management purposes. All members of an Org share the same resource quota plan, services availability, and custom domain. Quota plans are associated with Orgs. A quota will apply to all the activities within a particular organization.⁵

Each Org will have at least one Space but can have multiple Spaces. Every application and service is scoped to a Space. Spaces provide a shared location for application development, deployment, and maintenance, and users will have specific Space-related roles. All members of a Space have access to any application environment variables configured in the Space. Therefore, the Space members must have a strict level of trust among one another.

Orgs and Spaces allow you to create a logical multitenant environment within your Cloud Foundry deployment. They give you a level of abstraction with which you can define who can do what in a particular environment. They also provide a way of allocating resources and governing chargeback.

You can define Orgs and Spaces any way that you like. Typically, Orgs are defined around constructs such as the lines of businesses or particular projects and initiatives. Spaces are generally defined in a couple of different ways:

• Typically, bigger organizations are broken down into “two-pizza teams,” with each team owning its own Space. Usually, an individual team is responsible for developing an isolated component or components such as a specific microservice.

• When deploying through a pipeline, it is often useful to have a development space, test space, staging space, and a production space for the applications moving into production.

There is no right or wrong way to structure your Orgs and Spaces; an important point to keep in mind is that you are free to alter your logical Org and Space boundaries at any point.

To begin, you can use the default Org and simply create a Space, as demonstrated here:

$ cf create-space developer

Creating space developer in org default_org as admin...
OK
Assigning role SpaceManager to user admin in org default_org /
space developer as admin...
OK
Assigning role SpaceDeveloper to user admin in org default_org /
space developer as admin...
OK

You can then target the new developer space:

$ cf target -o "default_org" -s "developer"

Pushing Your First App

You can push many different apps to Cloud Foundry. If you do not have one on hand, you can download spring-music.

$ git clone https://github.com/scottfrederick/spring-music
$ cd spring-music

The Spring Music repository contains a sample app manifest. An app manifest provides an easy way to define and capture any required command-line arguments and application metadata. This is important because you can source-control the arguments you used when deploying your app. You do not need to deploy your app with an app manifest. If you prefer, you can simply provide any required arguments via the command line, as shown here:

---
applications:
- name: spring-music
  memory: 1G
  random-route: true
  path: build/libs/spring-music.jar

Therefore, to deploy the app, all you need to do is compile the code by using ./gradlew assemble and then use cf push:

$ ./gradlew assemble
$ cf push

The cf push command should return a URL that you can then use to access your deployed app.

Summary

This chapter walked you through an end-to-end installation of Cloud Foundry using cf-deployment and bosh-bootloader. If you followed all the steps, you should have accomplished the following:

• Deployed the BOSH Director and created IaaS-specific components using bosh-bootloader

• Deployed a working instance of Cloud Foundry using BOSH and cf-deployment

• Successfully validated platform integrity through CATS smoke tests

• Set up an Org and Space

• Pushed an application

Now that you are up and running with Cloud Foundry, Chapter 6 introduces you to the underlying concepts and operational aspects of Diego.