installation.html.md.erb

---
breadcrumb: PCF Services
title: Installing VMware Tanzu Service Broker for AWS
---

This topic tells you how to install <%= vars.product_full %> by configuring your AWS account and importing the product file into <%= vars.ops_manager %>.


## <a id="prerequisites"></a> Installation prerequisites

* <%= vars.app_runtime_full %> (<%= vars.app_runtime_abbr %>) v2.3 to v2.9
* An Amazon Web Services (AWS) account
* VMware Tanzu SQL with MySQL for VMs, or an existing MySQL or PostgreSQL database

<p> <%= vars.ops_manager %> products and tiles released after July 2018 require Ubuntu Xenial stemcells instead of Ubuntu Trusty stemcells.</p>

## <a id="setup"></a> Step 1: Setting up AWS

In this step, you configure your AWS account to allow the <%= vars.product_short %> to create and manage AWS resources.

Create a new IAM user for the <%= vars.app_runtime_abbr %> cluster in the **AWS Identity & Access Management** console by following the procedure below.

<p class="note">
<span class="note__title">Note</span> If you have more than one <%= vars.app_runtime_abbr %>
  deployment, you must create an IAM user for each deployment.
  Create a new IAM user in your AWS account.
  Do not use the same IAM user that installed <%= vars.app_runtime_abbr %> on
  AWS becuase it has different policy restrictions.
</p>

1. Select **Policies** and click **Create Policy**.

1. Click the **JSON** tab.

1. Copy the following text into the field:

    ```
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": [
                    "s3:CreateBucket",
                    "s3:DeleteBucket",
                    "s3:PutBucketAcl",
                    "s3:PutBucketLogging",
                    "s3:PutBucketPolicy",
                    "s3:PutBucketTagging",
                    "s3:GetObject",
                    "s3:ListBucket",
                    "iam:CreateAccessKey",
                    "iam:CreateUser",
                    "iam:GetUser",
                    "iam:DeleteAccessKey",
                    "iam:DeleteUser",
                    "iam:DeleteUserPolicy",
                    "iam:ListAccessKeys",
                    "iam:ListAttachedUserPolicies",
                    "iam:ListUserPolicies",
                    "iam:ListPolicies",
                    "iam:PutUserPolicy",
                    "iam:GetPolicy",
                    "iam:GetAccountAuthorizationDetails",
                    "rds:AddTagsToResource",
                    "rds:CreateDBCluster",
                    "rds:CreateDBInstance",
                    "rds:DeleteDBCluster",
                    "rds:DeleteDBInstance",
                    "rds:DescribeDBClusters",
                    "rds:DescribeDBInstances",
                    "rds:DescribeDBSnapshots",
                    "rds:DeleteDBSnapshot",
                    "rds:CreateDBParameterGroup",
                    "rds:ModifyDBParameterGroup",
                    "rds:DeleteDBParameterGroup",
                    "dynamodb:ListTables",
                    "dynamodb:DeleteTable",
                    "dynamodb:DescribeTable",
                    "sqs:CreateQueue",
                    "sqs:DeleteQueue"
                ],
                "Effect": "Allow",
                "Resource": "*"
            }
        ]
    }
    ```

1. Click **Review Policy** to check for errors.

1. Enter `PCFInstallationPolicy` for **Policy Name** and `Installation Policy for PCF` for **Description**.

1. Click **Create Policy**. This creates an AWS policy that you must apply to every IAM user you create for the <%= vars.product_short %>.

1. For each IAM user, do the following:
  1. Click the username.
  1. Click **Add permissions**.
  1. Click **Attach existing policies directly** and select **PCFInstallationPolicy**.

1. Record the **AWS Access Key ID** and **Secret Access Key** for each of your PCF IAM accounts for later use.

