awsapilib.controltower package¶

Subpackages¶

awsapilib.controltower.resources package

Submodules¶

awsapilib.controltower.controltower module¶

Main code for controltower.

class awsapilib.controltower.controltower.ControlTower(arn, settling_time=90, region=None)[source]¶

Bases: LoggerMixin

Models Control Tower by wrapping around service catalog.

property accounts¶

The accounts under control tower.

Returns:: A list of account objects under control tower’s control.
Return type:: accounts (Account)

property active_artifact_id: str¶

Contains the id of the active artifact.

Returns:: str with the artifact id or an empty string

api_content_type = 'application/x-amz-json-1.1'¶

api_user_agent = 'aws-sdk-js/2.528.0 promise'¶

property baseline_update_available¶: Baseline update available.

property busy¶: Busy.

property catastrophic_drift¶: List of catastrophic drift.

core_account_types = ['PRIMARY', 'LOGGING', 'SECURITY']¶

property core_accounts¶

The core accounts of the landing zone.

Returns:: A list of the primary, logging and security account.
Return type:: core_accounts (list)

create_account(account_name: str, account_email: str, organizational_unit: str, parent_hierarchy: list = None, product_name: str = None, sso_first_name: str = None, sso_last_name: str = None, sso_user_email: str = None, force_parent_hierarchy_creation=False) → bool[source]¶

Creates a Control Tower managed account.

Parameters:

account_name (str) – The name of the account.
account_email (str) – The email of the account.
organizational_unit (str) – The organizational unit that the account should be under.
parent_hierarchy (list) – The hierarchy under where the OU needs to be placed. Defaults to Root.
product_name (str) – The product name, if nothing is provided it uses the account name.
sso_first_name (str) – The first name of the SSO user, defaults to “Control”
sso_last_name (str) – The last name of the SSO user, defaults to “Tower”
sso_user_email (str) – The email of the sso, if nothing is provided it uses the account email.
force_parent_hierarchy_creation (bool) – Forces the creation of missing OUs in the provided hierarchy.

Returns:

True on success, False otherwise.

Return type:

result (bool)

Raises:

NonExistentOU – If the parent hierarchy provided does not exist and force is not provided as a flag.
InvalidParentHierarchy – If the parent hierarchy provided is invalid and force is not provided as a flag.
EmailInUse – If email provided is already used in AWS.

create_organizational_unit(name: str, parent_hierarchy=None, force_create=False) → bool[source]¶

Creates a Control Tower managed organizational unit.

Parameters:

name (str) – The name of the OU to create.
parent_hierarchy (list) – The list of the parent hierarchy path.
force_create (bool) – Forces the creation of the hierarchy if parents are missing.

Returns:

True if successful, False otherwise.

Return type:

result (bool)

Raises:

InvalidParentHierarchy – If the hierarchy provided is longer that 5 levels.
NonExistentOU – If there is an OU missing in the hierarchy and force_create is not set.

decommission() → bool[source]¶

Decommissions a landing zone.

The api call does not seem to be enough and although the resources are decommissioned like with the proper process, control tower responds with a delete failed on the api, so it seems that aws needs to perform actions on their end for the decommissioning to be successful.

Returns:: True if the process starts successfully, False otherwise.
Return type:: response (bool)

delete_organizational_unit(name: str, parent_hierarchy=None) → bool[source]¶

Deletes a Control Tower managed organizational unit.

Parameters:

name (str) – The name of the OU to delete.
parent_hierarchy (list) – A list of names of the hierarchy for a parent starting with ‘Root’

Returns:

True if successful, False otherwise.

Return type:

result (bool)

Raises:

NonExistentOU – If an OU does not exist in the hierarchy.

deploy(logging_account_email: str, security_account_email: str, logging_account_name: str = 'Log Archive', security_account_name: str = 'Audit', core_ou_name: str = 'Security', custom_ou_name: str = 'Sandbox', regions: Optional[list] = None, retries: int = 10, wait: int = 1) → bool[source]¶

Deploys control tower.

Returns:: True on success, False on failure.
Return type:: bool

property deploying_messages¶: Deploying messages.

property drift_messages¶: Drift messages.

property enabled_guard_rails¶: Enabled guard rails.

get_account_by_arn(arn)[source]¶

Retrieves an account by arn.

Returns:: An account object that matches the arn or None.
Return type:: account (Account)

