Eve library

Oshun SSM Parameter Store Module

Other

Revision 1

On this page

This Terraform module manages configuration parameters in AWS Systems Manager Parameter Store for all Oshun services across domains.

Features#

  • Centralized Configuration: All application configuration in SSM Parameter Store
  • Hierarchical Organization: Parameters organized by type and domain
  • Feature Flags: Built-in support for feature flags with rollout percentages
  • Rate Limiting: Pre-defined rate limit configurations
  • Cache Settings: Configurable cache TTLs per use case
  • Connection Pools: Database connection pool settings
  • Retry Policies: Configurable retry policies with exponential backoff
  • AI Configuration: Model-specific settings for AI/ML services
  • Domain Isolation: Domain-specific configuration namespaces
  • Path-Based Access: Efficient batch parameter retrieval by path

Usage#

hcl
module "ssm" {
  source = "../ssm"

  environment = "production"
  region      = "us-east-1"
  name_prefix = "oshun"

  # Application configuration
  app_config = {
    log_level = {
      description = "Default log level"
      value       = "info"
    }
  }

  # Service endpoints
  service_endpoints = {
    api-gateway = {
      description = "API Gateway service"
      internal    = "http://api.oshun.local:3000"
      external    = "https://api.oshun.app"
      health      = "http://api.oshun.local:3000/health"
    }
  }

  # Feature flags
  feature_flags = {
    new_feature = {
      description = "Enable new feature"
      enabled     = true
      rollout     = 50  # 50% rollout
    }
  }

  # Rate limits
  rate_limits = {
    api_default = {
      description    = "Default API rate limit"
      requests       = 1000
      window_seconds = 60
      burst          = 100
    }
  }

  tags = {
    Environment = "production"
  }
}

Parameter Types#

Application Configuration#

General application settings stored as key-value pairs.

hcl
app_config = {
  log_level = {
    description = "Application log level"
    value       = "info"
    type        = "String"  # String, StringList, or SecureString
    tier        = "Standard"  # Standard or Advanced
  }
}

Service Endpoints#

Service discovery configuration with multiple endpoint types.

hcl
service_endpoints = {
  my-service = {
    description = "My service endpoints"
    internal    = "http://service.local:3000"  # Internal DNS/Service Connect
    external    = "https://api.example.com"    # Public endpoint
    grpc        = "service.local:50051"        # gRPC endpoint
    health      = "http://service.local:3000/health"  # Health check
  }
}

Feature Flags#

Feature toggles with percentage-based rollouts.

hcl
feature_flags = {
  dark_mode = {
    description = "Enable dark mode"
    enabled     = true
    rollout     = 100  # Percentage of users (0-100)
  }
}

Parameter value structure:

json
{
  "enabled": true,
  "rollout": 100
}

Rate Limits#

API rate limiting configuration.

hcl
rate_limits = {
  auth = {
    description    = "Authentication rate limit"
    requests       = 10     # Max requests
    window_seconds = 60     # Time window
    burst          = 5      # Burst allowance
  }
}

Cache Configuration#

Cache TTL and size settings.

hcl
cache_config = {
  session = {
    description = "Session cache settings"
    ttl_seconds = 3600   # TTL in seconds
    max_size    = 10000  # Max entries (0 = unlimited)
  }
}

Database Connection Pools#

Connection pool settings per database.

hcl
db_pool_config = {
  primary = {
    description     = "Primary database pool"
    min_size        = 10
    max_size        = 50
    idle_timeout    = 30000    # ms
    acquire_timeout = 60000    # ms
  }
}

Storage Configuration#

S3-compatible storage settings.

hcl
storage_config = {
  uploads = {
    description       = "User uploads storage"
    bucket            = "my-uploads-bucket"
    region            = "us-east-1"
    endpoint          = ""  # Leave empty for AWS S3
    max_upload_size   = 104857600  # 100MB
    allowed_mimetypes = ["image/jpeg", "image/png"]
  }
}

Timeouts#

Operation timeout settings.

hcl
timeouts = {
  http_request = {
    description = "HTTP request timeout"
    value_ms    = 30000  # milliseconds
  }
}

Concurrency Limits#

Worker concurrency settings.

hcl
concurrency_limits = {
  ai_processing = {
    description = "AI processing concurrency"
    max_workers = 8
    queue_size  = 200
  }
}

Retry Policies#

Retry behavior configuration.

hcl
retry_policies = {
  ai = {
    description = "AI service retry policy"
    max_retries = 5
    base_delay  = 2000   # ms
    max_delay   = 30000  # ms
    exponential = true   # Exponential backoff
  }
}

Domain Configuration#

Domain-specific settings.

hcl
domain_config = {
  yemaya = {  # Domain name
    max_projects = {
      description = "Max projects per user"
      value       = "100"
      type        = "String"
    }
  }
}

AI Configuration#

AI/ML service settings.

hcl
ai_config = {
  text_generation = {
    description      = "Text generation settings"
    default_model    = "gpt-4"
    max_tokens       = 4096
    temperature      = 0.7
    timeout_seconds  = 120
    fallback_enabled = true
  }
}

