AWS Cloud Operations Blog
Using lifecycle events to track AWS Control Tower actions and trigger automated workflows
Many customers that I work with are creating and provisioning new accounts using AWS Control Tower. They prefer an AWS native solution for creating their environment knowing that it will be based upon documented AWS Best Practices. As customers scale their account creation, there exists an opportunity to use additional Control Tower features to perform further account enhancements.
In this post, I demonstrate how to use lifecycle events. This is a feature in Control Tower that allows you to track the completion of actions such as creating a new account using Control Tower’s Account Factory. I also show how you can use lifecycle events to trigger an automated workflow.
I refer to the following services in this post:
Background
AWS Control Tower uses several AWS services including AWS Organizations, AWS IAM, AWS Config, AWS CloudTrail, and AWS Service Catalog to build a well-architected multi-account AWS environment. As a result, when Control Tower takes an action, such as enabling a guardrail on accounts in an organizational unit (OU), it executes many processing steps and numerous API calls to these services
Lifecycle events inform you that the Control Tower action that you had initiated has now completed. Control Tower creates a lifecycle event after all subtasks relating to the originating Control Tower action have completed. Lifecycle events are recorded as CloudTrail events, and they are also delivered to Amazon CloudWatch Events (and to Amazon EventBridge) as events, as seen in the following diagram. The lifecycle event log also states if the Control Tower action you initiated completed successfully or not.
Control Tower creates lifecycle events at the completion of the following actions:
- creating a new landing zone,
- updating your landing zone,
- creating an OU using Control Tower,
- deregistering an OU from Control Tower,
- creating and provisioning an account using Account Factory,
- updating an account that was previously created using Account Factory,
- enabling a guardrail on an OU, and
- disabling a guardrail on an OU.
Recording lifecycle events in AWS CloudTrail
Lifecycle events are created internally by Control Tower and recorded in CloudTrail as AWS Service Events (eventType = AwsServiceEvent). You can identify lifecycle events on the CloudTrail Event history page as events that have Source IP address as AWS Internal, and Event source as controltower.amazonaws.com.
Example: Enabling a guardrail on an OU
I log in as the Control Tower Administrator. From the Control Tower dashboard, I create a new OU, called My-Custom-OU, and I then enable a guardrail on the newly created OU.
I go to the CloudTrail console, and I note that CloudTrail recorded two related events, both with the Event name as EnableGuardrail, as seen in the following screenshot.
The first EnableGuardrail event lists my User name and my Source IP address. This event is the record of my action of enabling the guardrail.
The second EnableGuardrail event lists the Source IP address as AWS Internal. This event is the lifecycle event that corresponds to my action of enabling the guardrail.
I view the log entries for both EnableGuardrail events to understand how they are recorded differently by CloudTrail.
In the extract from the log entry of the first EnableGuardrail event, I note that CloudTrail recorded the event type as AwsApiCall, as seen in the following screenshot. This indicates that I, the user, initiated an action that resulted in an AWS API call.
In the extract from the log entry of the second EnableGuardrail event, I note that CloudTrail recorded the event type as AwsServiceEvent, as seen in the following screenshot. This indicates that an AWS service, in this case, Control Tower, created this event, the EnableGuardrail lifecycle event.
The lifecycle event log includes information that is relevant to the originating Control Tower action in the section serviceEventDetails, as seen in the above screenshot. In this example, the lifecycle event log contains the name and ID of the OU, and the name and behavior of the guardrail that I enabled on the OU. The lifecycle event log also contains the state (or result) of the originating action, in this case, whether Control Tower succeeded, or failed, to enable the guardrail.
Example: Creating a new account using Account Factory
I use Control Tower’s Account Factory (via AWS Service Catalog) to create and provision a new account, called my-custom-account-2, and to place it in the OU, My-Custom-OU, that I previously created.
I return to the CloudTrail console to view a subset of the events that it recorded. I see that CloudTrail recorded my action of creating an account using Account Factory with the event name CreateManagedAccount, as seen in the following screenshot.
Over the next few minutes, Control Tower makes numerous API calls to other services to create and provision the new account, my-custom-account-2. Finally, I note that CloudTrail records two lifecycle events, as seen in the above screenshot.
The first lifecycle event, named EnableGuardrail, tells me that Control Tower completed deploying the guardrail that I had previously enabled on My-Custom-OU on the newly created account. The second lifecycle event, named CreateManagedAccount, tells me that Control Tower has completed all actions related to creating and provisioning the new account.
As described, I can use lifecycle events to track if my Control Tower action completed successfully or not.
I can also visit the Activities page on the Control Tower dashboard to view the lifecycle events, as seen in the following screenshot. The Activities page also displays other events that are recorded by CloudTrail as I use and navigate through the Control Tower console.
Triggering automated workflows using Amazon CloudWatch Events
Control Tower actions can take several minutes to complete, based on the type of action and on the number of resources that it has to configure. Lifecycle events mark the completion of Control Tower actions, and they can act as the starting point for the next set of actions that I want to take either on the Control Tower resources or on the results of my previous Control Tower actions.
For example, I can create an account using Account Factory, and then use the corresponding lifecycle event to trigger additional workflows depending on the result of the account creation action. If the lifecycle event reports that the account was created successfully, then I can further provision the account with custom resource configurations. Alternately, if the lifecycle event reports that the account creation did not succeed, I can file a ticket with the IT team to investigate
I can also perform a series of actions that are linked together using lifecycle events. For example, I can create an OU, enable guardrails on the OU, and then create multiple accounts and place them in the newly created OU – all actions linked together using lifecycle events.
To demonstrate how lifecycle events can be used to launch additional, automated workflows, I demonstrate an example where I automatically inform the InfoSec team whenever I use Account Factory to create an account.
Control Tower delivers lifecycle events as events to CloudWatch Events. I can create a CloudWatch Events rule that detects a lifecycle event related to Account Factory, and responds by publishing the lifecycle event log to an Amazon SNS topic.
- I log in as the Control Tower Administrator. From the Amazon SNS console, I create an Amazon SNS topic called
lifecycle-events-sns, and subscribe the InfoSec team to this Amazon SNS topic, as seen in the following screenshot.
- I create an event rule with CloudWatch Events.
- From the CloudWatch Events console, I define the Event Source and the Target.
- For the Event Source, I set the Service Name to Control Tower, and the Event Type to AWS Service Event via CloudTrail. I can create the rule to be triggered by all lifecycle events or by specific lifecycle events. In this example, I create the rule to be triggered by CreateManagedAccount lifecycle events, as seen in the following screenshot.
- I set the Amazon SNS topic that I previously created,
lifecycle-events-sns, as the Target to be invoked when CloudWatch Events detects a CreateManagedAccount lifecycle event, as seen in the following screenshot.
- I’ve now created a CloudWatch Events rule,
CWE-rule-lifecycle-event-account, that detects the Control Tower lifecycle event, CreateManagedAccount, and then publishes the lifecycle event log to the Amazon SNS topic,lifecycle-events-sns, as seen in the following screenshot. Since the InfoSec team’s email address is subscribed to this Amazon SNS topic, they are informed whenever I create a new account using Account Factory.
I return to the Control Tower console. I use Account Factory to create a new account, my-custom-account-3, and to place it in the OU, My-Custom-OU, that I created previously. After a few minutes, the resulting lifecycle event log finds its way to the InfoSec team’s inbox, as seen in the following screenshot.
At this point, the InfoSec team knows that an account was successfully created and provisioned by Control Tower, and they also know the new account’s ID and the OU where it was placed. Since CloudWatch Events supports multiple targets, I can configure the CWE-rule-lifecycle-event-account rule such that it simultaneously launches AWS Lambda or AWS CodePipeline to further provision this newly created account with additional custom resource configurations.
I consider another advantage of using lifecycle events with CloudWatch Events to be the visibility that it gives me into Control Tower actions that may have failed.
To illustrate this point, I create a new OU using Control Tower, My-Custom-OU-3. I configure Account Factory to create a new account, my-custom-account-7, and to place this account in the new OU. I launch the account creation process, but immediately delete My-Custom-OU-3 from the Organizations console so that I can cause the account creation and provisioning process to fail.
Sure enough, a few minutes later, the InfoSec team receives an email informing them that Control Tower was not successful in creating and provisioning the account my-custom-account-7, as shown in the following screenshot. The InfoSec can then investigate why this happened. If the InfoSec team relies solely on the CloudTrail logs of the originating user actions, they cannot know if the subtasks associated with my user action completed successfully, and they cannot respond in a timely and appropriate manner.
Conclusion
In this post, I demonstrated how to use Control Tower’s lifecycle events to track the completion of a Control Tower action, and how to use CloudWatch Events to launch pre-determined actions that are triggered by lifecycle events.
For more details on lifecycle events, visit the AWS Control Tower User Guide.
About the Author
 |
Kalyan Ghatak is a Senior Technical Product Manager on the AWS Control Tower team. Kalyan loves working with AWS customers on solving difficult problems and helping them build on AWS. Outside of work, he enjoys listening to classical music and reading classics. |