<p> The <%= vars.product_short %> also allows a custom name for the <code>PCFInstallationPolicy</code>.<br><br>
    • <strong>To use the default name:</strong> Follow the previous steps for configuring the <code>PCFInstallationPolicy</code> policy.<br>
    • <strong>To use a custom name:</strong> In the previous steps, use a custom name instead of <code>PCFInstallationPolicy</code>.
      You need to enter this custom name later during <strong>Broker Config</strong>, <strong>RDS Config</strong>, <strong>S3 Config</strong>, and <strong>SQS Config</strong>.</p>

### <a id='service-key-policies'></a> Service Key policies

The <%= vars.product_short %> allows app developers to create service keys for their service instances.
Creating a service key creates an IAM user with a templated policy,
and provides the app developer with Access Key credentials to the actions listed in the policies below.

The service key Policy names are configurable.
You can choose your own policy name and configure that name in each service by
updating the Service Key Policy Name field. The default names are used below.

To create the policy templates for each service that you enable,
log in to the AWS console and do the following:

1. Select **Policies** and click **Create Policy**.

1. Click the **JSON** tab.

1. Copy the following text into the field or create your own policy template:

    ```
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "allowtagging",
                "Effect": "Allow",
                "Action": [
                    "s3:GetBucketTagging",
                    "s3:PutBucketTagging"
                ],
                "Resource": [
                    "arn:aws:broker:resource::*"
                ]
             }
         ]
    }
    ```

1. Click **Review Policy** to check for errors.

1. Enter `PCFAppDeveloperPolicy-s3` for **Policy Name** and `<%= vars.product_short %> Service Key policy for S3` for  **Description**.

1. Click **Create Policy**. This creates an AWS policy that you must apply to every IAM user you create for the <%= vars.product_short %>.

1. Repeat steps 1 through 6 for `PCFAppDeveloperPolicy-sqs`, `PCFAppDeveloperPolicy-dynamodb`, and `PCFAppDeveloperPolicy-rds`, using or modifying the examples below.

    <strong>Example: `PCFAppDeveloperPolicy-sqs`</strong>

    ```
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "Stmt1471890189000",
                "Effect": "Allow",
                "Action": [
                    "sqs:ListQueues",
                    "sqs:PurgeQueue",
                    "sqs:ReceiveMessage",
                    "sqs:SendMessage"
                ],
                "Resource": [
                    "arn:aws:broker:resource::*"
                ]
            }
        ]
    }
    ```

    <strong>Example: `PCFAppDeveloperPolicy-dynamodb`</strong>

    ```
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "Stmt1471873911000",
                "Effect": "Allow",
                "Action": [
                    "dynamodb:*"
                ],
                "Resource": [
                    "arn:aws:broker:resource::*"
                ]
            }
        ]
    }
    ```

    <strong>Example: `PCFAppDeveloperPolicy-rds`</strong>

    ```
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "Stmt1471636048000",
                "Effect": "Allow",
                "Action": [
                    "rds:ListTagsForResource",
                    "rds:DescribeDbInstances"
                ],
                "Resource": [
                    "arn:aws:broker:resource::*"
                ]
            }
        ]
    }
    ```


## <a id="create-database"></a> Step 2: Create Service Broker Database

To store its configuration information, the <%= vars.product_short %> requires access
to a MySQL or PostgreSQL database that is highly available and regularly backed up.
Loss of this data severely impacts the ability of the service broker to manage
the configured service instances. However, the AWS resources are not be affected.

The database can be VMware Tanzu SQL with MySQL for VMs or an external MySQL or PostgreSQL database, including an AWS RDS database.

If you choose to use a VMware Tanzu SQL with MySQL for VMs database, the service broker automatically provisions the database.

If you choose to use an RDS MySQL or RDS PostgreSQL database, do the following:

1. In the AWS RDS console, create the appropriate database:
    * Choose the smallest database instance class, `db.t2.micro`.
    * Select `yes` for **Multi-AZ Deployment**.
    * Choose `Provisioned IOPS (SSD)` for **Storage Type**. For a non-production database, you can choose `General Purpose (SSD)`.
    * Enter the minimum accepted value '5' to '100' GB of **Allocated Storage**.
    * Leave **Provisioned IOPS** at the default value.
    * Enter `pcf-aws-services` for the **DB Instance Identifier**.
    * Enter suitable values for the **Master username** and **Master password**.

