Metadata-Version: 2.1
Name: renovosolutions.aws-cdk-aws-organization
Version: 0.3.2
Summary: AWS CDK Construct Library to manage specific AWS Organization resources
Home-page: https://github.com/RenovoSolutions/cdk-library-aws-organization.git
Author: Renovo Solutions<webmaster+cdk@renovo1.com>
License: Apache-2.0
Project-URL: Source, https://github.com/RenovoSolutions/cdk-library-aws-organization.git
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Typing :: Typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# cdk-library-aws-organization

This CDK library is a WIP and not ready for production use.

## Key challenges with Organizations

* Accounts aren't like AWS resources and the [removal process isn't a simple delete](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_remove.html). Therefore the constructs contained in this library do **not** have the goal to delete accounts.
* CloudFormation doesn't support Organizations directly so the constructs in this library use CloudFormation custom resources that utilize Python and [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/organizations.html)

## Testing the custom provider code with SAM CLI

* Create a test project that utilizes this library
* Create a test stack
* Synthesize the test stack with `cdk synth --no-staging > template.yml`
* Get the function name from the template
* Run `sam local start-lambda -t template.yml`
* Run the `handler_tests` python files with `pytest` like follows:

```
LAMBDA_FUNCTION_NAME='<name you noted earlier>' pytest ./handler_tests/<handler>/test.py -rA --capture=sys
```

* The `test.py` also looks up the root org id to run tests so you'll need to have AWS creds set up to accomodate that behavior.
* You can run the provided tests against the real lambda function by getting the deployed function name from AWS and setting the `RUN_LOCALLY` env variable

```
RUN_LOCALLY='false' LAMBDA_FUNCTION_NAME='<name from AWS>' pytest ./handler_tests/<handler>/test.py -rA --capture=sys
```

## Why can't I move an OU?

Moving OUs isn't supported by Organizations and would cause significant issues with keeping track of OUs in the CDK. Imagine a scenario like below:

* You have an ou, `OUAdmin`, and it has 2 children, `OUChild1 and Account1`, that are also managed by the CDK stack.
* You change the parent of `OUAdmin` to `OUFoo`. The CDK would need to take the following actions:

  * Create a new `OU` under `OUFoo` with the name `OUAdmin`
  * Move all of the original `OUAdmin` OU's children to the new `OUAdmin`
  * Delete the old `OUAdmin`
  * Update all physical resource IDs

    * It would succeed at moving accounts because physical IDs should not change. Accounting moving between OUs is supported by Organizations
    * It would fail at moving any child OUs because they would also be recreated. Resulting in a change to physical resource ID. Because the custom resource can only managed the resource it's currently acting on, `OUAdmin`, any children OUs would be "lost" in this process and ugly to try and manage.

The best way to move OUs would be to add additional OUs to your org then move any accounts as needed then proceed to delete the OUs, like so:

* Add new OU resources
* Deploy the stack
* Change account parents
* Deploy the stack
* Remove old OU resources
* Deploy the stack