Outputs#

Parameter ARNs and Names#

hcl
# Access individual parameter ARNs
module.ssm.app_config_arns["log_level"]
module.ssm.feature_flag_arns["new_feature"]
module.ssm.rate_limit_arns["api_default"]

# Get all parameter ARNs
module.ssm.all_parameter_arns

Path-Based Access#

hcl
# Get parameter paths for batch retrieval
module.ssm.parameter_paths.all          # /oshun/production
module.ssm.parameter_paths.features     # /oshun/production/features
module.ssm.parameter_paths.rate_limits  # /oshun/production/rate-limits

IAM Policies#

hcl
# Attach read policy to ECS task role
resource "aws_iam_role_policy" "ssm_access" {
  role   = aws_iam_role.task.id
  policy = module.ssm.parameters_read_policy_json
}

Accessing Parameters in Applications#

ECS Task Definition#

hcl
resource "aws_ecs_task_definition" "app" {
  container_definitions = jsonencode([{
    name = "app"
    environment = [
      {
        name  = "SSM_PARAMETER_PATH"
        value = module.ssm.parameter_paths.all
      }
    ]
  }])
}

Application Code (Node.js)#

typescript
import {
  SSMClient,
  GetParametersByPathCommand,
  GetParameterCommand,
} from '@aws-sdk/client-ssm';

const client = new SSMClient({});

// Get all parameters by path
async function getConfigByPath(path: string): Promise<Record<string, string>> {
  const config: Record<string, string> = {};
  let nextToken: string | undefined;

  do {
    const response = await client.send(
      new GetParametersByPathCommand({
        Path: path,
        Recursive: true,
        WithDecryption: true,
        NextToken: nextToken,
      })
    );

    for (const param of response.Parameters || []) {
      const key = param.Name!.split('/').pop()!;
      config[key] = param.Value!;
    }

    nextToken = response.NextToken;
  } while (nextToken);

  return config;
}

// Get single parameter
async function getParameter(name: string): Promise<string> {
  const response = await client.send(
    new GetParameterCommand({
      Name: name,
      WithDecryption: true,
    })
  );
  return response.Parameter!.Value!;
}

// Usage
const featureFlags = await getConfigByPath('/oshun/production/features');
const rateLimit = JSON.parse(
  await getParameter('/oshun/production/rate-limits/api_default')
);

Feature Flag Evaluation#

typescript
interface FeatureFlag {
  enabled: boolean;
  rollout: number;
}

function isFeatureEnabled(flag: FeatureFlag, userId: string): boolean {
  if (!flag.enabled) return false;
  if (flag.rollout >= 100) return true;

  // Consistent hashing for user
  const hash = hashCode(userId) % 100;
  return hash < flag.rollout;
}

function hashCode(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    hash = (hash << 5) - hash + str.charCodeAt(i);
    hash |= 0;
  }
  return Math.abs(hash);
}

Parameter Naming Convention#

All parameters follow this naming convention:

text
/{prefix}/{environment}/{category}/{name}

Examples:

  • /oshun/production/app/log_level
  • /oshun/production/features/dark_mode
  • /oshun/production/rate-limits/api_default
  • /oshun/production/domains/yemaya/max_projects

Best Practices#

  1. Use Path-Based Retrieval: Fetch parameters by path for efficiency
  2. Cache Parameters: Cache parameter values and refresh periodically
  3. SecureString for Sensitive Data: Use SecureString type with KMS for sensitive values
  4. Environment Separation: Use different parameter paths per environment
  5. Tagging: Tag parameters for cost allocation and organization
  6. Validation: Validate parameter values in application code

Inputs#

Name Description Type Default Required
environment Deployment environment string - yes
region AWS region string "us-east-1" no
name_prefix Prefix for parameter names string "oshun" no
kms_key_arn KMS key for SecureString string "" no
app_config Application configuration map(object) {} no
service_endpoints Service endpoint configs map(object) {} no
feature_flags Feature flag configs map(object) {} no
rate_limits Rate limit configs map(object) {} no
cache_config Cache configuration map(object) {} no
db_pool_config Database pool configs map(object) {} no
storage_config Storage configs map(object) {} no
timeouts Timeout configs map(object) {} no
concurrency_limits Concurrency limit configs map(object) {} no
retry_policies Retry policy configs map(object) {} no
domain_config Domain-specific configs map(map) {} no
ai_config AI service configs map(object) {} no
pagination_config Pagination defaults object {} no
cors_config CORS configuration object {} no
monitoring_config Monitoring configuration object {} no
custom_parameters Custom parameters map(object) {} no

Outputs#

Name Description
parameter_prefix Base path for all parameters
app_config_arns Map of app config parameter ARNs
feature_flag_arns Map of feature flag ARNs
rate_limit_arns Map of rate limit ARNs
all_parameter_arns Combined map of all parameter ARNs
parameters_read_policy_json IAM policy for read access
parameters_write_policy_json IAM policy for write access
parameter_paths Map of parameter paths by category
parameters_summary Summary of created parameters