Merge pull request #90 from bonitasoft/feat/BCD-188_deploy-existing-database

feat(stack_deploy): how to deploy with an existing database (BCD-188)

md/aws_prerequisites.md

@@ -35,44 +35,6 @@ Further configuration instructions for **AWS single sign-on** can be found [on t
         ]
     }
     ```
-1. Create an IAM Policy to allow to describe DB instances and list tags (mandatory for dynamic inventory script).
-    - **Policy name**: RDSDescribeDBInstances
-    - **Policy document**:
-    ```json
-    {
-        "Version": "2012-10-17",
-        "Statement": [
-            {
-                "Sid": "Stmt1498730873000",
-                "Effect": "Allow",
-                "Action": [
-                    "rds:DescribeDBInstances",
-                    "rds:ListTagsForResource"
-                ],
-                "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:*"
-            }
-        ]
-    }
-    ```    
 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**:

md/deploy-with-existing-database.md

+# How to deploy with an existing database
+
+By default, BCD provisions a database Docker container while deploying your Bonita stack.  
+Alternatively, BCD also lets you connect your Bonita stack with an existing database server. The database vendor and version has to be supported by BCD though.
+
+When the `bonita_db_host` variable is defined, BCD does not create a database container. Instead, BCD expects to connect to an existing database.  
+The following variables are to be set accordingly:
+- `bonita_db_vendor` - Vendor name in [postgres, mysql, oracle].
+- `bonita_db_host` - Host name or IP address (eg. `postgres.a1bac2defghi.us-west-2.rds.amazonaws.com`).
+- `bonita_db_port` - Port number (eg. `5432`).
+- `bonita_db_admin_user` - Name of an existing Administrator user (aka. "Master username"). This user must be granted permissions to create the Bonita and Business Data Model (BDM) databases.
+- `bonita_db_admin_pass` - Password of the Administrator user.
+
+Example with Amazon RDS <!--{.h2}-->
+
+One typical use case is to deploy your Bonita stack using an [Amazon RDS](https://aws.amazon.com/rds/) instance.  
+
+1. Prior to creating your RDS instance, create and customize a [DB Parameter Group](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html) in order to set database parameters for Bonita. Refer to Bonita documentation to check how to [Customize RDBMS to make it work with Bonita](https://documentation.bonitasoft.com/bonita/${bonitaDocVersion}/database-configuration).
+1. Create your RDS instance using the DB parameter group created previously. Make sure the assigned security group allows access to the DB instance.  
+   Leave the **Database Name** field empty to not create a database. BCD will create required databases automatically.
+1. Report connection information into your BCD scenario:
+  - `bonita_db_host` - DB instance endpoint (eg. `postgres.a1bac2defghi.us-west-2.rds.amazonaws.com`).
+  - `bonita_db_port` - Database Port (eg. `5432`).
+  - `bonita_db_admin_user` - Master Username.
+  - `bonita_db_admin_pass` - Master Password.

md/scenarios.md

@@ -42,7 +42,6 @@ The following variables are specific to AWS deployments ie. when `bcd_provider`
 | ec2_discovery_iam_role          | N         | -       | Name of the IAM role to attach to EC2 instances to allow Hazelcast EC2 auto-discovery. This is MANDATORY when deploying a Bonita cluster on AWS with BCD.                                                                                                                                                                                                         | ClusterBCD                |
 | ec2_vpc_destination_variable    | N         | -       | Type of network address the EC2 dynamic inventory script should use. 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`. | ip_address                |
 | boto_path                       | N         | ~/.boto | Path to the Boto file with the AWS credentials.                                                                                                                                                                                                                                                                                                                   | ~/.boto                   |
-| rds                             | N         | false   | Use an existing AWS RDS database instance. By default this parameter is set to `false` to create an EC2 instance for Bonita database.                                                                                                                                                                                                                             | true                      |
 | aws_ami                         | Y         | -       | Common AMI for all EC2 instances. Depends on AWS region. Should be Ubuntu 14.04 (trusty) or Ubuntu 16.04 (xenial) and ebs-ssd type.                                                                                                                                                                                                                               | ami-fc4f5e85              |
 | aws_database_instance_type      | Y         | -       | EC2 instance type for the database instance.                                                                                                                                                                                                                                                                                                                      | t2.micro                  |
 | aws_bonita_instance_type        | Y         | -       | EC2 instance type for the Bonita instances.                                                                                                                                                                                                                                                                                                                       | t2.micro                  |

md/taxonomy.md

@@ -11,6 +11,7 @@
         * [Configure AWS single sign-on](aws_sso.md)
         * [Assume IAM role within AWS Organizations](aws_organizations.md)
         * [Deploy with a static inventory](deploy_with_static_inventory.md)
+        * [Deploy with an existing database](deploy-with-existing-database.md)
         * [Customize the Bonita container](_custom_init.md)
             * [Using initialization scripts](custom_init.md)
             * [Configuring REST API authorization](how_to_configure_rest_api_authorization.md)