Configuration Reference¶

Table of Contents¶

Configuration File Structure
Section 1: Client Configuration
Section 2: Environment Configuration
Section 3: Security Groups Configuration
Section 4: Tags Configuration
Complete Configuration Examples
SG Naming Convention
Override System
Configuration Validation Rules
Configuration Best Practices
Troubleshooting Configuration Issues
Additional Resources

Configuration File Structure¶

The SG Provisioner uses a YAML configuration file with four main sections:

client:
  company_name: Global Bank
  company_prefix: globalbank
  account_id: "123456789012"
  tenant_id: "c001"

environment:
  env: prod
  region: us-west-2

security_groups:
  scenario: 3-tier-web
  vpc_source: parameter-store
  vpc_parameter_store_path: /vpc/globalbank-prod-c001-us-west-2-vpc/VPCId
  sg_name_override: ""
  workload: ""

  overrides:
    app:
      port_overrides:
        - protocol: tcp
          old_port: 8080
          new_port: 8443
      additional_ingress:
        - protocol: tcp
          port: 9090
          source_tier: web
          description: Prometheus metrics from web tier

tags:
  cost_center: Fraud Operations
  project: Real-time Fraud Detection
  owner: fraud-ml-engineering-team

Section 1: Client Configuration¶

company_name¶

Type: string
Required: Yes
Description: Full company name for display in reports
Example: Global Bank, Edge Corp

company_prefix¶

Type: string
Required: Yes
Description: Short company identifier (lowercase, no spaces)
Constraints: Pattern ^[a-z][a-z0-9-]*$
Example: globalbank, edge

account_id¶

Type: string (quoted)
Required: Yes
Description: 12-digit AWS account ID
Format: Must be quoted to preserve leading zeros
Example: "123456789012"

tenant_id¶

Type: string (quoted)
Required: Yes
Description: 4-character alphanumeric tenant identifier
Format: Pattern ^[a-z0-9]{4}$
Example: "c001"

Section 2: Environment Configuration¶

env¶

Type: string
Required: Yes
Description: Environment name
Valid Values: prod, dev, test, staging
Example: prod

region¶

Type: string
Required: Yes
Description: AWS region for deployment
Format: Pattern ^[a-z]{2}-[a-z]+-[0-9]$
Example: us-west-2

Section 3: Security Groups Configuration¶

scenario¶

Type: string
Required: Yes
Description: Scenario template name to use
Valid Values: Any YAML file in schemas/scenarios/ (without extension)
Example: 3-tier-web, 3-tier-rds-mysql, 2-tier-rds-postgresql

vpc_source¶

Type: string
Required: Yes
Description: How to resolve the target VPC ID
Valid Values: parameter-store, direct

# Option 1: Resolve from Parameter Store (recommended)
security_groups:
  vpc_source: parameter-store
  vpc_parameter_store_path: /vpc/globalbank-prod-c001-us-west-2-vpc/VPCId

# Option 2: Direct VPC ID
security_groups:
  vpc_source: direct
  vpc_id: vpc-0abc123def456

vpc_parameter_store_path¶

Type: string
Required: When vpc_source: parameter-store
Description: SSM Parameter Store path containing the VPC ID
Format: Must start with /
Example: /vpc/globalbank-prod-c001-us-west-2-vpc/VPCId

vpc_id¶

Type: string
Required: When vpc_source: direct
Description: Direct VPC ID
Format: Pattern ^vpc-[a-z0-9]+$
Example: vpc-0abc123def456

sg_name_override¶

Type: string
Required: No (can be empty)
Default: Auto-generated from client/environment values
Description: Override auto-generated SG name entirely

security_groups:
  sg_name_override: ""  # Use auto-generated name
  # OR
  sg_name_override: "my-custom-sg-name"

workload¶

Type: string
Required: No (can be empty)
Default: Empty (no workload segment in name)
Description: Workload discriminator for multiple SG sets in the same environment

# Without workload: globalbank-prod-c001-us-west-2-sg
security_groups:
  workload: ""

# With workload: globalbank-prod-c001-us-west-2-fraud-sg
security_groups:
  workload: "fraud"

# Another workload: globalbank-prod-c001-us-west-2-payments-sg
security_groups:
  workload: "payments"

overrides¶

Type: object (keyed by tier name)
Required: No
Description: Customer-specific modifications to the base scenario

See Override System for full details.

Section 4: Tags Configuration¶

tags¶

Type: object (key-value pairs)
Required: No
Description: Custom tags applied to all security groups

tags:
  cost_center: Fraud Operations
  project: Real-time Fraud Detection
  owner: fraud-ml-engineering-team

System Tags (Automatically Applied)¶

Tag Key	Source	Example Value
Name	Generated	globalbank-web-sg
Environment	environment.env	prod
ManagedBy	Static	sg-provisioner-tool
Tier	Per SG	web, app, db

Complete Configuration Examples¶

Example 1: Basic 3-Tier Web (No Overrides)¶

client:
  company_name: Acme Corp
  company_prefix: acme
  account_id: "123456789012"
  tenant_id: "a001"

environment:
  env: prod
  region: us-east-1

security_groups:
  scenario: 3-tier-web
  vpc_source: parameter-store
  vpc_parameter_store_path: /vpc/acme-prod-a001-us-east-1-vpc/VPCId
  sg_name_override: ""
  workload: ""

tags:
  cost_center: Engineering
  project: Main Platform
  owner: platform-team

