existing-orgs.md

1. Existing Organizations / Accounts

1.1. Considerations: Importing existing AWS Accounts / Deploying Into Existing AWS Organizations

• The Accelerator can be installed into existing AWS Organizations
  • our early adopters have all successfully deployed into existing organizations
• Existing AWS accounts can also be imported into an Accelerator managed Organization
• Caveats:
  • Per AWS Best Practices, the Accelerator deletes the default VPC's in all AWS accounts, worldwide. The inability to delete default VPC's in pre-existing accounts will fail the installation/account import process. Ensure default VPC's can or are deleted before importing existing accounts. On failure, either rectify the situation, or remove the account from Accelerator management and rerun the state machine
  • The Accelerator will NOT alter existing (legacy) constructs (e.g. VPC's, EBS volumes, etc.). For imported and pre-existing accounts, objects the Accelerator prevents from being created using preventative guardrails will continue to exist and not conform to the prescriptive security guidance
    • Existing workloads should be migrated to Accelerator managed VPC's and legacy VPC's deleted to gain the full governance benefits of the Accelerator (centralized flow logging, centralized ingress/egress, no IGW's, Session Manager access, existing non-encrypted EBS volumes, etc.)
  • Existing AWS services will be reconfigured as defined in the Accelerator configuration file (overwriting existing settings)
  • We do NOT support any workloads running or users operating in the Organization Management (root) AWS account. The Organization Management (root) AWS account MUST be tightly controlled
  • Importing existing workload accounts is fully supported, we do NOT support, recommend and strongly discourage importing mandatory accounts, unless they were clean/empty accounts. Mandatory accounts are critical to ensuring governance across the entire solution
  • We've tried to ensure all customer deployments are smooth. Given the breadth and depth of the AWS service offerings and the flexibility in the available deployment options, there may be scenarios that cause deployments into existing Organizations to initially fail. In these situations, simply rectify the conflict and re-run the state machine.
  • If the Firewall Manager administrative account is already set for your organization, it needs to be unset before starting a deployment.

1.2. Process to import existing AWS accounts into an Accelerator managed Organization

• Newly invited AWS accounts in an Organization will land in the root ou
• Unlike newly created AWS accounts which immediately have a Deny-All SCP applied, imported accounts are not locked down as we do not want to break existing workloads (these account are already running without Accelerator guardrails)
• In AWS Organizations, select ALL the newly invited AWS accounts and move them all (preferably at once) to the correct destination OU (assuming the same OU for all accounts)
  • In case you need to move accounts to multiple OU's we have added a 2 minute delay before triggering the State Machine
  • Any accounts moved after the 2 minute window will NOT be properly ingested, and will need to be ingested on a subsequent State Machine Execution
• This will first trigger an automated update to the config file and then trigger the state machine after a 2 minute delay, automatically importing the moved accounts into the Accelerator per the destination OU configuration
• As previously documented, accounts CANNOT be moved between OU's to maintain compliance, so select the proper top-level OU with care
• If you need to customize each of the accounts configurations, you can manually update the configuration file either before or after you move the account to the correct ou
  • if before, you also need to include the standard 4 account config file parameters, if after, you can simply add your new custom parameters to the account entry the Accelerator creates
  • if you add your imported accounts to the config file, moving the first account to the correct ou will trigger the state machine after a 2 minutes delay. If you don't move all accounts to their correct ou's within 2 minutes, your state machine will fail. Simply finish moving all accounts to their correct OU's and then rerun the state machine.
• If additional accounts are moved into OUs while the state machine is executing, they will not trigger another state machine execution, those accounts will only be ingested on the next execution of the state machine
  • customers can either manually initiate the state machine once the current execution completes, or, the currently running state machine can be stopped and restarted to capture all changes at once
  • Are you unsure if an account had its guardrails applied? The message sent to the state machine Status SNS topic (and corresponding email address) on a successful state machine execution provides a list of all successfully processed accounts.
• The state machine is both highly parallel and highly resilient, stopping the state machine should not have any negative impact. Importing 1 or 10 accounts generally takes about the same amount of time for the Accelerator to process, so it may be worth stopping the current execution and rerunning to capture all changes in a single execution.
• We have added a 2 min delay before triggering the state machine, allowing customers to make multiple changes within a short timeframe and have them all captured automatically in the same state machine execution.

1.3. Deploying the Accelerator into an existing Organization

• As stated above, if the ALZ was previously deployed into the Organization, please work with your AWS account team to find the best mechanism to uninstall the ALZ solution
• Ensure all existing sub-accounts have the role name defined in organization-admin-role installed and set to trust the Organization Management (root) AWS Organization account
  • prior to v1.2.5, this role must be named: AWSCloudFormationStackSetExecutionRole
  • if using the default role (AWSCloudFormationStackSetExecutionRole) we have provided a CloudFormation stack which can be executed in each sub-account to simplify this process
• As stated above, we recommend starting with new AWS accounts for the mandatory functions (shared-network, perimeter, security, log-archive accounts).
• To better ensure a clean initial deployment, we also recommend the installation be completed while ignoring most of your existing AWS sub-accounts, importing them post installation:
  • create a new OU (i.e. Imported-Accounts), placing most of the existing accounts into this OU temporarily, and adding this OU name to the global-options\ignored-ous config parameter;
  • any remaining accounts must be in the correct ou, per the Accelerator config file;
  • install the Accelerator;
  • import the skipped accounts into the Accelerator using the above import process, paying attention to the below notes
• NOTES:
  • Do NOT move any accounts from any ignored-ous to the root ou, they will immediately be quarantined with a Deny-All SCP, they need to be moved directly to their destination ou
  • As stated above, when importing accounts, there may be situations we are not able to fully handle
    • If doing a mass import, we suggest you take a quick look and if the solution is not immediately obvious, move the account which caused the failure back to ignored-ous and continue importing the remainder of your accounts. Once you have the majority imported, you can circle back and import outstanding problem accounts with the ability to focus on each individual issue
    • The challenge could be as simple as someone has instances running in a default VPC, which may require some cleanup effort before we can import (coming soon, you will be able to exclude single account/region combinations from default VPC deletion to gain the benefits of the rest of the guardrails while you migrate workloads out of the default VPC)