1. Record the **Database IP**, **Database Port**, **Admin User**, **Admin Password**, and **Database Name**. The <%= vars.product_short %> stores configuration information in this database.

1. Ensure that the <%= vars.product_short %> is able to connect to your database.
  If necessary for your deployment, modify your AWS VPC settings to allow access to
  the RDS database from an external IP address. For more information, see
  [Accessing a DB Instance in a VPC](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_VPC.Scenarios.html)
  in the AWS documentation.`


## <a id="ASGs"></a> Step 3: Application Security Groups

To allow this service to have network access, you must create [Application Security Groups](https://docs.vmware.com/en/VMware-Tanzu-Application-Service/3.0/tas-for-vms/app-sec-groups.html) (ASGs).

<p> Without Application Security Groups, the service cannot be used.</p>

### <a id="service-container-network-connections"></a> Service Container network connections

This service is deployed as an application to the `iaas-brokers` space in the `system` org, and requires the following outbound network connections:

|Destination        |Ports       |Protocol   |Reason
|---                |---         |---        |---
|`AWS_IP_RANGE`     |443, 5432, 1521, 1433, 3306         |tcp        |This service accesses RDS/S3

<p class="note">
<span class="note__title">Note</span> The AWS IP range is available from <a href="http://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html#aws-ip-download">Amazon</a>. You might choose to use <a href="https://curl.haxx.se/">curl</a> and <a href="https://stedolan.github.io/jq/">jq</a> to convert the IP range as downloaded from Amazon into ASG rules:</p>

```
    curl -s https://ip-ranges.amazonaws.com/ip-ranges.json | \
    jq '[
      {
        ports: "443, 5432, 1521, 1433, 3306",
        protocol: "tcp",
        destination: .prefixes | map(select(.service == "AMAZON")) | .[] | .ip_prefix
      }
    ] | .' > aws-service-broker.json