Example 2: MySQL with Custom App Port¶

client:
  company_name: Acme Corp
  company_prefix: acme
  account_id: "123456789012"
  tenant_id: "a001"

environment:
  env: prod
  region: us-east-1

security_groups:
  scenario: 3-tier-rds-mysql
  vpc_source: direct
  vpc_id: vpc-0abc123def456
  sg_name_override: ""
  workload: "orders"

  overrides:
    app:
      port_overrides:
        - protocol: tcp
          old_port: 8080
          new_port: 3000

tags:
  cost_center: Commerce
  project: Order Processing
  owner: commerce-team

Example 3: Multiple Workloads (Same Environment)¶

# Config 1: fraud workload
security_groups:
  scenario: 3-tier-rds-postgresql
  workload: "fraud"
  # Result: acme-prod-a001-us-east-1-fraud-sg

# Config 2: payments workload (separate file)
security_groups:
  scenario: 3-tier-rds-postgresql
  workload: "payments"
  # Result: acme-prod-a001-us-east-1-payments-sg

SG Naming Convention¶

When sg_name_override is empty, the tool auto-generates names:

Without workload:

{company_prefix}-{env}-{tenant_id}-{region}-sg

Example: globalbank-prod-c001-us-west-2-sg

With workload:

{company_prefix}-{env}-{tenant_id}-{region}-{workload}-sg

Example: globalbank-prod-c001-us-west-2-fraud-sg

Derived names:

Stack: {sg_name}-stack
SSM path: /sg/{sg_name}/{tier}/SecurityGroupId
- e.g., /sg/globalbank-prod-c001-us-west-2-sg/web/SecurityGroupId
SG Name tag: {company_prefix}-{tier}-sg

Override System¶

Overrides let you customize a base scenario without creating a new YAML file.

Structure¶

overrides:
  <tier_name>:
    port_overrides:
      - protocol: <tcp|udp|icmp>
        old_port: <int>
        new_port: <int>
    additional_ingress:
      - protocol: <tcp|udp|icmp>
        port: <int>
        source: <cidr>          # OR
        source_tier: <tier>     # (mutually exclusive)
        description: <string>
    additional_egress:
      - protocol: <tcp|udp|icmp>
        port: <int>
        destination: <cidr>       # OR
        destination_tier: <tier>  # (mutually exclusive)
        description: <string>

Port Overrides¶

Replace an existing port in the scenario:

overrides:
  app:
    port_overrides:
      - protocol: tcp
        old_port: 8080    # Original port in scenario
        new_port: 8443    # New port to use

Additional Ingress¶

Append new inbound rules:

overrides:
  app:
    additional_ingress:
      - protocol: tcp
        port: 9090
        source_tier: web
        description: Prometheus metrics
      - protocol: tcp
        port: 8443
        source: 10.0.0.0/16
        description: Internal HTTPS from VPC

Additional Egress¶

Append new outbound rules:

overrides:
  app:
    additional_egress:
      - protocol: tcp
        port: 6379
        destination_tier: cache
        description: Redis cache connections

Configuration Validation Rules¶

Client¶

company_prefix: lowercase, starts with letter, alphanumeric + hyphens
account_id: exactly 12 digits, must be quoted
tenant_id: exactly 4 alphanumeric characters

Environment¶

env: one of prod, dev, test, staging
region: valid AWS region format (e.g., us-west-2)

Security Groups¶

vpc_source: must be parameter-store or direct
vpc_parameter_store_path: must start with / (when using parameter-store)
vpc_id: must match ^vpc-[a-z0-9]+$ (when using direct)
Override ports: 1-65535

Tags¶

All values must be strings

Configuration Best Practices¶

1. Use Parameter Store for VPC ID¶

vpc_source: parameter-store  # Decouples SG from VPC deployment

2. Use Workload Discriminator for Multiple SG Sets¶

workload: "fraud"     # Separate SG set per workload
workload: "payments"  # No naming collisions

3. Keep Overrides Minimal¶

Use overrides for small tweaks. If you need a fundamentally different architecture, create a new scenario YAML.

4. Tag for Cost Allocation¶

tags:
  cost_center: Fraud Operations
  project: Fraud Detection
  owner: fraud-team

5. Quote Numeric Strings¶

account_id: "123456789012"  # Always quote
tenant_id: "c001"           # Always quote

6. Version Control Configurations¶

Store configs in Git. Each config file represents a deployable SG set.

7. Test Before Production¶

environment:
  env: dev  # Test here first

Troubleshooting Configuration Issues¶

Issue: VPC not found in Parameter Store¶

Error: VPC ID not found in Parameter Store at: /vpc/.../VPCId

Solution: Deploy the VPC first using the VPC Provisioner, or switch to vpc_source: direct.

Issue: Scenario not found¶

Error: Scenario YAML not found

Solution: Use list-scenarios to see available scenarios. Check spelling matches filename.

Issue: Invalid port in override¶

Error: Port values must be between 1 and 65535

Solution: Ensure ports are integers between 1 and 65535.

Issue: Account ID loses leading zeros¶

Solution: Always quote the account_id:

account_id: "012345678901"  # Quoted preserves leading zero

Issue: Stack already exists¶

Solution: Use delete-security-groups --force first, or use a different workload value.

Additional Resources¶

User Guide - Complete command reference
Scenarios - Scenario details and customization
Troubleshooting - Common issues and solutions