spicy-automation/docs/ACCOUNTS.md

# 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.