get_account_by_email(email)[source]¶

Retrieves an account by email.

Returns:: An account object that matches the email or None.
Return type:: account (Account)

get_account_by_id(id_)[source]¶

Retrieves an account by id.

Returns:: An account object that matches the id or None.
Return type:: account (Account)

get_account_by_name(name)[source]¶

Retrieves an account by name.

Returns:: An account object that matches the name or None.
Return type:: account (Account)

get_accounts_with_available_updates()[source]¶

Retrieves the accounts that have available updates from control tower.

Returns:: A list of account objects under control tower’s control with available updates.
Return type:: accounts (Account)

get_available_accounts()[source]¶

Retrieves the available accounts from control tower.

Returns:: A list of available account objects under control tower’s control.
Return type:: accounts (Account)

static get_available_regions()[source]¶

The regions that control tower can be active in.

Returns:: A list of strings of the regions that control tower can be active in.
Return type:: regions (list)

get_changing_accounts()[source]¶

Retrieves the under change accounts from control tower.

Returns:: A list of under change account objects under control tower’s control.
Return type:: accounts (Account)

get_erroring_accounts()[source]¶

Retrieves the erroring accounts from control tower.

Returns:: A list of erroring account objects under control tower’s control.
Return type:: accounts (Account)

get_organizational_unit_by_id(id_)[source]¶

Gets a Control Tower managed Organizational Unit by id.

Parameters:: id (str) – The id of the organizational unit to retrieve.
Returns:: A OU object on success, None otherwise.
Return type:: result (ControlTowerOU)

get_organizational_unit_by_name(name, parent_hierarchy=None)[source]¶

Gets a Control Tower managed Organizational Unit by name.

Parameters:

name (str) – The name of the organizational unit to retrieve.
parent_hierarchy (list) – A list of names of the hierarchy for a parent starting with ‘Root’

Returns:

A OU object on success, None otherwise.

Return type:

result (ControlTowerOU)

Raises:

NonExistentOU – If an OU does not exist in the hierarchy.

get_organizations_ou_by_arn(arn)[source]¶

Gets an Organizations managed Organizational Unit by arn.

Parameters:: arn (str) – The arn of the organizational unit to retrieve.
Returns:: A OU object on success, None otherwise.
Return type:: result (OrganizationsOU)

get_organizations_ou_by_id(id_)[source]¶

Gets an Organizations managed Organizational Unit by id.

Parameters:: id (str) – The id of the organizational unit to retrieve.
Returns:: A OU object on success, None otherwise.
Return type:: result (OrganizationsOU)

get_organizations_ou_by_name(name, parent_hierarchy=None)[source]¶

Gets an Organizations managed Organizational Unit by name.

Parameters:

name (str) – The name of the organizational unit to retrieve.
parent_hierarchy (list) – A list of names of the hierarchy for a parent starting with ‘Root’

Returns:

A OU object on success, None otherwise.

Return type:

result (OrganizationsOU)

get_service_control_policy_by_name(name)[source]¶

Retrieves a service control policy by name.

Parameters:: name (str) – The name of the SCP to retrieve
Returns:: The scp if a match is found else None.
Return type:: scp (ServiceControlPolicy)

get_updated_accounts()[source]¶

Retrieves the accounts that have no available updates from control tower.

Returns:: A list of account objects under control tower’s control with no available updates.
Return type:: accounts (Account)

property governed_regions¶: Governed regions.

property guard_rails¶: Guard rails.

property guard_rails_violations¶: List guard rails violations.

property guardrail_update_available¶: Guardrail update available.

property is_deployed¶: The deployment status of control tower.

is_email_used(email)[source]¶: Check email for availability to be used or if it is already in use.

property landing_zone_update_available¶: Landing Zone update available.

property landing_zone_version¶: Landing zone version.

property not_governed_regions¶: Not governed regions.

property organizational_units¶

The organizational units under control tower.

Returns:: A list of organizational units objects under control tower’s control.
Return type:: organizational_units (OrganizationalUnit)

property organizations_ous¶

The organizational units under Organizations.

Returns:: A list of organizational units objects under Organizations.
Return type:: organizational_units (OrganizationsOU)

property percentage_complete¶: Percentage complete.

property region¶: Region.

property region_metadata_list¶: Region metadata list.

