aaia /

Filename Size Date modified Message
aaia
cloudformation
config
templates
tests
340 B
11.4 KB
7.8 KB
15.8 KB
110 B
363 B
231 B
5.3 KB
1.5 KB

Amazon AWS Integration (for) Atlassian

At the core aaia is an AWS Lambda function being triggered by an AWS SNS message, if the message matches our configured criteria it is able to report events to Slack, Stride, HipChat and/or JIRA.

In the most generic case these AWS SNS messages are created by an AWS CloudWatch Event; however, you can also publish directly to aaia's AWS SNS (see Generic Event below).

Configuration

aaia provides an example configuration at config/aaia.yml.example, use this file as a starting point by copying it to config/aaia.yml, the path is excluded from version control using our .gitignore (there is no need to worry about accidental commits).

$ cp config/aaia.example.yml config/aaia.yml

Token Generation

Slack

Create a new Slack Application, then add the feature Incoming Webhooks. Toggle the feature On, then click the Add Webhook To Workspace button at bottom of page. Copy the Webhook URL and add to aaia configuration.

Stride

Within a Stride conversation (in the application) click the Apps icon from the right sidebar. In the upper part of the panel click + (plus symbol). Next click Add custom app, and select API tokens.

HipChat

Login to your HipChat Home Page and find the Room you wish to send alerts. On the left hand panel click Tokens. Create a new token with the Send Notification scope.

JIRA

Generate a new token from Atlassian's API Tokens Page.

Logging

A default logger is provided and configured in config/logging.yml, this logger is utilized throughout the aaia execution and can be reviewed in your AWS Lambda logs.

Templates

We provide a couple Jinja2 templates for different event criteria, have a look in the templates/ directory to get a better idea.

Feel free to add any additional templates as you see fit, just be sure the new templates are referenced in your config/aaia.yml.

Admin script

We provide a single admin script for doing all things aaia.

To use this script install the admin_requirements.txt into a python3 virtualenv:

$ virtualenv -p python3 venv
$ source venv/bin/activate
$ pip install -r admin_requirements.txt

You can now execute admin.py with --help to get an idea of what things it can do.

$ ./admin.py --help
Usage: admin.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  build               Build aaia into a aws lambda zipfile
  coverage            Run coverage on test results
  create_stack        Creates a cloudformation stack using template
  lint                Run lint on source code
  run_event           Run a sample event
  show_stack_outputs  Show a cloudformation stacks outputs
  show_stack_status   Show a cloudformation stack
  test                Run tests on source code
  update_stack        Update a cloudformation stack with new...
  upload              Upload zipfile to s3 bucket

Running with sample_events

We provide a document with sample events at sample_events.json, using adming.py we can run any of these events locally, this can be helpful with test formatting, config, and all around functionality:

./admin.py run_event -e generic

Lint, test, and coverage

Using the admin.py script we can run lint, tests, and coverage, this will be helpful if you wish to contribute to aaia:

$ ./admin.py lint
$ ./admin.py test
$ ./admin.py coverage

Build artifact

Before we can create the AWS Lambda function we need to build aaia into a compatible zipfile:

$ ./admin.py build -o zipfiles
Completed build of /Users/jness/Git/aaia/zipfiles/aaia-0.2.21.zip

Upload artifact

Once we have our zipfile we need to upload it to a AWS S3 Bucket, this is so our AWS CloudFormation can deploy the application as a AWS Lambda function:

$ ./admin.py upload -a production -f zipfiles/aaia-0.2.21.zip
Performing upload of /Users/jness/Git/aaia/zipfiles/aaia-0.2.21.zip to region us-east-1

Create Stack

Once our zipfile has been uploaded we can create our AWS CloudFormation stack. The create_stack command will prompt you for all needed parameters:

$ ./admin.py create_stack -a production -z aaia-0.2.21.zip
Creating aws cloudformation stack in region us-east-1

Show Stack Status

It may take a couple minutes for your stack to complete, use the show_stack_status command to track the creation / update process.

$ ./admin.py show_stack_status -a production
Stack status in region us-east-1: UPDATE_COMPLETE

Show Stack Resources

aaia's CloudFormation stack will create multiple resources in your region, to list our all resources use the show_stack_resources command:

$ ./admin.py show_stack_resources -a production
Stack resource in region us-east-1 : AWS::Events::Rule = aaia-autoscale
Stack resource in region us-east-1 : AWS::Events::Rule = aaia-cloudformation
Stack resource in region us-east-1 : AWS::Events::Rule = aaia-health
Stack resource in region us-east-1 : AWS::IAM::Role = aaia
Stack resource in region us-east-1 : AWS::Lambda::Function = aaia
Stack resource in region us-east-1 : AWS::Lambda::Permission = aaia-MyLambdaPermissions-XXXXXXXXX
Stack resource in region us-east-1 : AWS::SNS::Subscription = aaia-MySNSSubscription-XXXXXXXXX
Stack resource in region us-east-1 : AWS::SNS::Topic = arn:aws:sns:us-east-1:1111:aaia
Stack resource in region us-east-1 : AWS::SNS::TopicPolicy = aaia-MySNSTopicPolicy-XXXXXXXXX

Show Logs

To get verbose logs for your Lambda executions use the show_logs command.

Use the optional -f flag to filter on events:

$ ./admin.py show_logs -a production -f ERROR
us-west-2
 [ 2018-04-13 04:35:48,755 ][ stride.send ] ERROR - Failed to send alert, {"code":401,"message":"Unauthorized"}
 [ 2018-04-13 04:36:01,958 ][ stride.send ] ERROR - Failed to send alert, {"code":401,"message":"Unauthorized"}
 [ 2018-04-13 06:39:36,705 ][ stride.send ] ERROR - Failed to send alert, {"code":401,"message":"Unauthorized"}

Update Stack

In order to update your aaia version, merely build and upload a new zipfile, then update the stack's ZipFile parameter:

$ ./admin.py update_stack -a production -k ZipFile -v aaia-{new version}.zip

Or say we wanted to enable / disable an AWS CloudWatch Event:

$ ./admin.py update_stack -a production -k CloudformationState -v ENABLED

Generic Event

aaia can also receive generic AWS SNS messages.

You will notice a generic event type in config/aaia.example.yml, and a templates/generic.js template.

Below is an example of publishing a generic message using awscli:

$ aws sns publish --message '{"source": "generic", "text": "Hello World"}' --topic-arn {{ your SNS ARN here }}