```

<p class="note">
<span class="note__title">Note</span> This creates a configuration which allows traffic for all AWS Regions.
  You can further filter the list of entries in the Application Security Group config
  to a specific set of AWS Regions by adding additional
  <code>jq</code> <code>map(select(.region == "REGION_NAME"))</code>
  statements for each region.</p>

Log in as an admin and create an ASG called `aws-service-broker`, binding it to the `iaas-brokers` space in the `system` org:
<pre class="terminal">
$ cf create-security-group aws-service-broker aws-service-broker.json
$ cf bind-security-group aws-service-broker system iaas-brokers
</pre>

### <a id="application-container-network-connections"></a> Application Container Network Connections

Application containers that use instances of this service require the following outbound network connections:

|Destination        |Ports       |Protocol   |Reason
|---                |---         |---        |---
|`AWS_IP_RANGE`     |443, 5432, 1521, 1433, 3306         |tcp        |Application containers can access S3/RDS

Create an ASG called `aws-service-broker-app-containers` with the above configuration and bind it to the appropriate space or, to give all started apps access, the `default-running` ASG set. For example:

```
[
  {
      "ports": "443, 5432, 1521, 1433, 3306",
      "protocol": "all",
      "destination": "192.0.2.0/14"
  },
  {
      "ports": "443, 5432, 1521, 1433, 3306",
      "protocol": "all",
      "destination": "198.51.100.0/22"
  },
  ...rest of AWS IPs elided...
]
```


## <a id="install"></a> Step 4: Install in <%= vars.ops_manager %>

To install the <%= vars.product_short %> tile in <%= vars.ops_manager %>, do the following:

1. Download the <%= vars.product_short %> product file from [<%= vars.product_network %>](https://network.tanzu.vmware.com/products/aws-services).

1. From the <%= vars.ops_manager %> Installation Dashboard, click **Import a Product** to upload the product file.

1. Click **Add** next to the uploaded product description in the **Available Products** view to add this product to your staging area.

1. Click on the newly added tile to configure the sections as described below.

### <a id="aws-config"></a> AWS Config

The setup in Step 1 must be successfully completed before beginning this configuration. You need the AWS and database parameters from that step to successfully configure the broker.

1. Click **AWS Config**.
    <%= image_tag("images/aws-sb-awsconfig.png", :alt => "A screenshot of the AWS
    Config tab. The configurable fields are described in the following steps.") %>

1. Enter the **AWS Access Key ID** and the **Secret Access Key** from [Step 1](#setup).

1. Enter the **Temporary Credentials Timeout** value in minutes. This is the time after which service key credentials expire. To deactivate expiry of the credentials, enter `0`.

1. Modify the **AWS Endpoint** <strong>only</strong> if you are using Amazon's Commercial Cloud Service. Otherwise, leave it set to the default.

1. For **Default Region**, enter the AWS region to use as the default. You can change this later for a particular service.

1. For **Default Availability Zone**, enter the AWS Availability Zone to use as the default. This default Availability Zone is only used where Multi-AZ is not selected.

1. The broker automatically creates AWS tags for the service plan GUID and the org-space GUID. You can also configure default tags to add for each AWS resource by entering them in the **Default Tags** field, separated by a space. For example, `owner=operations env=production app=payroll`.

1. Click **Save**.

### <a id="broker-config"></a> Broker Config

1. Click **Broker Config**.
    <%= image_tag("images/aws-sb-brokerconfig.png", :alt => "A screenshot of the Broker
    Config tab. The configurable fields are described in the following steps.") %>

1. For **App Instances**, enter the number of instances of the service broker you want to run. The default is `2`.

1. Do not change the **Broker IAM Policy Name** unless you configured a custom policy name earlier.

1. For **Backing Database**, select the database type for the Service Broker Configuration.

1. If you select **Pivotal MySQL (v2)**, enter the **Plan Name** to be used (e.g. `db-small`) and a unique database name. The database is created during deployment if it does not already exist.

1. If you chose **External MySQL** or **External Postgres**:
	1. For **Database Host** enter the IP address of the database where the <%= vars.product_short %> stores configuration information. You can use the database you created in the AWS RDS console in [Step 1](#setup), or choose to use an existing database.
	1. For **Database Port**, enter the port number of your database. The default for PostgreSQL is `5432`, and the default for MySQL is `3306`.
	1. For **Database Username** and **Database Password**, enter your database credentials.
	1. For **Database Name**, enter the name of the database.

1. Under **Database SSL Connection**, select **Enabled** if you want to encrypt traffic to your database and add your custom root certificate in the **Root Certificate** field. Otherwise, select **Disabled**.

1. Click **Save**.

<p> In the following sections that configure AWS Services, if you do not want to offer that specific service in your <%= vars.app_runtime_abbr %> Marketplace, clear the <strong>Enable in Marketplace</strong> checkbox.</p>

### <a id="dynamodb-config"></a> DynamoDB Config

1. Click **DynamoDB Config**.
    <%= image_tag("images/aws-sb-dynamodbconfig.png", :alt => "A screenshot of the DynamoDB
    Config tab. The configurable fields are described in the following steps.") %>

1. Under **Override Default AWS Region**, select the default AWS region.

### <a id="rds-config"></a> RDS Config

1. Click **RDS Config**.
    <%= image_tag("images/aws-sb-rdsconfig.png", :alt => "A screenshot of the RDS
    Config tab. The configurable fields are described in the following steps.") %>

1. Under **Override Default AWS Region**, select the default AWS region.

1. Under **Override Default AWS Availability Zone**, select the default Availability Zone for RDS database instances.

1. The **RDS Instance Prefix** is set to `cf` by default. This is the prefix for creating RDS database instances.

1. The **Service Key Policy Name** has a default setting. Do not change this unless you created a custom policy earlier in [Set Up AWS](#setup).

1. The **Networking** section allows you to configure whether to use the Default VPC or a Custom VPC, and whether the instance is publicly accessible. For a Custom VPC, enter the DB Subnet Group Name and the VPC Security Group(s).

1. The **Enable Storage Encryption** setting is deactivated by default. You can enable RDS encryption for a database instance. However, not all regions and database instance classes support encryption. If you enable this setting, you must change the default plans to remove those that do not support encryption. For more information, see [http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.html#d0e21710](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.html#d0e21710).

1. Select the check boxes of the RDS Services you want to show in the Marketplace.

1. Under **Plans**, for each RDS Database, the <%= vars.product_short %> includes several default plans for use.
    * **basic**: For small projects and during development.
    * **standard**: For a small production database (multi-AZ, 2vCPU, 7.5&nbsp;GB).
    * **premium**: For a mid-sized database (multi-AZ, 4 vCPU, 15&nbsp;GB).
    * **enterprise**: For a large database (multi-AZ, 8 vCPU, 32&nbsp;GB).

1. You can view and edit the configuration of existing plans by clicking the arrow next to their names.
    <%= image_tag("images/aws-sb-editplan.png", :alt => "A screenshot of the PostgreSQL Plans section of the RDS
    Config tab. The standard plan is selected.") %>
    <p class="note">
<span class="note__title">Note</span> If you edit an existing service plan, only future instances of that services plan are changed. Ask your admin to modify existing instances.</p>

1. You can also create a new custom plan by clicking **Add** and completing the following fields:
    - **Plan Name**: The name of the plan in the Marketplace.
    - **Plan Description**: The description of the plan in the Marketplace.
    - **Plan Features**: The list of features displayed in Apps Manager.
    - **Engine**: You usually do not have to edit this field. The field defaults to the RDS database you are configuring. However, for Aurora MySQL v5.7 and later, you must change this field to `aurora-mysql`.
    - **Engine Version**: The version that your database uses.
    - **DB Instance Class**: The hardware that runs the database.
    - **Allocated Storage (GB)**: The amount of storage allocated to the database.
    - **Storage Type**: This can be Magnetic, SSD, or Provisioned IOPS (`io1`).
    - **IOPS**: The IOPS rate for the database instance. Only required if your **Storage Type** is `io1`.
    - **Backup Retention Period**: How long to retain backups (typically 7 days).
    - **Preferred Backup Window**: When to back up. Must be at least a 30-minute window (e.g. 13:00-14:00).
    - **Copy Tags to Snapshot**: Whether to tag the database snapshots.
    - **Multi AZ**: Whether to automatically run in multiple Availability Zones.
    - The **Enable Storage Encryption** setting is deactivated by default. If you have not enabled it globally, you can configure it per service plan.
    - For flexibility, the **User Privileges** allows configuration of database user privileges by service plan. Use this to secure the privileges you want for your developers or apps.
    - **Require SSL for communication**: Select this checkbox to reject connections without TLS.
    - **Additional custom query params on binding URI**: A comma separated list of additional key-value pairs that are added to binding credentials. This feature is useful to provide hints to application database connector libraries, such as `enabledTLSProtocols=TLSv1.2`.
    - **DB Parameter Group Name** allows you to associate an existing DB Parameter Group Name with this service plan. Use the AWS Console to create the DB Parameter Group.

    <%= image_tag("images/aws-sb-addplan.png", :alt => "A screenshot of the PostgreSQL Plans section of the RDS
    Config tab with the custom plan selected. The configurable fields are described in the previous step.") %>

1. Click **Save**.

### <a id="s3-config"></a> S3 Config

1. Click **S3 Config**.
    <%= image_tag("images/aws-sb-s3config.png", :alt => "A screenshot of the S3
    Config tab. The configurable fields are described in the following steps.") %>

1. Under **Override Default AWS Region**, select the default AWS region for this service.

1. Select **Enable in Marketplace** to enable the service in the Marketplace.

1. The **Service Key Policy Name** has a default setting. Do not change this unless you created a custom policy earlier in [Set Up AWS](#setup).

1. The **Quota Limit** limits the total number of instances. Setting it to `0` deactivates it.

1. Enter the **Bucket Prefix**, a short name to prefix all bucket names.

1. S3 has one default plan called `standard`, but in <%= vars.product_short %> v1.4 and later, you can add more. A service plan can require an S3 bucket to be encrypted by creating an AWS KMS Key (see AWS SSE-KMS) and entering the KMS key ARN in the service plan configuration.
	    <%= image_tag("images/aws-sb-s3plans.png", :alt => "A screenshot of the S3 Plans section of the S3
      Config tab. The standard plan is selected.") %>

1. Click **Save** to store the changed settings.


### <a id="sqs-config"></a> SQS Config

1. Click **SQS Config**.
    <%= image_tag("images/aws-sb-sqsconfig.png", :alt => "A screenshot of the SQS
    Config tab. The configurable fields are described in the following steps.") %>

1. Under **Override Default AWS Region**, select the default AWS region for this service.

1. Select **Enable in Marketplace** to enable the service in the Marketplace.

1. The **Service Key Policy Name** has a default setting. Do not change this unless you created a custom policy earlier in [Set Up AWS](#setup).

1. The **Quota Limit** limits the total number of instances. Setting it to `0` deactivates it.

1. For **Queue Prefix**, enter the queue name prefix that is used for filtering list results.

1. For **Default Visibility Timeout**, enter the length of time during which the queue is unavailable once a message is delivered from the queue.

1. For **Message Retention Period**, enter the number of seconds Amazon SQS retains a message.

1. For **Max Message Size**, enter the limit of how many bytes a message can contain before Amazon SQS rejects it.

1. For **Delivery Delay**, enter the time in seconds that the delivery of all messages in the queue are delayed.

1. For **Rx Message Wait Time**, enter the duration, in seconds, that the receiver action waits until a message is in the queue.

1. The **Redrive Policy** specifies an existing dead letter queue to receive messages after the source queue fails to process a message a specified number of times. If enabled, this policy includes the following properties:
    - **Dead Letter Queue**: The Amazon Resource Name (ARN) of the dead letter queue.
    - **Max Receives**: The maximum number of times a message is delivered to the source queue before being sent to the dead letter queue.

1. Click **Installation Dashboard** to return to the <%= vars.ops_manager %> Installation Dashboard.

1. If you are using <%= vars.ops_manager %> v2.3 or later, click **Review Pending Changes**.
For more information about this <%= vars.ops_manager %> page,
see [Reviewing pending product changes]https://docs.vmware.com/en/VMware-Tanzu-Operations-Manager/3.0/vmware-tanzu-ops-manager/install-review-pending-changes.html).

1. Click **Apply Changes** to install the product.

For more information about AWS SQS queue properties, see [AWS::SQS::Queue](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sqs-queues.html) in the AWS documentation. For more information about SQS Redrive Policy, see [Using Amazon SQS Dead Letter Queues](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/SQSDeadLetterQueue.html) in the AWS documentation.


## <a id="confirm"></a> Step 5: Confirm installation

<p> The <%= vars.product_short %> installs an app named <code>aws-services-broker</code> in the <code>iaas-brokers</code> space of the <code>system</code> org. Like other Cloud Foundry apps, you can view the
application logs through the cf CLI by connecting to that org and space with the correct permissions.</p>

1. After <%= vars.ops_manager %> finishes the installation, the **<%= vars.product_short %>** appears as a green tile in the **Installation Dashboard**.
    <%= image_tag("images/aws-sb-install.png", :alt => "A screenshot of the Installation Dashboard
    showing the BOSH Director, Tanzu Application Service, and Service Broker for AWS tiles.") %>

1. In Apps Manager, all orgs and spaces show the new services in the Marketplace. You can create instances of these services through Apps Manager or through the cf CLI. For more information, see [Creating and Managing Service Instances](creating.html).
    <%= image_tag("images/aws-sb-marketplace.png", :alt => "A screenshot of the marketplace
    in the Apps Manager UI. It shows tiles for 10 installed services.") %>