Initial commit: Spicy CDK automation framework

Jenkins shared library and CDK constructs for AWS infrastructure.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/ACCOUNTS.md

@@ -0,0 +1,216 @@
+# Account Configuration Guide
+
+Configure AWS accounts for multi-environment deployments.
+
+## Overview
+
+The `accounts.groovy` utility provides a centralized way to manage AWS account configurations across environments. This eliminates hardcoding credentials and region information in individual Jenkinsfiles.
+
+## Usage
+
+```groovy
+@Library(["spicy-automation@main"]) _
+
+// Get all accounts
+def allAccounts = accounts.get()
+
+// Use a specific environment
+def prodAccount = allAccounts.SPICY_CA_CENRAL_1_PROD
+
+spicyVPC(
+    jenkinsAwsCredentialsId: prodAccount.jenkinsAwsCredentialsId,
+    region: prodAccount.region,
+    accountId: prodAccount.accountId,
+    stackName: prodAccount.vpcStackName,
+    ownerTag: "Platform",
+    productTag: "spicy",
+    componentTag: "vpc",
+)
+```
+
+## Available Accounts
+
+| Key | Environment | Description |
+|-----|-------------|-------------|
+| `SPICY_CA_CENRAL_1` | Base | Base account configuration |
+| `SPICY_CA_CENRAL_1_DEV` | Development | Development environment |
+| `SPICY_CA_CENRAL_1_SANDBOX` | Sandbox | Sandbox/experimental environment |
+| `SPICY_CA_CENRAL_1_QA` | QA | Quality assurance environment |
+| `SPICY_CA_CENRAL_1_STAGING` | Staging | Pre-production environment |
+| `SPICY_CA_CENRAL_1_PROD` | Production | Production environment |
+
+## Account Properties
+
+Each account object contains:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `accountId` | string | AWS Account ID (12-digit) |
+| `region` | string | AWS Region (e.g., `ca-central-1`) |
+| `jenkinsAwsCredentialsId` | string | Jenkins credential ID for AWS access |
+| `vpcStackName` | string | Default VPC stack name for this environment |
+| `ecsClusterStackName` | string | Default ECS cluster stack name |
+
+## Configuration Files
+
+Account configurations are loaded from YAML files in the `resources/` directory:
+
+```
+jenkins/
+└── resources/
+    └── accounts/
+        ├── aws-spicy-ca-central-1.yml          # Base account
+        └── environments/
+            ├── aws-spicy-ca-central-1-dev.yml
+            ├── aws-spicy-ca-central-1-sandbox.yml
+            ├── aws-spicy-ca-central-1-staging.yml
+            └── aws-spicy-ca-central-1-prod.yml
+```
+
+### Base Account Configuration
+
+`resources/accounts/aws-spicy-ca-central-1.yml`:
+
+```yaml
+accountId: "123456789012"
+region: "ca-central-1"
+jenkinsAwsCredentialsId: "aws-spicy-ca-central-1"
+```
+
+### Environment Configuration
+
+`resources/accounts/environments/aws-spicy-ca-central-1-prod.yml`:
+
+```yaml
+# Inherits from base account
+vpcStackName: "spicy-vpc-prod"
+ecsClusterStackName: "spicy-ecs-cluster-prod"
+jenkinsAwsCredentialsId: "aws-spicy-ca-central-1-prod"
+```
+
+## Adding a New Account
+
+### 1. Create Base Account File
+
+Create `resources/accounts/aws-mycompany-us-west-2.yml`:
+
+```yaml
+accountId: "987654321098"
+region: "us-west-2"
+jenkinsAwsCredentialsId: "aws-mycompany-us-west-2"
+```
+
+### 2. Create Environment Files
+
+Create `resources/accounts/environments/aws-mycompany-us-west-2-prod.yml`:
+
+```yaml
+vpcStackName: "mycompany-vpc-prod"
+ecsClusterStackName: "mycompany-ecs-cluster-prod"
+```
+
+### 3. Update accounts.groovy
+
+Edit `jenkins/vars/accounts.groovy`:
+
+```groovy
+def getAccounts() {
+  def accounts = [:]
+
+  // Existing accounts...
+  accounts.put("SPICY_CA_CENRAL_1", resources.getProperties("accounts/aws-spicy-ca-central-1.yml"))
+
+  // Add new account
+  accounts.put("MYCOMPANY_US_WEST_2", resources.getProperties("accounts/aws-mycompany-us-west-2.yml"))
+
+  return accounts
+}
+
+def getProduction() {
+  def accounts = [:]
+
+  // Existing...
+  accounts.put(
+    "SPICY_CA_CENRAL_1_PROD",
+    getAccounts().SPICY_CA_CENRAL_1 + resources.getProperties("accounts/environments/aws-spicy-ca-central-1-prod.yml")
+  )
+
+  // Add new environment
+  accounts.put(
+    "MYCOMPANY_US_WEST_2_PROD",
+    getAccounts().MYCOMPANY_US_WEST_2 + resources.getProperties("accounts/environments/aws-mycompany-us-west-2-prod.yml")
+  )
+
+  return accounts
+}
+```
+
+## Jenkins Credentials Setup
+
+For each account, create AWS credentials in Jenkins:
+
+1. Go to **Manage Jenkins** → **Manage Credentials**
+2. Add credentials:
+   - **Kind**: Username with password
+   - **Username**: AWS Access Key ID
+   - **Password**: AWS Secret Access Key
+   - **ID**: Match the `jenkinsAwsCredentialsId` in your config (e.g., `aws-spicy-ca-central-1-prod`)
+
+## Multi-Region Deployments
+
+Deploy to multiple regions:
+
+```groovy
+@Library(["spicy-automation@main"]) _
+
+def regions = [
+    accounts.get().SPICY_CA_CENRAL_1_PROD,
+    accounts.get().SPICY_EU_WEST_1_PROD,  // If configured
+]
+
+regions.each { account ->
+    spicyVPC(
+        jenkinsAwsCredentialsId: account.jenkinsAwsCredentialsId,
+        region: account.region,
+        stackName: "vpc-${account.region}",
+        ownerTag: "Platform",
+        productTag: "spicy",
+        componentTag: "vpc",
+    )
+}
+```
+
+## Environment-Specific Overrides
+
+Override settings per environment:
+
+```groovy
+@Library(["spicy-automation@main"]) _
+
+def account = accounts.get().SPICY_CA_CENRAL_1_DEV
+
+spicyVPC(
+    jenkinsAwsCredentialsId: account.jenkinsAwsCredentialsId,
+    region: account.region,
+    stackName: account.vpcStackName,
+    ownerTag: "Dev",
+    productTag: "spicy",
+    componentTag: "vpc",
+
+    // Dev-specific: fewer AZs, no NACL subnets
+    numberOfAzs: 2,
+    createAdditionalPrivateSubnets: false,
+)
+```
+
+## Best Practices
+
+1. **Use environment-specific credentials**: Each environment should have its own AWS credentials with appropriate permissions.
+
+2. **Naming conventions**: Use consistent naming like `{company}-{region}-{env}` for stack names.
+
+3. **Least privilege**: Production credentials should only have permissions needed for deployment.
+
+4. **Separate accounts**: Use separate AWS accounts for production vs non-production when possible.
+
+5. **Centralize configuration**: Keep all account configs in the shared library, not in individual repos.