#AWS Account Setup

Setting up AWS for tsdevstack deployments. AWS requires separate accounts per environment for proper isolation.

AWS Organization (Management Account)
+-- tsdevstack-dev (Member Account)
+-- tsdevstack-staging (Member Account)
+-- tsdevstack-prod (Member Account)

Why separate accounts? Secrets Manager isolation, billing separation, resource name isolation, and impossible cross-environment access.

#Step 1: Create AWS Organization

1. Go to AWS Organizations
2. Click Create an organization
3. Your current account becomes the Management Account

#Step 2: Create IAM Admin User

The root user cannot switch roles to member accounts. You need an IAM user.

1. Go to IAM > Users > Create user
2. User name: admin
3. Check: Provide user access to the AWS Management Console
4. Select: I want to create an IAM user
5. Attach: AdministratorAccess policy
6. Copy the password — you won't see it again
7. Sign out and sign back in as the IAM user

#Step 3: Create Member Account

Repeat for each environment (dev, staging, prod):

#3.1 Create the Account

1. Go to Organizations
2. Click Add an AWS account > Create an AWS account
3. Account name: e.g. myproject-dev (use your own project naming)
4. Email: any email you own (e.g. you+awsdev@gmail.com using the + trick for unique addresses)
5. IAM role name: Leave as OrganizationAccountAccessRole
6. Wait 1-5 minutes until status shows Active

#3.2 Get the Account ID

Click on the account in the Organizations page and copy the 12-digit Account ID.

#3.3 Switch to the Member Account

1. Click your account name (top right)
2. Go to Switch Role
3. Enter the Account ID and role name OrganizationAccountAccessRole

#3.4 Create IAM User for tsdevstack

1. Go to IAM > Users > Create user
2. User name: tsdevstack-dev
3. DO NOT check "Provide user access to the AWS Management Console"

#3.5 Attach Policies

For simplicity:

Attach AdministratorAccess.

For least-privilege:

Use a single inline policy instead of managed policies (AWS limits roles to 10 managed policies). See the inline policy in the CI/CD guide — the same policy works for IAM users.

#3.6 Create Access Key

1. Click on the user > Security credentials tab
2. Access keys > Create access key
3. Select Command Line Interface (CLI)
4. Copy both values (Access key ID + Secret access key)

#3.7 Repeat for Other Environments

Switch back to the Management Account and repeat Steps 3.1-3.6 for each environment.

#Step 4: Configure Credentials File

Create .tsdevstack/.credentials.aws.json:

{
  "dev": {
    "accountId": "123456789012",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  },
  "prod": {
    "accountId": "345678901234",
    "accessKeyId": "AKIAIMRX7TNNEXAMPLE",
    "secretAccessKey": "vf4tBg2sjkdfh3KdnEXAMPLEKEYsldf98234sdkf",
    "region": "us-east-1"
  }
}

Requirements:

• Each environment must use a different AWS account (different accountId)
• Framework validates unique account IDs and verifies credentials belong to the specified account

#Step 5: Initialize Cloud Provider

npx tsdevstack cloud:init --aws

This will:

1. Read environments from .credentials.aws.json
2. Validate each environment has a unique accountId
3. Verify credentials belong to the specified account (via STS API)
4. Test connection to Secrets Manager
5. Update .tsdevstack/config.json with cloud.provider: "aws"

#Next Steps: Route 53 (Required for Custom Domains)

If you plan to use a custom domain (e.g., api.example.com), you must set up Route 53 before deploying infrastructure. Without it, ACM certificate validation fails and deployment will error out.

See DNS & Domains for the full setup guide.

If you don't need a custom domain, services will use default AWS URLs (*.elb.amazonaws.com, *.cloudfront.net).

#Environment Isolation

Each environment must use a separate AWS account. The framework validates this during cloud:init and rejects duplicate account IDs.

#Troubleshooting

#"Cannot switch role" error

Cause: You're signed in as root user. Solution: Create an IAM user with AdministratorAccess and sign in as that user.

#"Access Denied" when creating secrets

1. IAM user missing SecretsManagerReadWrite policy
2. Wrong credentials in file
3. Wrong region

#"Account ID mismatch"

The credentials belong to a different AWS account than specified in accountId. Check your Account ID in the AWS Console (top-right corner).

#"Duplicate AWS accountId detected"

You're using the same AWS account for multiple environments. Each environment must have its own separate AWS account.