Deploying the CloudFormation Template for Pivotal Cloud Foundry on AWS

Page last updated:

This topic describes how to deploy the CloudFormation template for Pivotal Cloud Foundry (PCF) on Amazon Web Services (AWS).

An AWS CloudFormation template describes a set of AWS resources and properties. Follow the instructions below to use a CloudFormation template to create the infrastructure that you need to deploy PCF to AWS.

The template is designed to output the resources necessary for two availability zones (AZ), with a private and public subnet designated for each AZ. The Elastic Load Balancer will be attached to the public subnet of both AZs to balance traffic across both environments. Three AZs is actually recommended as the desired number of AZs for a highly available deployment of PCF, however many AWS regions only have two AZs available.

Note: The CloudFormation template for Elastic Runtime includes a reference to another CloudFormation template for Ops Manager. For more information about how IaaS user roles are configured for each template, refer to the Pivotal Cloud Foundry IaaS User Role Guidelines topic.

Note: Before following the procedure below, confirm that you have selected the correct region within your AWS account. All of the AWS resources for your deployment must exist within a single region. See the Amazon documentation on regions and availability zones for help selecting the correct region for your deployment.

Step 1: Download the PCF CloudFormation Template

  1. Sign in to Pivotal Network.

  2. Select Elastic Runtime. From the Releases drop-down menu, select the release that you wish to install.

  3. Download the PCF CloudFormation for AWS Setup.

  4. Save the file as pcf.json.

Step 2: Upload an SSL Certificate to AWS

You can add an SSL Certificate using two methods:

(Option) Create SSL Certificate using the AWS CLI

The AWS CLI must be installed on your machine and configured to a user account with admin access privileges on your AWS account.

  1. Obtain or create an SSL server certificate. For more information, see the AWS documentation on SSL certificates. When you create a certificate signing request (CSR) in the “Create a Server Certificate” instructions, you must use your wildcard domain as the Common Name input.

  2. Add the following additional domains and wildcards using the OpenSSL SAN (subjectAltName) extension:

    • *.system.example.com
    • *.login.system.example.com
    • *.uaa.system.example.com
    • *.apps.example.com

      Note: If you use a self-signed certificate or select the “Generate Self-Signed RSA Certificate” option during the Deploying Elastic Runtime on AWS installation process, you can ignore the step above. However, make sure you upload the self-signed certificate to AWS and attach the certificate to the listeners on the AWS Elastic Load Balancer. Pivotal recommends only using a self-signed certificate for testing and development.

  3. Upload your SSL certificate to AWS. For more information, see the AWS documentation s on uploading SSL certificate using the CLI.

    $ aws iam upload-server-certificate \
    --server-certificate-name YOUR-CERTIFICATE \
    --certificate-body file://YOUR-PUBLIC-KEY-CERT-FILE.pem \
    --private-key file://YOUR-PRIVATE-KEY-FILE.pem \
    
    For example:
    $ aws iam upload-server-certificate \
    --server-certificate-name myServerCertificate \
    --certificate-body file://my-certificate.pem \
    --private-key file://my-private-key.pem
    

    Note: If you receive an upload error (MalformedCertificate), run the following command to convert your server certificate to the PEM format as required by the AWS Identity and Management (IAM) service: $ openssl x509 -inform PEM -in my-certificate.pem
    Then try your upload again.

  4. After successfully uploading the certificate to your AWS account, you will see output metadata for your certificate. For example:

    {
     "ServerCertificateMetadata": {
     "ServerCertificateId": "ASCAI3HRFYUTD55KNAF64",
     "ServerCertificateName": "myServerCertificate",
     "Expiration": "2016-10-18T18:41:59Z",
     "Path": "/",
     "Arn": "arn:aws:iam::9240874958318:server-certificate/myServerCertificate",
     "UploadDate": "2015-10-19T19:10:57.404Z"
     }
    }
    

  5. Record the value of the SSL Certificate ARN (Amazon Resource Name) to use when configuring your AWS resource stack. Alternatively, if you know the name of the certificate, you can run the following command to retrieve certificate metadata later:

    $ aws iam get-server-certificate --server-certificate-name YOUR-CERT-NAME
    For example:
    $ aws iam get-server-certificate --server-certificate-name myServerCertificate

