This repository will help you automate the deployment, management and tracking of AWS Service Control Policies (SCPs) through a CI/CD pipeline across an organization’s multi-account environment.
.
├── app.py # <-- the "main" for this pipeline code deployment.
├── cdk.json # <-- configuration file for CDK that defines what executable CDK should run to generate the CDK construct tree.
├── config.yaml # <-- defines optional extensions of the core solution.
├── requirements.txt # <-- defines the list of packages or libraries needed for this deployment to work.
├── SCP_Management_Pipeline
├── README.md # <-- defines the list of AWS resources created by CDK for managing this SCP management pipeline
├── SCP_Management_Pipeline.py # <-- sets up the main resources required for the SCP pipeline solution.
├── devtools.py # <-- sets up the development and deployment tools.
├── pipeline.py # <-- the main code that defines all the AWS resources created for building the CI/CD pipeline for SCP creation and management
├── lambda_function # <-- contains the lambda function that triggers the SCP management pipeline everytime a change is made in the source code repository of SCPs.
├── terraformbuild_buildspec.yaml # <--
├── access_analyzer_checks_buildspec.yaml # <--
├── terraform_apply_buildspec.yaml # <--
├── pipeline.py # <-- defines the CI/CD pipeline stages and how the application is built and deployed.
├── source_code
├── README.md # <-- defines how to deploy the SCPs through your chosen pipeline or directly into your AWS organization
├── scp_define_attach.tf # <-- the main code that defines the SCPs to be created along with its necessary configurations for creation in an AWS organization environment.
├── variables.tf # <-- variable definition file
├── terraform.tfvars # <-- pass values to variables before execution through this file
├── providers.tf # <-- defines which Terraform plugin to use and how to authenticate with the cloud provider (in this case - AWS)
├── backend.tf # <-- defines where the state file of the current infrastructure will be stored
├── service_control_policies # <-- a directory with sub-directories specific to the OUs to which SCPs are directly attached
├── Root # <-- all SCP policies to be attached directly to Root
├── InfrastructureOU # <-- all SCP policies to be attached directly to Infrastructure OU
├── MultiOUs # <-- all SCP policies to be attached directly to the list of multiple OUs.
├── scp_module # <-- code for creating an SCP and attaching it to defined targets
├── find_blocking_scps # <-- code to identify which existing SCPs are denying your actions
├── List-of-SCPs.md # <-- A file containing overview of all the SCPs enabled through this repository.
└── README.md # <-- This fileBefore getting started,
- Create a pre-configured Amazon SNS topic with atleast one verified subscriber.
- This SNS topic is needed for notifying the reviewer for any change in the SCP management via email notification.
- As an email subscriber for SNS topic need manual verification hence for the ease of deployment this step is requested as a pre-requisite for this solution
- You can customize this notification step as per your organization requirement and also include it in the pipeline deployment code.
- AWS Organizations must be enabled with multiple organization units (OUs).
- This solution is applicable only for those AWS environment which has a multi-account environment divided into multiple OUs
Basic understating of the following can help as this solution uses:
- Python and Boto3.
- CDK environments.
- Getting started with Terraform for AWS
- Terraform: Beyond the Basics with AWS
- The terraform.tfvars file contains the value for all the SCP targets to which the SCPs are planned to be attached. Before deploying the code replace the value of each SCP target variable with the appropriate values of your AWS organization.
- The pipeline.py file contains all the AWS resources to be created for the SCP pipeline. and , which are created for storing and locking the Terraform state files respectively.
- Edit the name of the S3 bucket (cdk resource - 'tfstate-backend-bucket'). Replace the value of bucket_name with a S3 bucket name that you want to create in your organization where the terraform state files will be stored
- Edit the name of DynamboDB table(cdk resource - 'tfstate-lock-table'). Replace the value of table_name with a DynamoDB table name that you want to create in your organization where the terraform state files will be locked
- The backend.tf file where the value of the S3 bucket and DynamboDB table used for storing and locking the Terraform state files respectively are passed to Terraform. Provide the same names as used in the pipeline.py.
-
Use the following command to download this Cloud Development Kit (CDK) project in your environment.
git clone https://github.com/aws-samples/scp-management-reference-architecture -
Create a virtual Python environment to contain the project dependencies by using the following command.
python3 -m venv .venv -
Activate the virtual environment with the following command.
source .venv/bin/activate -
Install the project requirements by using the following command.
pip install -r requirements.txt -
Use the following command to update the CDK CLI to the latest major version.
npm install -g aws-cdk@2 --force -
Before you can deploy the CDK project, use the following command to bootstrap your AWS environment. Bootstrapping is the process of creating resources needed for deploying CDK projects. These resources include an Amazon Simple Storage Service (Amazon S3) bucket for storing files and IAM roles that grant permissions needed to perform deployments.
cdk bootstrap -
Finally, use the following command to deploy the pipeline infrastructure. Replace SNS arn of the topic you want to receive alerts for manual approval with your sns arn.
cdk deploy --parameters SNSarn=<SNS arn of the topic you want to receive alerts for human approval> -
The deployment will create the following AWS resources:
- a CodeCommmit repository with all files of source_code folder which holds the source code for SCP creation and management,
- 3 CodeBuild projects, one for each of the pipeline stages - code validation, policy checks, code deploy (as defined in the architecture diagram above)
- a human approval stage in the pipeline
- a CodePipeline tying all the CodeBuild steps togather
- necessary AWS resources to support the management of the pipeline. For details of the AWS resources created by this pipeline refer to this readme
-
Once the pipeline runs, and if the SCPs specified in the templates pass all the validation steps, a notification will be sent to the subscribed email/mobile address on the SNS topic that was provided during CDK deploy. Once you approve the changes, the pipeline will attempt to deploy SCPs in your AWS Organization if the correct organization structure exists.
Use the following command to delete the infrastructure that was provisioned as part of the examples in this blog post.
cdk destroy
For deploying the SCPs through your chosen pipeline or directly in your organization using Terraform as the Infrastructure-as-Code (IaC), navigate directly to the source_code folder.
There are detail steps mentioned about the scripts defined and how to deploy them.
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.