This document describes the features implemented in the Little Orange project. Features are grouped into functional categories.
Perform a project search for the feature name to find where and how it is implemented.
- Little Orange Features
- 1 Orchestration and Deployment
- 2 Centralised AWS Management
- 3 Logging and Audit
- 4 Identity and Access Management
- 5 Security
- 6 Networking
- 7 Workload Services
- AWS SAM Support
- AWS Billing
- AWS CloudTrail
- AWS Config
- AWS Organizations
- AWS GuardDuty
- AWS SecurityHub
- Federated Identify with AWS SSO
- Federated Identity with IAM SAML Identity Provider
- VPC Factory with CloudFormation Macro
- Service Catalog for VPC Deployment
- Centralised DNS with Route 53 Resolver
- Transit Gateway
Useful entrypoints for project functions are documented as make targets. Utility functions are provided to aid project discoverability.
> make
+------------------------------------+
| LITTLE ORANGE HELP |
+------------------------------------+
Available targets:
Deploy Deploy Little Orange
DeployGitHubCredentials Deploy stack to store GitHub credentials in Secrets Manager and create CodeBuild credentials
DeployPipeline Deploy CodeBuild projects with webhook to run tests on GitHub pull requests and deploy on merge
...
See also the Tooling section of the main README.
CloudReach Sceptre is used to provision all Little Orange resources through multi-stack CloudFormation deployments. Stack inputs are wired to outputs of other stacks which Sceptre can interpret and resolve as dependencies at deploy time to ensure all connected resources are kept in-sync. Sceptre also provides extensible "hooks" and "resolvers" written in Python to accommodate additional functionality.
The Sceptre config is separated into multiple Stack Groups (Core, Security, Networking, etc.) that correspond to the core AWS Accounts created as part of Little Orange. The Stack Group Config (config.yaml) within each specifies the AWS Profile that will be used to access each role.
See also the Tooling section of the main README.
The Sceptre Resolver Library provides useful Sceptre Resolvers leveraged in Little Orange.
Command: allows for arbitrary shell commands to be evaluated as part of parameters for stack deploymentsUploadS3: allows for assets to be uploaded to S3 and parameter resolved to S3 URI as part of stack deployments
The Sceptre Integration for AWS SAM provides a Python library for invoking AWS SAM project builds via make targets and reads in the resuling CloudFormation template.
The build integration library is invoked from an accompanying Python BuildSAM.py script to be invoked from the template_path of a Sceptre Stack Config. It implements a handler that invokes the integration library and returns the resulting template to be used in stack deployment.
Linting of YAML files is performed by yamllint and driven by make.
Linting of CloudFormation is performed by cfn-lint and driven bt make.
These tools help to ensure the correctness and robustness of the resources maintained within this project.
Python unit tests are implemented using pytest.
For code that interact with the AWS SDK for Python, the following strategies are employed in order of preference:
- moto - https://github.com/spulec/moto - mock implementations of
boto3 - Botocore Stubber- https://botocore.amazonaws.com/v1/documentation/api/latest/reference/stubber.html - provided stubbing in botocore
- Python Mocking - https://docs.python.org/3/library/unittest.mock.html - roll own mocking from scratch in Python (not preferred)
See also the Tooling section of the main README.
Little Orange includes a Python script to provide a programmatic way to generate AWS Profile entries for each account in the AWS Organization.
These AWS Profiles are named as required to drive the Sceptre deployment of Little Orange. A make target documents how to execute the script. This script also supports generating the AWS Profile entries required to deploy within the CodeBuild deployment automation.
# set an existing AWS Profile or provide credentials in environment to list accounts in the AWS Organization
# generate AWS Profiles and direct output to a file (to update profiles direct to ~/.aws/config)
make GenerateAWSProfiles >> ~/.aws/config.new
# generate AWS Profiles for use in ECS (executed by deployment automation)
make GenerateECSAWSProfiles >> ~/.aws/config.newLittle Orange deploys an integration between the GitHub repository and AWS CodeBuild to trigger deployment automation on new changes. CloudFormation (managed outside of the Sceptre deployment footprint) deploys the requisite infrastructure and configures credentials to access GitHub (credentials provided by user).
Little Orange configures webhooks to trigger a build project for changes to Pull Requests (PRs) in the GitHub repository. This build project executes linting and validation checks to provide early feedback.
Python dependencies are managed by Pipenv. This provides a simple way to track project dependencies and boostrap new copies of the project. Required Pipenv commands are maintained and documented as make targets.
See also the Tooling section of the main README.
Little Orange configures tools and services with a "core" management account that support the operation and maintenance of the AWS multi-account footprint.
Little Orange manages multiple accounts via AWS Organizations. Little Orange manages resources across a number of specialised accounts:
LittleOrangeManagementLittleOrangeSecurityLittleOrangeNetworking
CloudFormation Resource Providers provide the ability to manage AWS Organizations resources. This allows for the structure of the AWS Organization to be defined declaratively using CloudFormation.
The Quarantine OU allows for a compromised AWS Account to be detained and all access to AWS APIs revoked. The Quarantine OU has a Service Control Policy (SCP) attached that assigns Deny to all AWS IAM Actions.
Little Orange provisions and manages all resources via the AWS CloudFormation service. Resources and services not natively supported by CloudFormation are implemented using CloudFormation Custom Resources or CloudFormation Resource Providers.
The CloudFormation Custom Resource Proxy allows for a single Custom Resource Lambda Function deployment to be leveraged from multiple accounts and regions. For Custom Resources implemented as AWS SAM projects this pattern is necessary as limitations exist for deploying the same AWS SAM template across many accounts or regions. The proxy is implemented as a lightweight, inlined Lambda Function that can be deployed across all accounts and regions -- Lambda-backed Custom Resources can only be invoked in the same account and region as the source CloudFormation Stack.
References:
- The CloudFormation Stack defines a Custom Resource using the Custom Resource Proxy deployed within the same account and region.
- The Custom Resource Proxy unwraps the actual target Custom Resource service token and parameters from the
Propertiespayload. - The Custom Resource Proxy is configured with the appropriate IAM Role to perform a cross-region, cross-account invoke of the Custom Resource Lambda Function.
- The
crhelperlibrary of the target Custom Resource handles completing the callback to CloudFormation for the resource.
The CloudFormation Macro Proxy allows for a single CloudFormation Lambda Macro Function deployment to be leveraged by multiple regions. Usually, a CloudFormation Macro must invoke a Lambda function in the same region.
When using the CloudFormation Macro Proxy, the Macro function itself is deployed once in a central location (reference), and the Lambda ARN is stored in AWS SSM Parameter Store. The CloudFormation Macro Proxy is deployed via Stack Set across all accounts and regions (reference).
Defining a proxied Macro involves specifying the local proxy as the function to invoke. The CloudFormation Macro Proxy handles looking up the macro name (e.g. NetworkingVPC below) to determine the actual Lambda ARN that backs the Macro and handles performing a cross-account and cross-region invocation of the function and returning the result (reference).
Macro:
Type: AWS::CloudFormation::Macro
Properties:
Name: NetworkingVPC
Description: Expands LittleOrange::Networking::VPC Resources into CloudFormation VPC Resources
FunctionName: !Sub arn:aws:lambda:${AWS::Region}:${MacroProxyAccountId}:function:LittleOrangeCloudFormationMacroProxy
...CloudFormation Stack Sets can be deployed using self-managed IAM Roles in target accounts that does not rely on the AWS Organizations integration for CloudFormation. Little Orange handles deploying this required trust relationship between the management and child accounts via a service-managed Stack Set as per the following AWS Documentation:
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-prereqs-self-managed.html
Management of Cost and Usage Reports resources are not supported by CloudFormation. Little Orange provides an implementation of a CloudFormation Custom Resource for administering Cost and Usage Reports.
Little Orange configures Cost and Usage Reports generation into S3. AWS Budgets is configured to provide a basic forecasted and actual spending alert.
TBC
Little Orange configures AWS Cost Explorer to notify on daily and weekly anomaly detection.
AWS: Detecting unusual spend with AWS Cost Anomaly Detection
AWS CloudTrail is configured across all accounts and regions via an AWS Organizations-integrated trail.
AWS: Creating a trail for an organization
CloudFormation support for AWS CloudTrail does not yet provide support for configuring AWS Organizations integration for a trail. Little Orange provides a CloudFormation Custom Resource for enabling AWS Organizations integration on an existing trail.
TBC
TBC
TBC
TBC
Add notes about setting up ACM Certificate
TBC
- Cost and Usage Reports
- AWS Budget: forecasted and actual
- Cost Explorer Anomaly Detection: daily and weekly
- CloudTrail trail deployed to
Coreaccount - CloudTrail data delivered to S3 Bucket in
Coreaccount - CloudTrail data delivered to CloudWatch Log Group in
Coreaccount - Trail enabled as Organization trail via SAM Custom Resource
- AWS Organisation Trusted Access enabled for Config and Config Rules
Securityaccount enabled as Delegated Administrator for Config Rules and Config- Config deployed across Organization via Stack Set deployed to
Coreaccount (and Stack Set forCoreaccount directly) - Config Aggregator and S3 Bucket for Config snapshots deployed to
Securityaccount
- Declarative Organizations resource state in CloudFormation stack in
Coreaccount - Organizations resource management via CloudFormation Resource Providers
AWS::Organization::OrganizationAWS::Organization::OrganizationalUnitAWS::Organization::AccountAWS::Organization::ServiceControlPolicy
Securityaccount enabled as Delegated Administrator of Organization for GuardDuty- GuardDuty Organization configuration via SAM Custom Resource in
Coreaccount - GuardDuty enabled in all regions of
Securityaccount and auto-enable enabled via Stack Set inCoreaccount - Little Orange accounts specifically enrolled as GuardDuty member accounts via Stack Set in
Securityaccount
- SecurityHub Hub deployed across Organization accounts and regions via Stack Set in
Coreaccount - Custom Resource registers
Securityaccount as Delegated Administrator for Security Hub and handles registering existing accounts as members
The below architecture is not implemented as part of Little Orange due to gaps in ability to automate configuration of AWS SSO. Currently, AWS SSO can only be configured via the AWS Console. The following guide presents a good ClickOps walk-through of configurating AWS SSO for federated identity with Azure Active Directory:
https://aws.amazon.com/blogs/aws/the-next-evolution-in-aws-single-sign-on/
