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#
- Use Path-Based Retrieval: Fetch parameters by path for efficiency
- Cache Parameters: Cache parameter values and refresh periodically
- SecureString for Sensitive Data: Use SecureString type with KMS for sensitive values
- Environment Separation: Use different parameter paths per environment
- Tagging: Tag parameters for cost allocation and organization
- 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 |