Multi-Account Setup
Add accounts under test and deploy to all of them. A high-privilege deploy role creates the test infrastructure in each account; tests then run as a scoped role CATS creates there, so the two privilege levels never share an identity.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Parent Account (runs CATS) │
│ - Runs CATS tests │
│ - Assumes the deploy role that exists in each target account │
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Prod Account │ │ Dev Account │ │ Shared Services │
│ (Spoke) │ │ (Spoke) │ │ (Spoke) │
│ - CATS IAM role │ │ - CATS IAM role │ │ - CATS IAM role │
│ - Test infra │ │ - Test infra │ │ - Test infra │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Prerequisites
- A parent account: the account tests run from, whose ID goes in
cats_deployment_settings.parent_account_idand which the test roles trust - An existing cross-account role in each target account (e.g.,
AWSControlTowerExecution,OrganizationAccountAccessRole, or a custom-deployed role) that the credentials runningcats infracan assume - AWS credentials for the parent account (the one that runs CATS)
Configuration
cats_deployment_settings:
parent_account_id: "999999999999" # Parent account: where CATS runs
deploy_role_name: AWSControlTowerExecution # Role to assume for deployment
aws_region: us-east-1
global_account_settings:
additional_roles:
readonly:
managed_policies:
- ReadOnlyAccess
accounts_under_test:
prod:
account_id: "111111111111"
account_name: "Production"
dev:
account_id: "222222222222"
account_name: "Development"
shared:
account_id: "333333333333"
account_name: "Shared Services"
Adding Network Targets
For network testing, add account_network_under_test and configure listen ports:
global_network_settings:
tcp_listen_ports: [443, 8080]
udp_listen_ports: [5000]
accounts_under_test:
prod:
account_id: "111111111111"
account_network_under_test:
private:
vpc_id: vpc-abc123
subnet_ids: [subnet-aaa111]
dmz:
vpc_id: vpc-abc123
subnet_ids: [subnet-ddd333]
dev:
account_id: "222222222222"
account_network_under_test:
private:
vpc_id: /ssm/dev/vpc-id # SSM parameter reference
subnet_ids:
- /ssm/dev/private-subnet # Resolved at deploy time
Deploy to All Accounts
Deploy CATS infrastructure to all configured accounts in parallel:
Or deploy to specific accounts:
Check Deployment Status
Output shows CloudFormation stack status and the CATS release that deployed each stack:
Account Status Stack Version
prod CREATE_COMPLETE CATS-test-infra-prod 1.0.0
dev CREATE_COMPLETE CATS-test-infra-dev 1.0.0
shared not deployed - -
Write Cross-Account Tests
from cats import AccountUnderTest, CatsNetworkResponse
def test_prod_cannot_reach_dev(
prod_account: AccountUnderTest,
dev_account: AccountUnderTest,
) -> None:
"""Prove production cannot reach development network."""
target = dev_account.private.ec2_dns_name
result = prod_account.private.http_call(target, 443)
# TIMEOUT: no response, consistent with a silent drop. REFUSED would mean the path is open.
assert result == CatsNetworkResponse.TIMEOUT
def test_shared_can_reach_all(
shared_account: AccountUnderTest,
prod_account: AccountUnderTest,
dev_account: AccountUnderTest,
) -> None:
"""Prove shared services can reach both prod and dev."""
for target_account in [prod_account, dev_account]:
target = target_account.private.ec2_dns_name
result = shared_account.private.http_call(target, 443)
assert result == CatsNetworkResponse.SUCCESS
Run Tests
Destroy All Infrastructure
CATS is ephemeral by intent - end every testing session by cleaning up.
CI/CD Pattern
In pipelines, always ensure cleanup runs: