{"id":18524533,"url":"https://github.com/stelligent/cumulogenesis","last_synced_at":"2025-04-23T01:55:34.150Z","repository":{"id":53533956,"uuid":"131870005","full_name":"stelligent/cumulogenesis","owner":"stelligent","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-21T20:46:40.000Z","size":138,"stargazers_count":3,"open_issues_count":19,"forks_count":1,"subscribers_count":57,"default_branch":"master","last_synced_at":"2025-04-23T01:55:28.681Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stelligent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-02T15:24:18.000Z","updated_at":"2023-09-29T05:33:08.000Z","dependencies_parsed_at":"2024-12-26T00:35:48.847Z","dependency_job_id":null,"html_url":"https://github.com/stelligent/cumulogenesis","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stelligent%2Fcumulogenesis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stelligent%2Fcumulogenesis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stelligent%2Fcumulogenesis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stelligent%2Fcumulogenesis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stelligent","download_url":"https://codeload.github.com/stelligent/cumulogenesis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250354301,"owners_count":21416751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T17:42:21.058Z","updated_at":"2025-04-23T01:55:34.133Z","avatar_url":"https://github.com/stelligent.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cumulogenesis\n\nThis is a tool that allows an AWS Organization to be described in a YAML format and subsequently deployed. Key features:\n\n- Creation and management of AWS Organizations, Organizational Units, Accounts, and Service Control Policies\n- Dry runs that produce reports that demonstrate the expected and existing Organization states and list the required changes to converge the actual Organization state to the expected state.\n- A simple command line interface for executing bothdry runs and convergence.\n\nIt is implemented in Python 3 and uses [pipenv](https://docs.pipenv.org/) to manage Python virtualenv configuration and dependency management.\n\n## Installation\n\n1. [Install pipenv](https://docs.pipenv.org/#install-pipenv-today). You may need to update your `pipenv` installation as some older versions do not support the `Pipfile` `[scripts]` entrypoints used in the examples below.\n\n2. Clone this repository\n\n3. Install virtualenv and module dependencies\n\n```\ncd cumulogenesis\npipenv install\n```\n\n## Usage\n\n1. Create a configuration that describes the desired state of your organization. See [the examples](examples/).\n\n2. Run the `pipenv run cumulogenesis` wrapper to run the CLI in the `pipenv` created virtualenv.\n\nWhen run without `--converge`, a dry run report will be logged to the console that demonstrates the changes that will be made during convergence. When run with `--converge`, a dry run will be executed and a YAML report will logged to the console, then convergence will be run and a report demonstrating changes that were made will be logged to the console.\n\nThese YAML reports can also be written to the filesystem with the `--dry-run-report-file` and `--converge-report-file` arguments.\n\n```\n$ pipenv run cumulogenesis --help\nusage: cumulogenesis.py [-h] --config-file CONFIG_FILE [--profile PROFILE]\n                        [--converge]\n                        [--dry-run-report-file DRY_RUN_REPORT_FILE]\n                        [--converge-report-file CONVERGE_REPORT_FILE]\n                        [--log-level LOG_LEVEL]\n\nLoads an Organization model from the configuration in the specified YAML file,\nloads the corresponding existing resources from AWS, then executes a\ncomparison dry run and generates a report of the differences. Optionally, it\nwill converge the differences to make the Organization in AWS match what is\nspecified in the configuration when run with the --converge option. Both dry\nrun and converge reports are printed to the console by default. Reports can be\nwritten to the files specified with --dry-run-report-file and --converge-\nreport-file\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --config-file CONFIG_FILE\n                        The path to the YAML file containing the configured\n                        Organization model.\n  --profile PROFILE     The name of the AWS CLI profile to use when\n                        initializing AWS API sessions.\n  --converge            When specified, will attempt to converge differences\n                        between the configured Organization model and the AWS\n                        resources after executing a dry run.\n  --dry-run-report-file DRY_RUN_REPORT_FILE\n                        The path to the file that should contain the dry run\n                        report in addition to being printed to the console.\n  --converge-report-file CONVERGE_REPORT_FILE\n                        The path to the file that should contain the\n                        convergence report in addition to being printed to the\n                        console.\n  --log-level LOG_LEVEL\n                        The console log level to set. Valid values include\n                        DEBUG, INFO, WARNING, ERROR, CRITICAL\n```\n\n## Recommended IAM Policy\n\nRunning Cumulogenesis will require some permissions on your AWS account. Below are the minimum requirements for the full feature set of this software.\n\nSee [the example IAM Policy to use Cumulogenesis](examples/aws/iam-policy.json).\n\n## Opinionated Features\n\n### Account regions\n\n_Opinion:_ Accounts should be used only for a single application or business use case. As a result, there shouldn't be a case where one set of resources is deployed in one region for an account while a separate set of resources is deployed in a different region.\n\nAccounts have `region` parameters, which represent the regions in which resources associated with the account should be provisioned. Resources like Stack Sets will be provisioned against each region for the account, and this cannot be overridden.\n\n### Policies\n\n- When not specified, Orgunit and Account entities will have the `FullAWSAccess` AWS-managed policy attached to them. This policy will be replaced by the user-specified policies if any are specified. If you plan to use deny-only policies, ensure that `FullAWSAccess` is still specified somewhere in the Organization hierarchy.\n\n## Implemented/To Do\n\nSee the [project board](https://github.com/stelligent/cumulogenesis/projects/1).\n\n## Running tests\n\n### Unit/static code/intramodule integration tests\n\n1. Install development dependencies\n\n```\npipenv install --dev\n```\n\n2. Execute tests:\n\n```\npipenv run tests\n```\n\n## Generating Documentation\n\nAuto-generated documentation is provided by [pydoc-markdown](https://github.com/NiklasRosenstein/pydoc-markdown). To build the documentation and run a local webserver to view it:\n\n1. Install development dependencies\n\n```\npipenv install --dev\n```\n\n2. Run the documentation server\n\n```\npipenv run doc-server\n```\n\n3. Visit https://localhost:8000/ in your browser.\n\n## Acknowledgements\n\nHuge thanks to @jedugas and everyone else on the Stelligent team whose previous work informed this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstelligent%2Fcumulogenesis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstelligent%2Fcumulogenesis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstelligent%2Fcumulogenesis/lists"}