AWS API Changes

2023/11/27 - AWS Control Tower - 1 new3 updated api methods

Changes This release adds the following support: 1. The EnableControl API can configure controls that are configurable. 2. The GetEnabledControl API shows the configured parameters on an enabled control. 3. The new UpdateEnabledControl API can change parameters on an enabled control.

UpdateEnabledControl (new)

Link ¶

Updates the configuration of an already enabled control.

If the enabled control shows an EnablementStatus of SUCCEEDED, supply parameters that are different from the currently configured parameters. Otherwise, Amazon Web Services Control Tower will not accept the request.

If the enabled control shows an EnablementStatus of FAILED, Amazon Web Services Control Tower will update the control to match any valid parameters that you supply.

If the DriftSummary status for the control shows as DRIFTED, you cannot call this API. Instead, you can update the control by calling DisableControl and again calling EnableControl, or you can run an extending governance operation. For usage examples, see the Amazon Web Services Control Tower User Guide

See also: AWS API Documentation

Request Syntax

client.update_enabled_control(
    enabledControlIdentifier='string',
    parameters=[
        {
            'key': 'string',
            'value': {...}|[...]|123|123.4|'string'|True|None
        },
    ]
)

type enabledControlIdentifier:

string

param enabledControlIdentifier:

[REQUIRED]

The ARN of the enabled control that will be updated.

type parameters:

list

param parameters:

[REQUIRED]

A key/value pair, where Key is of type String and Value is of type Document.

(dict) --

A set of parameters that configure the behavior of the enabled control. A key/value pair, where Key is of type String and Value is of type Document.
- key (string) -- [REQUIRED]
  
  The key of a key/value pair. It is of type string.
- value (:ref:`document<document>`) -- [REQUIRED]
  
  The value of a key/value pair. It can be of type array string, number, object, or boolean.

rtype:

dict

returns:

Response Syntax

{
    'operationIdentifier': 'string'
}

Response Structure

(dict) --
- operationIdentifier (string) --
  
  The operation identifier for this UpdateEnabledControl operation.

EnableControl (updated)

Link ¶
Changes (request)

{'parameters': [{'key': 'string', 'value': {}}]}

This API call activates a control. It starts an asynchronous operation that creates Amazon Web Services resources on the specified organizational unit and the accounts it contains. The resources created will vary according to the control that you specify. For usage examples, see the Amazon Web Services Control Tower User Guide.

See also: AWS API Documentation

Request Syntax

client.enable_control(
    controlIdentifier='string',
    parameters=[
        {
            'key': 'string',
            'value': {...}|[...]|123|123.4|'string'|True|None
        },
    ],
    tags={
        'string': 'string'
    },
    targetIdentifier='string'
)

type controlIdentifier:

string

param controlIdentifier:

[REQUIRED]

The ARN of the control. Only Strongly recommended and Elective controls are permitted, with the exception of the landing zone Region deny control. For information on how to find the controlIdentifier, see the overview page.

type parameters:

list

param parameters:

An array of EnabledControlParameter objects

(dict) --

A set of parameters that configure the behavior of the enabled control. A key/value pair, where Key is of type String and Value is of type Document.
- key (string) -- [REQUIRED]
  
  The key of a key/value pair. It is of type string.
- value (:ref:`document<document>`) -- [REQUIRED]
  
  The value of a key/value pair. It can be of type array string, number, object, or boolean.

type tags:

dict

param tags:

Tags to be applied to the EnabledControl resource.

(string) --
- (string) --

type targetIdentifier:

string

param targetIdentifier:

[REQUIRED]

The ARN of the organizational unit. For information on how to find the targetIdentifier, see the overview page.

rtype:

dict

returns:

Response Syntax

{
    'arn': 'string',
    'operationIdentifier': 'string'
}

Response Structure

(dict) --
- arn (string) --
  
  The ARN of the EnabledControl resource.
- operationIdentifier (string) --
  
  The ID of the asynchronous operation, which is used to track status. The operation is available for 90 days.

GetControlOperation (updated)

Link ¶
Changes (response)

{'controlOperation': {'operationType': {'UPDATE_ENABLED_CONTROL'}}}

Returns the status of a particular EnableControl or DisableControl operation. Displays a message in case of error. Details for an operation are available for 90 days. For usage examples, see the Amazon Web Services Control Tower User Guide.

See also: AWS API Documentation

Request Syntax

client.get_control_operation(
    operationIdentifier='string'
)

type operationIdentifier:

string

param operationIdentifier:

[REQUIRED]

