aws_prerequisites.md 7.47 KB
Newer Older
1
# How to configure Amazon Web Services (AWS) for BCD
jeremy's avatar
jeremy committed
2

3 4 5 6
This tutorial describes how to configure Amazon Web Services (AWS) for BCD.  
These configuration steps are required to allow BCD to programmatically manage your AWS instances and to be able to connect to your Bonita stack.


7
## Sign Up for AWS
jeremy's avatar
jeremy committed
8

9
If you do not have an Amazon Web Services account yet, first sign up as described in this AWS user guide: [Sign Up for AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#sign-up-for-aws).
10 11 12 13 14


## AWS Setup for BCD

In order to use Amazon EC2 instances, some configuration steps need to be performed as a prerequisite.  
15
The following steps are the basic requirements to set up AWS credentials for Ansible automation.  
16
Further configuration instructions for **AWS single sign-on** can be found [on this page](aws_sso.md).
jeremy's avatar
jeremy committed
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

1. [Create an IAM Policy](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) to grant full access to Amazon EC2 on a specific region (eg. us-west-2)
    - **Policy name**: EC2FullAccess_us-west-2
    - **Policy document**:
    ```json
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": "ec2:*",
                "Effect": "Allow",
                "Resource": "*",
                "Condition": {
                    "StringEquals": {
                        "ec2:Region": "us-west-2"
                    }
                }
            }
        ]
    }
    ```
38
1. Create an IAM Policy to allow to describe DB instances and list tags (mandatory for dynamic inventory script).
jeremy's avatar
jeremy committed
39 40 41 42 43 44 45 46 47 48
    - **Policy name**: RDSDescribeDBInstances
    - **Policy document**:
    ```json
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "Stmt1498730873000",
                "Effect": "Allow",
                "Action": [
49 50
                    "rds:DescribeDBInstances",
                    "rds:ListTagsForResource"
jeremy's avatar
jeremy committed
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
                ],
                "Resource": [
                    "*"
                ]
            }
        ]
    }
    ```
1. Create an IAM Policy to grant full access to Amazon RDS on a specific region (eg. us-west-2). In order to do it you will need your account id (eg. 012345678901)
    - **Policy name**: RDSFullAccess_us-west-2
    - **Policy document**:
    ```json
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": [
                    "rds:*"
                ],
                "Effect": "Allow",
                "Resource": "arn:aws:rds:us-west-2:012345678901:*"
            }
        ]
    }
    ```    
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
1. Create an IAM Policy to give [PassRole](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) permission in order to be able to associate a specific role with the EC2 instances of a cluster.
    - **Policy name**: IAMPassRole
    - **Policy document**:
    ```json
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": "iam:PassRole",
                "Effect": "Allow",
                "Resource": "*"
            }
        ]
    }
    ```
jeremy's avatar
jeremy committed
91 92 93
1. [Create an IAM Group](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups_create.html)
    - **Group name**: bonita-provisioning
    - Select the IAM Policies created previously
94 95 96

    *For some usage you may be interested to create a role and attach to it the corresponding policies, see [Configure AWS single sign-on](aws_sso.md) or [Assume IAM role within AWS Organizations](aws_organizations.md).*

97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
1. Create an IAM Policy to allow ec2 instances of a cluster to autodiscover themselves on a specific region (eg. us-west-2).
    - **Policy name**: ClusterBCD_us-west-2
    - **Policy document**:
    ```json
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": [
                    "ec2:DescribeInstances"
                ],
                "Effect": "Allow",
                "Resource": "*",
                "Condition": {
                    "StringEquals": {
                        "ec2:Region": "us-west-2"
                    }
                }
            }
        ]
    }
    ```
119 120 121
    ::: warning
    :fa-exclamation-triangle: Pay attention that for security reasons, pushing AWS user credentials to EC2 instances (as done with BCD 1.0.x) is no longer supported.
    :::
122 123 124 125
1. [Create an IAM Role for an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)
    - Select EC2 to "Allows EC2 instances to call AWS services on your behalf."
    - Select the IAM Policy created previously (ClusterBCD_us-west-2)
    - **Role name**: ClusterBCD
jeremy's avatar
jeremy committed
126 127 128 129 130 131 132 133
1. [Create an IAM User](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)
    - **Access type**: Programmatic access
    - Add user to the IAM group created previously
    - Download as .csv (or copy) Access key information (**Access key ID** and **Secret access key**) for later use
1. Now let's assume you are using an EC2 region which supports the [EC2-VPC platform](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-supported-platforms.html).
Therefore a [default VPC and default subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html) should already be available.
1. [Create an EC2 Security Group](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#creating-security-group)
    - **Security group name**: sg_bonita-provisioning
134 135 136 137 138 139 140 141 142 143 144
    - Add an Inbound rule to allow communication between Bonita stack components
      - **Type**: All Traffic, **Source**: <security_group_id_of_sg_bonita-provisioning>
    - Add an Inbound rule to allow Ansible to connect via SSH
      - **Type**: SSH, **Source**: My IP
    - Add an Inbound rule to allow remote connection to Bonita Tomcat via HTTP
      - **Type**: Custom TCP Rule, **Port Range**: 8081, **Source**: My IP
    - Add an Inbound rule to allow remote connection to Bonita databases
      - **Type**: Custom TCP Rule, **Source**: My IP
        - with `bonita_db_vendor: postgres` - **Port Range**: 5432
        - with `bonita_db_vendor: mysql` - **Port Range**: 3306
        - with `bonita_db_vendor: oracle` - **Port Range**: 1521
jeremy's avatar
jeremy committed
145 146 147 148 149
1. [Create an EC2 Key Pair](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)
    - _Note: A key pair is linked to an AWS region_
    - Download the `.pem` private key file
    - Ensure private key file permissions: `$ chmod 400 <keyfile_basename>.pem`

150
BCD is compatible with official Ubuntu cloud images as EC2 AMI (Amazon Machine Images).  
jeremy's avatar
jeremy committed
151 152 153
Use the [Amazon EC2 AMI Locator](https://cloud-images.ubuntu.com/locator/ec2/) tools to identify IDs of such images.


154 155 156 157 158 159 160 161 162 163
## Dynamic EC2 inventory configuration

When deploying to AWS, BCD uses [dynamic Amazon EC2 inventory](http://docs.ansible.com/ansible/latest/intro_dynamic_inventory.html#example-aws-ec2-external-inventory-script) with a `ec2_wrapper.sh` script.

This `ec2_wrapper.sh` script can be further configured with the `ec2.ini.j2` template.

For instance, if you are running the BCD controller **from outside EC2**, the `vpc_destination_variable` parameter should be set to `ip_address`. If you are running the BCD controller **from within EC2**, the `vpc_destination_variable` parameter should be set to `private_ip_address`.  
This parameter is managed by the `ec2_vpc_destination_variable` BCD variable.

More information on dynamic EC2 inventory management can be found in [this blog post](https://aws.amazon.com/blogs/apn/getting-started-with-ansible-and-dynamic-amazon-ec2-inventory-management/).