(Option) Create SSL Certificate using the AWS Certificate Manager

  1. Log into your AWS management console and navigate to Certificate Manager. If your Certificate Manager has no certificates, click Get Started.

  2. Under Add domain names, enter the following wildcard subdomains to the certificate, based on your domain (example: example.com). Click Add another name to this certificate until you have entered them all:

    • *.example.com
    • *.system.example.com
    • *.login.system.example.com
    • *.uaa.system.example.com
    • *.apps.example.com
  3. Click Review and Request to review, and Confirm and Request to confirm.

  4. Check the email account registered for the domain owner. Open the certificate approval email message sent from Amazon Certificates, and click the email link to the approval page for the SSL certificate.

  5. From the approval page, click I Approve.

  6. Record the SSL Certificate Amazon Resource Name (ARN) shown on the confirmation page to use when configuring your AWS resource stack. Alternatively, you can retrieve certificate metadata later by selecting the certificate listing in Certificate Manager and recording values in the Details pane that appears underneath.

Step 3: Create a Resource Stack Using the CloudFormation Template

  1. Log in to the AWS Console.

  2. In the second column, under Management Tools, click CloudFormation.

    Cloudformation

  3. Click Create New Stack.

    Newstack

  4. Select Upload a template to Amazon S3.

    Uploadtemplate

  5. Click Browse. Browse to and select the pcf.json, the Pivotal Cloud Foundry CloudFormation script for AWS file that you downloaded. Click Next.

  6. On the next screen, name the stack pcf-stack.

  7. In the Specify Parameters page, complete the following fields:

    New stack params

    • 01NATKeyPair: Use the drop-down menu to select the name of your pre-existing AWS key pair. If you do not have a pre-existing key pair, create one in AWS and return to this step.
    • 02NATInstanceType: Do not change this value.
    • 03OpsManagerIngress: Do not change this value.

      Note: The first parameter name begins with 03.

    • 04RdsDBName: Do not change this value.
    • 05RdsUserName: Enter a username for the RDS database.

      Note: Do not enter the username rdsadmin. AWS reserves the rdsadmin user account for internal database instance management.

    • 06RdsPassword: Enter a password for the RDS database.
    • 07SSLCertificateARN: Enter your uploaded SSL Certificate ARN.
    • 08OpsManagerTemplate: The default template link provided here works. Otherwise you can enter your own S3 bucket location of the Ops Manager CloudFormation script.
    • 09ElbPrefix: Prefix for the generated names of the ELBs. Any string you specify in this field will be prefixed to -pcf-elb to form the name of your ELBs. Leave empty to use the default prefix of AWS::StackName.
    • 10AllowHttpOnElb: Set this to true to listen for HTTP traffic on port 80. This is the default. Set it to false to only listen for traffic on ports 443 and 4443.
  8. Click Next.

  9. On the Options page, leave the fields blank and click Next.

    Options

  10. On the Review page, select the I acknowledge that this template might cause AWS CloudFormation to create IAM resources checkbox and click Create.

    Acknowledge

    AWS runs the CloudFormation script and creates the infrastructure that you need to deploy PCF to AWS. This may take a few moments. You can click on the Events tab to view the progress of the setup.

When the installation process successfully completes, AWS displays CREATE_COMPLETE as the status of the stack.

Aws cloudform stacks

After completing this procedure, complete all of the steps in the following topics:


Return to Installing Pivotal Cloud Foundry Using AWS CloudFormation.

Create a pull request or raise an issue on the source for this page in GitHub