Yingyi Bu has uploaded a new change for review. https://asterix-gerrit.ics.uci.edu/1647
Change subject: Update ansible and aws docs. ...................................................................... Update ansible and aws docs. Change-Id: I2bf4dab747a149f6fd9f1a74cf862043171cf03e --- M asterixdb/asterix-doc/src/site/markdown/ansible.md M asterixdb/asterix-doc/src/site/markdown/aws.md 2 files changed, 58 insertions(+), 53 deletions(-) git pull ssh://asterix-gerrit.ics.uci.edu:29418/asterixdb refs/changes/47/1647/1 diff --git a/asterixdb/asterix-doc/src/site/markdown/ansible.md b/asterixdb/asterix-doc/src/site/markdown/ansible.md index fa3f483..a52383b 100644 --- a/asterixdb/asterix-doc/src/site/markdown/ansible.md +++ b/asterixdb/asterix-doc/src/site/markdown/ansible.md @@ -23,8 +23,7 @@ * [Manage the lifecycle of your instance](#lifecycle) ## <a id="Introduction">Introduction</a> -This installation option wraps the basic, low-level installation binaries described in the [NCService -installation option](ncservice.html), and provides several wrapped [Ansible](https://www.ansible.com/)-based +This installation option provides several wrapped [Ansible](https://www.ansible.com/)-based scripts to deploy, start, stop, and erase an AsterixDB instance on a multi-node cluster without requiring users to interact with each individual node in the cluster. @@ -43,14 +42,13 @@ pip install boto pip install boto3 - **Make sure that the version of Ansible is no less than 2.2.1.0.** + Note that you might need `sudo` depending on your system configuration. + **Make sure that the version of Ansible is no less than 2.2.1.0.** : - * Download a released [simple server package](http://asterixdb.apache.org/download.html). + $ansible --version + ansible 2.2.1.0 - Alternatively, you can follow the [instruction](https://github.com/apache/asterixdb#build-from-source) to - build from source. - - * In the extracted directory from the `simple server package`, navigate to `opt/ansible/` + * Download the AsterixDB distribution package, unzip it, and navigate to `opt/ansible/` $cd opt/ansible @@ -58,31 +56,15 @@ README bin conf yaml - `bin` contains scripts that deploy, start, stop and erase a multi-node AsterixDB instance, according to + `bin` contains scripts that deploy, start, stop and erase a multi-node AsterixDB cluster, according to the configuration specified in files under `conf/`. `yaml` contains internal Ansible scripts that the shell scripts in `bin` use. -## <a id="config">Configuration and parameters</a> - * **Parameters**. Edit the instance configuration file `conf/cc.conf` when necessary. - You can add/update whatever parameters in the **[common]** and **[nc]** sections (except IPs and ports). - For example: - - [common] - log.level=INFO - - [nc] - txn.log.dir=txnlog - iodevices=iodevice - command=asterixnc - - More parameters and their usage can be found [here](ncservice.html#Parameters). - Note that with this installation option, all parameters in the **[cc]** and **[ncservice]** - section will use defaults and cannot be changed. - +## <a id="config">Configuring the cluster</a> * **Nodes and account**. Edit the inventory file `conf/inventory` when necessary. - You mostly only need to sepecify the node DNS names (or IPs) for the cluster controller, i.e., the master node, + You mostly only need to specify the node DNS names (or IPs) for the cluster controller, i.e., the master node, in the **[cc]** section, and node controllers, i.e., slave nodes, in the **[ncs]** section. The following example configures a cluster with two slave nodes (172.0.1.11 and 172.0.1.12) and one master node (172.0.1.10). @@ -95,7 +77,7 @@ 172.0.1.12 **Configure passwordless ssh from your current client that runs the scripts to all nodes listed - in `conf/inventory`.** + in `conf/inventory` as well as `localhost`.** If the ssh user account for target machines is different from your current username, please uncomment and edit the following two lines: @@ -105,9 +87,12 @@ If you want to specify advanced Ansible builtin variables, please refer to the [Ansible documentation](http://docs.ansible.com/ansible/intro_inventory.html). - * **Remote working directories**. Edit `conf/instance_settings.yml` to change the instance binary directories + * **Remote working directories**. Edit `conf/instance_settings.yml` to change the remote binary directories when necessary. By default, the binary directory will be under the home directory (as the value of Ansible builtin variable ansible_env.HOME) of the ssh user account on each node. + + # The name of the product being used. + product: asterixdb # The parent directory for the working directory. basedir: "{{ ansible_env.HOME }}" @@ -116,21 +101,25 @@ binarydir: "{{ basedir }}/{{ product }}" -## <a id="lifecycle">Manage the lifecycle of your instance</a> - * Deploy the AsterixDB binary to all nodes: +## <a id="lifecycle">Manage the lifecycle of your AsterixDB cluster</a> + * Deploy the binary to all nodes: bin/deploy.sh - * Launch your cluster instance: + * Every time before starting the AsterixDB cluster, you can edit the instance configuration file + `conf/instance/cc.conf`, except that IP addresses/DNS names are generated and cannot + be changed. All available parameters and their usage can be found [here](ncservice.html#Parameters). + + * Launch your AsterixDB cluster: bin/start.sh - Now you can use the multi-node AsterixDB instance. + Now you can use the multi-node AsterixDB cluster by sending queries to the master node listed in `conf/inventory`. - * If you want to stop the the multi-node AsterixDB instance, run the following script: + * If you want to stop the the multi-node AsterixDB cluster, run the following script: bin/stop.sh - * If you want to remove the AsterixDB binary on all nodes, run the following script: + * If you want to remove the binary on all nodes, run the following script: bin/erase.sh diff --git a/asterixdb/asterix-doc/src/site/markdown/aws.md b/asterixdb/asterix-doc/src/site/markdown/aws.md index 272beb0..525a3cf 100644 --- a/asterixdb/asterix-doc/src/site/markdown/aws.md +++ b/asterixdb/asterix-doc/src/site/markdown/aws.md @@ -25,10 +25,11 @@ ## <a id="Introduction">Introduction</a> Note that you can always manually launch a number of Amazon Web Services EC2 instances and then run the Ansible cluster installation scripts as described [here](ansible.html) separately to manage the - lifecycle of an AsterixDB instance on those EC2 instances. + lifecycle of an AsterixDB cluster on those EC2 instances. However, via this installation option, we provide a combo solution for automating both AWS EC2 - and AsterixDB, where you can run only one script to start/stop an AsterixDB instance on AWS. + and AsterixDB, where you can run only one script to deploy, start, stop, and terminate + an AsterixDB cluster on AWS. ## <a id="Prerequisites">Prerequisites</a> * Supported operating systems for the client: **Linux** and **MacOS** @@ -47,14 +48,13 @@ pip install boto pip install boto3 - **Make sure that the version of Ansible is no less than 2.2.1.0.** + Note that you might need `sudo` depending on your system configuration. + **Make sure that the version of Ansible is no less than 2.2.1.0.** : - * Download a released [simple server package](http://asterixdb.apache.org/download.html). + $ansible --version + ansible 2.2.1.0 - Alternatively, you can follow the [instruction](https://github.com/apache/asterixdb#build-from-source) to - build from source. - - * In the extracted directory from the `simple server package`, navigate to `opt/aws/` + * Download the AsterixDB distribution package, unzip it, navigate to `opt/aws/` $cd opt/aws @@ -100,7 +100,7 @@ # The data center region for ec2 instances. region: us-west-2 - # The tag for each ec2 machine. + # The tag for each ec2 machine. Use different tags for isolation. tag: scale_test # The name of a security group that appears in your AWS console. @@ -125,10 +125,13 @@ # The user name. user: ec2-user - # Whether to reuse one nc machine to host cc. + # Whether to reuse one slave machine to host the master process. cc_on_nc: false **As described in [prerequisites](#Prerequisites), the following parameters must be customized:** + + # The tag for each ec2 machine. Use different tags for isolation. + tag: scale_test # The name of a security group that appears in your AWS console. group: default @@ -153,16 +156,29 @@ binarydir: "{{ basedir }}/{{ product }}" -### <a id="lifecycle">Manage the lifecycle of your instance</a> - * Start an AWS-based AsterixDB cluster: +### <a id="lifecycle">Manage the lifecycle of your AsterixDB cluster on AWS</a> + * Allocate AWS EC2 nodes and deploy the binary to all allocated AWS nodes: - bin/start.sh + bin/deploy.sh - Now you can use the cluster instance through the public IP or DNS name of the master node. + * Every time before starting the AsterixDB cluster, you can edit the instance configuration file + `conf/instance/cc.conf`, except that IP addresses/DNS names are generated and cannot + be changed. All available parameters and their usage can be found [here](ncservice.html#Parameters). - * If you want to terminate the AsterixDB instance, run the following script: + * Launch your AsterixDB cluster on AWS: - bin/stop.sh + bin/start.sh - **Note that it will destroy everything in the AsterixDB instance you installed and terminate all AWS nodes - for the cluster.** + Now you can use the multi-node AsterixDB cluster on AWS by sending queries to the master node + listed in `conf/instance/inventory`. + + * If you want to stop the AWS-based AsterixDB cluster, run the following script: + + bin/stop.sh + + * If you want to terminate the AWS nodes that runs the AsterixDB cluster, run the following script: + + bin/terminate.sh + + **Note that it will destroy everything in the AsterixDB cluster you installed and terminate all AWS nodes + for the cluster.** -- To view, visit https://asterix-gerrit.ics.uci.edu/1647 To unsubscribe, visit https://asterix-gerrit.ics.uci.edu/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I2bf4dab747a149f6fd9f1a74cf862043171cf03e Gerrit-PatchSet: 1 Gerrit-Project: asterixdb Gerrit-Branch: master Gerrit-Owner: Yingyi Bu <[email protected]>
