AWS Control Tower releases API, pre-defined controls to your organizational units

AWS Control Tower offers a direct way to set up and govern an AWS multi-account environment following prescriptive guidance and best practices. It orchestrates the capabilities of several other AWS services, including AWS Organizations, AWS Service Catalog, and AWS IAM Identity Center (successor to AWS Single Sign-On), to build a landing zone in less than an hour. Resources are set up and managed on your behalf.

Today we’re announcing the general availability of Control Tower API to manage pre-defined controls. Customers can now programmatically enable, disable, and list enabled AWS Control Tower controls (guardrails) across their organizational units (OU) at scale. These controls can be managed via AWS CloudFormation, AWS Command Line Interface (AWS CLI), AWS SDK, and AWS Cloud Development Kit (AWS CDK) to allow more efficient deployment and management of controls as infrastructure as code (IaC).
Four control APIs are now available for all AWS Control Tower customers without any requirement to update AWS Control Tower Landing Zone to the latest version.

In this post, we’ll show you how you can rely on AWS CLI and CloudFormation to perform operations of the newly released APIs.

Prerequisites

To be able to perform the desired operation on specific controls and OU, you’ll need the following:

User Access: Make sure that the user you’re using has enough admin privileges to perform the right actions. Otherwise, make sure that the new AWS Identity and Access Management (IAM) actions of the new APIs are associated with your user: controltower:EnableControl, controltower:DisableControl, controltower:GetControlOperation, and controltower:ListEnabledControls.
Required parameter for API calls:

ControlARN for the control (guardrails): The ControlARN contains the control name which is specified in each guardrail. For a list of control names for Strongly recommended and Elective guardrails, see list here
```
Note that Only Strongly recommended and Elective control are permitted
(Except Region Deny control which is managed via the console Landing
Zone settings). Operations on Mandatory Controls is not allowed.
```
ARN of the target Organizational unit (OU): This is possible either via the console on the Organization or via AWS CLI. It should be something like:

arn:aws:organizations::123456789:ou/o-abc1234xyz/ou-abc-xyz

The latest AWS CLI is installed and configured.

For our scenario, we’ve chosen to perform operations on the control: “AWS-GR_EC2_INSTANCE_NO_PUBLIC_IP” on the desired OU. First, we’ll enable the desired control and check out the status of the operation. Then, we’ll list all of the enabled control of an OU, and re-check that the control is well enabled. At the end, we’ll disable the control.

Enable a control

enable-control: This lets you activate a control in an OU. It starts an asynchronous operation that creates AWS resources on the specified OU and the accounts it contains. The resources created will vary according to the control that you specify.

It accepts two parameter inputs:

–control-identifier : The ARN of the control. Only Strongly recommended and Elective controls are permitted, with the exception of the Region deny guardrail.
–target-identifier: The ARN of the OU.

aws controltower enable-control --control-identifier arn:aws:controltower:eu-central-1::control/AWS-GR_EC2_INSTANCE_NO_PUBLIC_IP --target-identifier arn:aws:organizations::123456789:ou/o-abc1234xyz/ou-abc-xyz

The output of this command will be an operation identifier which lets you track the status of the control enablement progress within the OU.

{
"operationIdentifier": "abcd1234-abcd1234-abcd1234-abcd1234-abcd1234"
}

Get control operation

get-control-operation: Returns the status of a particular EnableControl or DisableControl operation. Details for an operation are available for 90 days. Let’s track the status of the previous command.

aws controltower get-control-operation --operation-identifier abcd1234-abcd1234-abcd1234-abcd1234-abcd1234

The output of the control operation will show information related to the start time and end time of the operation, including the status which could be one of: IN_PROGRESS, SUCCEEDED, FAILED. If the operations is FAILED, then the status message will contain an explanation as to why the operation has failed.

Figure 1. Control operation in progres.

Figure 2. Control operation succeeded

The operation can also be checked directly within the AWS Control Tower console, or the AWS CloudTrail event history.

List enabled controls

list-enabled-controls: Lists the controls enabled by AWS Control Tower on the specified OU and the accounts that it contains.

aws controltower list-enabled-controls --target-identifier arn:aws:organizations::123456789:ou/o-abc1234xyz/ou-abc-xyz

The results of this command will output the list of controls enabled in the specified OU. As the command might return a large list of items, the list is paginated and you can use next token to paginate to the next page.

Disable a control

disable-control: This API call turns off a control. It starts an asynchronous operation that deletes AWS resources on the specified OU and the accounts that it contains. This command accepts the same parameter as enable-control and outputs an operation identifier to track the operation status.

aws controltower disable-control --control-identifier arn:aws:controltower:eu-central-1::control/AWS-GR_EC2_INSTANCE_NO_PUBLIC_IP --target-identifier arn:aws:organizations::123456789:ou/o-abc1234xyz/ou-abc-xyz

CloudFormation template

In this CloudFormation example template, we’re enabling a detective and preventive control within an AWS Control Tower OU. You can create a CloudFormation stack either via the console or AWS CLI.

AWSTemplateFormatVersion: 2010-09-09

Resources:
  DetectiveControl:
    Type: AWS::ControlTower::EnabledControl
    Properties:
      ControlIdentifier: !Sub 'arn:${AWS::Partition}:controltower:${AWS::Region}::control/AWS-GR_EC2_INSTANCE_NO_PUBLIC_IP'
      TargetIdentifier: arn:aws:organizations::123456789:ou/o-abc1234xyz/ou-abc-xyz
  PreventativeControl:
    Type: AWS::ControlTower::EnabledControl
    Properties:
      ControlIdentifier: !Sub 'arn:${AWS::Partition}:controltower:${AWS::Region}::control/AWS-GR_AUDIT_BUCKET_POLICY_CHANGES_PROHIBITED'
      TargetIdentifier: arn:aws:organizations::123456789:ou/o-abc1234xyz/ou-abc-xyz

Updating the stack with newer controls will result in an update, and AWS Control Tower will enable the new controls on the desired OU. If you would like to disable the controls, then you must delete the stack, which will disable all of the controls defined within your template.

Note that a limit of 10 concurrent control operations are allowed simultaneously.

Conclusion

You can use AWS Control Tower API in all supported regions that allows you to programmatically manage the controls on your OU; check out the API page for more information.

About the author:

AWS Cloud Operations & Migrations Blog