This folder houses all the Ansible roles to automate the configuration of your local environment and to deploy the necessary DynamoDB and DAX components to AWS. AWS Deployments leverage AWS CDK to automate the provisioning of AWS resources. For more information, navigate to the CDK directory.
To just see how to run different plays and their corresponding commands without knowing how it all works together, skip down to the Plays section below.
Note that if no ssh_key_name
is provided, the default value is $USER-dax-pair
- You must be logged into the AWS CLI prior to running the CDK. Ensure you're logged into your target AWS account by running
aws sts get-caller-identity
. - Install pip (Assuming python3 is already installed):
sudo apt-get install python3-pip
- Install the most recent version of Ansible and jmespath from pip:
pip3 install --user ansible jmespath
- Export the local bin path:
export PATH=~/.local/bin:$PATH
- Install curl (
sudo apt-get install curl
) - Install the required Ansible dependencies using Ansible Galaxy (
ansible-galaxy install -r requirements.yml
)
To initialize the stack (including the local Elastic Stack), run the deploy_benchmarker.yml
playbook with the init
tag:
ansible-playbook -i inventories/local \
--tags init \
--ask-become-pass \
deploy_benchmarker.yml
To deploy the entire benchmarking stack all at once, local and AWS, use the following command:
ansible-playbook -i inventories/local \
-e vpc_id={{ vpc_id_to_deploy_into }} \
deploy_benchmarker.yml
The same prerequisites apply to the CDK with the necessary environment or CDK parameters as is defined in the CDK Parameters section of the CDK README. Ansible will only resolve the following variables for you; all other variables must be supplied by the user a runtime:
localIp
awsAccount
To run the benchmarkers, run the following command:
ansible-playbook -i inventories/local \
-e dax_endpoint={{ the_dax_endpoint_uri }} \
run_benchmarkers.yml
Let's analyze how an ansible command is formed:
ansible-playbook -i inventories/local \
-e vpc_id={{ vpc_id_to_deploy_into }} \
--ask-become-pass \
deploy_benchmarker.yml
ansible-playbook
is the program that runs our playbook, deploy_benchmarker.yml
. Playbooks
are the main "blueprints" of automation tasks that Ansible uses.
-i inventories/local
tells Ansible that we want to use the hosts and variables associated
with the local
environment. So later in the playbook and
roles, when we're
using variables and hosts, we're pulling the corresponding values for this environment. More
information about inventories in Ansible can be found
here. Inventories would be a good place
to start learning about Ansible if you're confused by what's happening in this module.
This is where you'd put variables to persist between runs of this application. By default, they are only provided for you if you follow the steps in the main repository script.
-e vpc_id={{ vpc_id_to_deploy_into }}
is setting an extra variable for the playbook to use (fun fact: -e
is an alias
for --extra-vars
). This variable is not defined by default in your local host vars because
we don't know what VPC you want to deploy the stack into. If you're running this using the main TUI script in the root
of this repo, then this is handled graphically for you. This will be set on the first run of the CDK deployment, so you do not have to specify
the vpc_id
between subsequent runs. Otherwise, if you wish to change the VPC ID for any reason (including prior to an initial run), and
you wish to run this Ansible playbook manually, you can add it to your host vars file.
--ask-become-pass
is telling Ansible to prompt you for your sudo password, so it can run installs and other configuration tasks on your behalf.
deploy_benchmarker.yml
is the name of our playbook that we want Ansible to run.
Each part of the deploy_benchmarker.yml
playbook has
tags associated with them.
These tags allow us to tell Ansible which part(s) of the playbook we want to run. In other words, tags
allow us to tell Ansible which parts of the overall Logstash deployment pipeline we want to run.
They deploy_benchmarker.yml
playbook (and a couple of roles) has the following tags in it:
init
init_elk
stop_elk
prerequisites
elk
cdk
run
deploy
destroy
destroy_key_pair
upload
dynamodb
dax
crud
read-only
To view all these tags and their associated plays from the ansible
CLI, run
ansible-playbook deploy_benchmarker.yml --list-tags
Using these tags, we can specify that we only want to run specific parts of the Benchmarking Deployment pipeline that's
defined in the deploy_benchmarker.yml
playbook.
For example: If we only wanted to start the ELK (Elasticsearch-Logstash-Kibana) stack, we would run this:
ansible-playbook -i inventories/local --tags elk deploy_benchmarker.yml
Likewise, if we wanted to stop the ELK stack, we'd run this:
ansible-playbook -i inventories/local --tags stop_elk deploy_benchmarker.yml
Note the --tags
argument. This allows us to tell Ansible to only run tasks or roles that have the
elk
or stop_elk
tag on them.
We can also specify multiple arguments for --tags
if we wish; for example, if we wanted to simply spin up the local
Elastic stack (synonymous with ELK stack), and deploy the CDK, we'd run the following:
ansible-playbook -i inventories/local -e vpc_id=vpc-1234567890 --tags 'elk,cdk' deploy_benchmarker.yml
The following plays can be run from these playbooks using the tags with the following commands:
A sudo password is required to install applications, so we tell Ansible to prompt us for it at the start:
ansible-playbook -i inventories/local --tags init deploy_benchmarker.yml --ask-become-pass
This assumes you already know the VPC ID to deploy into and have already created an SSH key pair and have the key pair
locally in your ~/.ssh
directory with a .pem
extension.
If you did not do this manually, it was done for you automatically and the created pair is under ~/.ssh/$USER-dax-pair.pem
.
You can either specify the vpc_id
argument directly via -e
in the command, or you can hard code
it in your host_vars. You must also already be logged into the AWS CLI for
your target environment, or specify a profile_id
either in your host_vars
or via -e
, along with an aws_region
. If you're not
already logged into AWS, your profile_id
must be configured to be picked up automatically from your ~/.aws/config
or
~/.aws/credentials
files with no additional login steps in order to deploy to AWS.
ansible-playbook -i inventories/local -e vpc_id=vpc-1234567890 --tags deploy deploy_benchmarker.yml
ansible-playbook -i inventories/local --tags stop_elk deploy_benchmarker.yml
Once more, this assumes you either have the DAX
endpoint and the VPC ID hardcoded in your host vars, or you provide them via -e
.
If you've already run a CDK deploy via Ansible, then you should not need to specify anything.
Note: For safety purposes, this will not wipe away the ssk_key_name
in your ~/.ssh
directory. If you specified
a pre-existing key to use for this deployment, it will not be touched. If you did not specify a key name, the automatically
generated key $USER-dax-pair
will be left in your ~/.ssh
directory. If you wish to delete this pair from your local machine
and remove it from AWS, also specify the destroy_key_pair
tag as well in the below command.
You can either specify the vpc_id
argument directly via -e
in the command, or you can hard code
it in your host_vars. You must also already be logged into the AWS CLI for
your target environment, or specify a profile_id
either in your host_vars
or via -e
, along with an aws_region
. If you're not
already logged into AWS, your profile_id
must be configured to be picked up automatically from your ~/.aws/config
or
~/.aws/credentials
files with no additional login steps in order to deploy to AWS.
Destroy Everything, But Leave the ssh_key_name Key-Pair Alone:
ansible-playbook -i inventories/local -e vpc_id=vpc-1234567890 --tags destroy deploy_benchmarker.yml
Destroy Everything, Including the ssh_key_name Key-Pair
ansible-playbook -i inventories/local -e vpc_id=vpc-1234567890 --tags 'destroy,destroy_key_pair' deploy_benchmarker.yml
A sudo password is required to install applications, so we tell Ansible to prompt us for it at the start:
ansible-playbook -i inventories/local --tags prerequisites deploy_benchmarker.yml --ask-become-pass
ansible-playbook -i inventories/local --tags elk deploy_benchmarker.yml
This assumes you already know the VPC ID to deploy into and have already created an SSH key pair and have the key pair
locally in your ~/.ssh
directory with a .pem
extension. If you did not do this manually, it was done for you automatically
and the created pair is under ~/.ssh/$USER-dax-pair.pem
. You can either specify the vpc_id
argument directly via -e
in the command, or you can hard code it in your host_vars.
If you've already run a CDK deploy via Ansible, then you should not need to specify anything.
You must also already be logged into the AWS CLI for your target environment, or specify a profile_id
either in your
host_vars
or via -e
, along with an aws_region
. If you're not already logged into AWS, your profile_id
must be
configured to be picked up automatically from your ~/.aws/config
or ~/.aws/credentials
files with no additional
login steps in order to deploy to AWS.
ansible-playbook -i inventories/local --tags cdk deploy_benchmarker.yml
ansible-playbook -i inventories/local --tags upload deploy_benchmarker.yml
This assumes the CDK is already deployed and an EC2 instance already exists. This also assumes you either have the DAX
endpoint and the VPC ID hardcoded in your host vars, or you provide them via -e
.
If you've already run a CDK deploy via Ansible, then you should not need to specify anything.
Additionally, You must also already be logged into the AWS CLI for
your target environment, or specify a profile_id
either in your host_vars
or via -e
, along with an aws_region
. If you're not
already logged into AWS, your profile_id
must be configured to be picked up automatically from your ~/.aws/config
or
~/.aws/credentials
files with no additional login steps in order to deploy to AWS:
ansible-playbook -i inventories/local --tags run run_benchmarkers.yml
This assumes the CDK is already deployed and an EC2 instance already exists. This also assumes you either have the DAX
endpoint and the VPC ID hardcoded in your host vars, or you provide them via -e
.
If you've already run a CDK deploy via Ansible, then you should not need to specify anything.
Additionally, You must also already be logged into the AWS CLI for
your target environment, or specify a profile_id
either in your host_vars
or via -e
, along with an aws_region
. If you're not
already logged into AWS, your profile_id
must be configured to be picked up automatically from your ~/.aws/config
or
~/.aws/credentials
files with no additional login steps in order to deploy to AWS:
ansible-playbook -i inventories/local --tags dynamodb deploy_benchmarker.yml
or
ansible-playbook -i inventories/local --tags dax deploy_benchmarker.yml
Note the difference in tags: dynamodb
and dax
This assumes the CDK is already deployed and an EC2 instance already exists. This also assumes you either have the DAX
endpoint and the VPC ID hardcoded in your host vars, or you provide them via -e
.
If you've already run a CDK deploy via Ansible, then you should not need to specify anything.
Additionally, You must also already be logged into the AWS CLI for
your target environment, or specify a profile_id
either in your host_vars
or via -e
, along with an aws_region
. If you're not
already logged into AWS, your profile_id
must be configured to be picked up automatically from your ~/.aws/config
or
~/.aws/credentials
files with no additional login steps in order to deploy to AWS:
CRUD:
ansible-playbook -i inventories/local --tags crud deploy_benchmarker.yml
read-only:
ansible-playbook -i inventories/local --tags read-only deploy_benchmarker.yml
The following variables are supported to be specified via the -e
argument when running the deploy_benchmarker.yml
playbook:
Variable Name | Description | Required? |
---|---|---|
profile_id |
The name of the AWS CLI profile you wish to deploy with; Defaults to using the AWS_PROFILE environment variable |
|
vpc_id |
The ID of the VPC in the AWS account you're deploying to where you want the CDK components created Only required on first run only |
* |
local_ip |
The public IP of your local machine; Defaults to the response from curl -s -L checkip.amazonaws.com |
|
ssh_key_name |
The name of the SSH key-pair that will be used when creating the EC2 instance to allow you SSH access to it; Defaults to $USER-dax-pair |
|
aws_account |
The account ID of the AWS account you're deploying into; Defaults to the result of aws sts get-caller-identity | jq -r .Account |
|
base_table_name |
The base name to use when creating the DynamoDB table; Defaults to high-velocity-table |
|
cdk_action |
The action to perform when deploying the CDK; Defaults to deploy |
|
duration |
How long to run each simulation for; Defaults to 1800 seconds |
|
benchmarker |
Which benchmarker to run (i.e. dynamodb or dax ) |
|
dax_endpoint |
The DAX URI to use to hit the DAX cluster; Only required when running the benchmarkers and without an initial CDK deploy) |
* |
When first running from scratch, you'll want to run with the init
tags first to initialize the Elastic Stack and install the prerequisites, then run again without any tags to actually
deploy everything and run the benchmarkers. If you only want to run the benchmarkers, run the run_benchmarkers.yml
playbook, or specify the run
tag.
You can generally get more information about your problem by adding -vvv
to the end of your
ansible-playbook
command. The more v
's you add, the more verbose the output and the more information
you will get. For example:
ansible-playbook -i inventories/local -e cdk_action=destroy --tags 'elk,cdk' deploy_benchmarker.yml -vvv