The ID of the asynchronous operation, which is used to track status. The operation is available for 90 days.

rtype:

dict

returns:

Response Syntax

{
    'controlOperation': {
        'endTime': datetime(2015, 1, 1),
        'operationType': 'ENABLE_CONTROL'|'DISABLE_CONTROL'|'UPDATE_ENABLED_CONTROL',
        'startTime': datetime(2015, 1, 1),
        'status': 'SUCCEEDED'|'FAILED'|'IN_PROGRESS',
        'statusMessage': 'string'
    }
}

Response Structure

(dict) --
- controlOperation (dict) --
  
  An operation performed by the control.
  - endTime (datetime) --
    
    The time that the operation finished.
  - operationType (string) --
    
    One of ENABLE_CONTROL or DISABLE_CONTROL.
  - startTime (datetime) --
    
    The time that the operation began.
  - status (string) --
    
    One of IN_PROGRESS, SUCEEDED, or FAILED.
  - statusMessage (string) --
    
    If the operation result is FAILED, this string contains a message explaining why the operation failed.

GetEnabledControl (updated)

Link ¶
Changes (response)

{'enabledControlDetails': {'parameters': [{'key': 'string', 'value': {}}]}}

Retrieves details about an enabled control. For usage examples, see the Amazon Web Services Control Tower User Guide.

See also: AWS API Documentation

Request Syntax

client.get_enabled_control(
    enabledControlIdentifier='string'
)

type enabledControlIdentifier:

string

param enabledControlIdentifier:

[REQUIRED]

The controlIdentifier of the enabled control.

rtype:

dict

returns:

Response Syntax

{
    'enabledControlDetails': {
        'arn': 'string',
        'controlIdentifier': 'string',
        'driftStatusSummary': {
            'driftStatus': 'DRIFTED'|'IN_SYNC'|'NOT_CHECKING'|'UNKNOWN'
        },
        'parameters': [
            {
                'key': 'string',
                'value': {...}|[...]|123|123.4|'string'|True|None
            },
        ],
        'statusSummary': {
            'lastOperationIdentifier': 'string',
            'status': 'SUCCEEDED'|'FAILED'|'UNDER_CHANGE'
        },
        'targetIdentifier': 'string',
        'targetRegions': [
            {
                'name': 'string'
            },
        ]
    }
}

Response Structure

(dict) --
- enabledControlDetails (dict) --
  
  Information about the enabled control.
  - arn (string) --
    
    The ARN of the enabled control.
  - controlIdentifier (string) --
    
    The control identifier of the enabled control. For information on how to find the controlIdentifier, see the overview page.
  - driftStatusSummary (dict) --
    
    The drift status of the enabled control.
    - driftStatus (string) --
      
      The drift status of the enabled control.
      
      Valid values:
      - DRIFTED: The enabledControl deployed in this configuration doesn’t match the configuration that Amazon Web Services Control Tower expected.
      - IN_SYNC: The enabledControl deployed in this configuration matches the configuration that Amazon Web Services Control Tower expected.
      - NOT_CHECKING: Amazon Web Services Control Tower does not check drift for this enabled control. Drift is not supported for the control type.
      - UNKNOWN: Amazon Web Services Control Tower is not able to check the drift status for the enabled control.
  - parameters (list) --
    
    Array of EnabledControlParameter objects.
    - (dict) --
      
      Returns a summary of information about the parameters of an enabled control.
      - key (string) --
        
        The key of a key/value pair.
      - value (:ref:`document<document>`) --
        
        The value of a key/value pair.
  - statusSummary (dict) --
    
    The deployment summary of the enabled control.
    - lastOperationIdentifier (string) --
      
      The last operation identifier for the enabled control.
    - status (string) --
      
      The deployment status of the enabled control.
      
      Valid values:
      - SUCCEEDED: The enabledControl configuration was deployed successfully.
      - UNDER_CHANGE: The enabledControl configuration is changing.
      - FAILED: The enabledControl configuration failed to deploy.
  - targetIdentifier (string) --
    
    The ARN of the organizational unit. For information on how to find the targetIdentifier, see the overview page.
  - targetRegions (list) --
    
    Target Amazon Web Services Regions for the enabled control.
    - (dict) --
      
      An Amazon Web Services Region in which Amazon Web Services Control Tower expects to find the control deployed.
      
      The expected Regions are based on the Regions that are governed by the landing zone. In certain cases, a control is not actually enabled in the Region as expected, such as during drift, or mixed governance.
      - name (string) --
        
        The Amazon Web Services Region name.