Tutorial: Monitor Important Changes to Your Organization with
CloudWatch Events

This tutorial shows how to configure CloudWatch Events to monitor your organization
for changes. You
start by configuring a rule that is triggered when users invoke specific Organizations
operations. Next,
you configure CloudWatch Events to run an AWS Lambda function when the rule is triggered,
and you configure
Amazon SNS to send an email with details about the event.

Test your new rule by running one of the monitored operations. In this tutorial, the
monitored operation is creating an organizational unit (OU). You view the log entry
that
the Lambda function creates, and you view the email that SNS sends to subscribers.

Prerequisites

This tutorial assumes the following:

You can sign in to the AWS Management Console as an IAM user from the master account
in your
organization. The IAM user must have permissions to create and configure a log in
CloudTrail,
a function in Lambda, a topic in Amazon SNS, and a rule in CloudWatch. For more information
about
granting permission, see Access Management
in the IAM User Guide, or the guide for the service
for which you want to configure access.

You have access to an existing S3 bucket (or you have permission to create a bucket)
to receive the CloudTrail log that you configure in the first step.

Important

Currently, AWS Organizations is hosted in only the US East (N. Virginia) Region (even
though it is
available globally). To perform the steps in this tutorial, you must configure the
AWS Management Console
to use that region.

Step 1: Configure a Trail and Event Selector

In this step, you sign in to the master account and configure a log (called a trail) in AWS CloudTrail. You also configure an event selector on the
trail to capture all read/write API calls so that CloudWatch Events has calls to trigger
on.

On the navigation bar in the upper-right corner of the console, choose the
US East (N. Virginia) Region. If you choose a different region,
AWS Organizations does not appear as an option in the CloudWatch Events configuration
settings, and CloudTrail does
not capture information about Organizations.

In the navigation pane, choose Trails.

Choose Add new trail.

For Trail name, type My-Test-Trail.

Perform one of the following options to specify where CloudTrail is to deliver its
logs:

If you already have a bucket, choose No next to
Create a new S3 bucket, and then choose the bucket name from
the S3 bucket list.

If you need to create a bucket, choose Yes next to
Create a new S3 bucket, and then for S3
bucket, type a name for the new bucket.

CloudWatch Events enables you to choose from several different ways to send alerts
when an alarm rule
matches an incoming API call. This tutorial demonstrates two methods: invoking a Lambda
function that can log the API call, and sending information to an Amazon SNS topic
that sends an
email or text message to the topic's subscribers. In the next two steps, you create
the
components you need, the Lambda function, and the Amazon SNS topic.

Step 2: Configure a Lambda Function

In this step, you create a Lambda function that logs the API activity that is sent
to it by
the CloudWatch Events rule that you configure later.

This sample code logs the event with a "LogOrganizationEvents" marker string
followed by the JSON string that makes up the event.

For Role, choose Create a custom role, and
then at the bottom of the AWS Lambda requires access to your
resources page, choose Allow. This role grants your
Lambda function permissions to access the data it requires and to write its output
log.

Now you can create a subscription for the topic. Choose the ARN for the topic that
you
just created.

Choose Create subscription.

On the Create subscription page, for
Protocol, choose Email.

For Endpoint, type your email address.

Choose Create subscription. AWS sends an email to the email
address that you specified in the preceding step. Wait for that email to arrive, and
then choose the Confirm subscription link in the email to verify
that you successfully received the mail.

Return to the console and refresh the page. The Pending
confirmation message disappears and is replaced by the now valid
subscription ID.

Step 4: Create a CloudWatch Events Rule

Now that the required Lambda function exists in your account, you create a CloudWatch
Events rule that
invokes it when the criteria in the rule are met.

Choose Specific operation(s), and then enter the APIs that
you want monitored: CreateAccount,
CreateOrganizationalUnit, and
LeaveOrganization. You can select any others that you want as
well. For a complete list of available Organizations APIs, see the AWS Organizations API Reference.

Under Targets, under Lambda function, in the
drop-down list, select the function you created in the previous procedure.

Under Targets, choose Add target.

In the new target row, choose the drop-down header, and then select SNS
topic.

For Topic, select the topic named
OrganizationCloudWatchTopic that you created in the preceding
procedure.

Choose Configure details.

On the Configure rule details page, for Name
type OrgsMonitorRule, leave State selected,
and then choose Create rule.

Step 5: Test Your CloudWatch Events Rule

In this step, you create an organizational unit (OU) and then observe the CloudWatch
Events rule
generate a log entry and send an email to you with details about the event.

Check your email account for a message from OrgsCWEvnt (the
display name of your SNS topic). The body of the email contains the same JSON text
output
as the log entry that is shown in the preceding step.

Clean up: Remove the Resources You No Longer Need

To avoid incurring charges, you should delete any AWS resources that you created as
part
of this tutorial that you do not want to keep.

That's it. In this tutorial, you configured CloudWatch Events to monitor your organization
for
changes. You configured a rule that is triggered when users invoke specific Organizations
operations.
The rule ran an AWS Lambda function that logged the event and sent an email that contains
details about the event.