register_organizations_ou(name: str, parent_hierarchy=None, force: bool = False) → bool[source]¶

Registers an Organizations OU under control tower.

Parameters:

name (str) – The name of the Organizations OU to register to Control Tower.
force (bool) – Forces re-registering if the OU is already controlled by Control Tower

Returns:

True if successful, False otherwise.

Return type:

result (bool)

repair()[source]¶

Repairs control tower.

Returns:: True on success, False on failure.
Return type:: bool

property root_ou¶

The root ou of control tower.

Returns:: The root ou object.
Return type:: root_ou (ControlTowerOU)

property service_control_policies¶

The service control policies under organization.

Returns:: A list of SCPs under the organization.
Return type:: service_control_policies (list)

property service_landing_zone_version¶: Service landing zone version.

property status¶: Status.

supported_targets = ['ListManagedOrganizationalUnits', 'ManageOrganizationalUnit', 'DeregisterOrganizationalUnit', 'ListManagedAccounts', 'DescribeManagedOrganizationalUnit', 'ListGuardrailsForTarget', 'GetAvailableUpdates', 'DescribeCoreService', 'GetAccountInfo', 'ListEnabledGuardrails', 'ListGuardrails', 'ListOrganizationalUnitsForParent', 'ListDriftDetails', 'GetLandingZoneStatus', 'SetupLandingZone', 'GetHomeRegion', 'ListGuardrailViolations', 'GetCatastrophicDrift', 'GetGuardrailComplianceStatus', 'DescribeAccountFactoryConfig', 'PerformPreLaunchChecks', 'DeleteLandingZone']¶

update()[source]¶

Updates the control tower to the next available version.

Returns:: True on success, False on failure.
Return type:: bool

property user_landing_zone_version¶: User landing zone version.

validate_availability()[source]¶: Validation decorator.

awsapilib.controltower.controltowerexceptions module¶

Custom exception code for controltower.

exception awsapilib.controltower.controltowerexceptions.ControlTowerBusy[source]¶

Bases: Exception

The control tower is already executing some action.

exception awsapilib.controltower.controltowerexceptions.ControlTowerNotDeployed[source]¶

Bases: Exception

The control tower is deployed at all.

exception awsapilib.controltower.controltowerexceptions.EmailCheckFailed[source]¶

Bases: Exception

Checking of the email was not possible.

exception awsapilib.controltower.controltowerexceptions.EmailInUse[source]¶

Bases: Exception

The email provided is already in use and cannot be used to deploy an account.

exception awsapilib.controltower.controltowerexceptions.InvalidParentHierarchy[source]¶

Bases: Exception

The parent hierarchy provided is not valid.

exception awsapilib.controltower.controltowerexceptions.NoActiveArtifactRetrieved[source]¶

Bases: Exception

Could not retrieve an active artifact.

exception awsapilib.controltower.controltowerexceptions.NoServiceCatalogAccess[source]¶

Bases: Exception

There is no access to service catalog.

exception awsapilib.controltower.controltowerexceptions.NoSuspendedOU[source]¶

Bases: Exception

The suspended ou has not been created.

exception awsapilib.controltower.controltowerexceptions.NonExistentOU[source]¶

Bases: Exception

The OU name provided does not exist in Control Tower.

exception awsapilib.controltower.controltowerexceptions.NonExistentSCP[source]¶

Bases: Exception

The SCP requested does not exist.

exception awsapilib.controltower.controltowerexceptions.OUCreating[source]¶

Bases: Exception

The organizational unit is still under creation and cannot be used.

exception awsapilib.controltower.controltowerexceptions.PreDeployValidationFailed[source]¶

Bases: Exception

The pre deployment validation failed.

exception awsapilib.controltower.controltowerexceptions.RoleCreationFailure[source]¶

Bases: Exception

Unable to create the required roles for the deployment of control tower, manual clean up is required.

exception awsapilib.controltower.controltowerexceptions.ServiceCallFailed[source]¶

Bases: Exception

The call to the service has failed.

exception awsapilib.controltower.controltowerexceptions.UnavailableRegion[source]¶

Bases: Exception

The region or regions provided to control tower to deploy in are not available.

exception awsapilib.controltower.controltowerexceptions.UnsupportedTarget[source]¶

Bases: Exception

The target call is not supported by the current implementation.

Module contents¶

controltower module.

Import all parts from controltower here