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

@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:

accountId: "123456789012"
region: "ca-central-1"
jenkinsAwsCredentialsId: "aws-spicy-ca-central-1"

Environment Configuration

resources/accounts/environments/aws-spicy-ca-central-1-prod.yml:

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

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:

vpcStackName: "mycompany-vpc-prod"
ecsClusterStackName: "mycompany-ecs-cluster-prod"

3. Update accounts.groovy

Edit jenkins/vars/accounts.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:

@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:

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