Skip to content

9 Standardize configuration #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mwarman merged 3 commits into from
Dec 2, 2025
Merged

9 Standardize configuration #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d58dae1
Standardize logging configuration variables and update related docume…
mwarman Dec 2, 2025
c0cb9b9
Add comprehensive configuration guide and update README for clarity
mwarman Dec 2, 2025
b142a64
Standardize logging configuration variable names across documentation…
mwarman Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 196 additions & 0 deletions docs/ConfigurationGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
# Configuration Guide

This guide provides comprehensive information about configuring the Lambda Starter application and its infrastructure.

## Application Configuration

The application configuration is managed through environment variables. These variables are validated using Zod schemas at runtime to ensure proper configuration.

### Environment Variables

The following environment variables are available for configuring the application:

| Variable | Type | Description | Default | Required |
| ------------------- | ------- | ------------------------------------------------ | ----------- | -------- |
| `TASKS_TABLE` | string | The name of the DynamoDB table for storing tasks | - | Yes |
| `AWS_REGION` | string | The AWS region where resources are deployed | `us-east-1` | No |
| `LOGGING_ENABLED` | boolean | Enable or disable application logging | `true` | No |
| `LOGGING_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `debug` | No |
| `LOGGING_FORMAT` | enum | Logging format: `text`, `json` | `json` | No |
| `CORS_ALLOW_ORIGIN` | string | CORS allow origin header value | `*` | No |

### Usage

Application configuration is accessed through the `config` object exported from `src/utils/config.ts`:

```typescript
import { config } from './utils/config';

console.log(`Tasks table: ${config.TASKS_TABLE}`);
console.log(`Logging enabled: ${config.LOGGING_ENABLED}`);
```

### Configuration Validation

The application uses Zod to validate environment variables at startup. If validation fails, the application will throw an error with details about the validation issues.

---

## Infrastructure Configuration

The infrastructure configuration is managed through environment variables prefixed with `CDK_`. These variables control how AWS resources are provisioned using the AWS CDK.

### Environment Variables

The following environment variables are available for configuring the infrastructure:

| Variable | Type | Description | Default | Required |
| ------------------------- | ------- | ------------------------------------------------------ | ---------------- | -------- |
| `CDK_APP_NAME` | string | The application name used in resource naming | `lambda-starter` | No |
| `CDK_ENV` | enum | Environment: `dev`, `qat`, `prd` | - | Yes |
| `CDK_ACCOUNT` | string | AWS account ID for deployment | - | No |
| `CDK_REGION` | string | AWS region for deployment | - | No |
| `CDK_OU` | string | Organizational Unit for resource tagging | `leanstacks` | No |
| `CDK_OWNER` | string | Owner tag for resource tracking | `unknown` | No |
| `CDK_CORS_ALLOW_ORIGIN` | string | CORS allow origin for API Gateway and Lambda functions | `*` | No |
| `CDK_APP_LOGGING_ENABLED` | boolean | Enable logging in Lambda functions | `true` | No |
| `CDK_APP_LOGGING_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `info` | No |
| `CDK_APP_LOGGING_FORMAT` | enum | Logging format: `text`, `json` | `json` | No |

### Usage

Infrastructure configuration is managed through the `getConfig()` function in `infrastructure/utils/config.ts`:

```typescript
import { getConfig } from './utils/config';

const config = getConfig();
console.log(`Environment: ${config.CDK_ENV}`);
console.log(`App name: ${config.CDK_APP_NAME}`);
```

### Configuration Files

Infrastructure configuration can be provided through:

1. **Environment variables** - Set directly in your shell or CI/CD pipeline
2. **.env file** - Create a `.env` file in the `infrastructure/` directory for local development

Example `.env` file:

```bash
CDK_ENV=dev
CDK_ACCOUNT=123456789012
CDK_REGION=us-east-1
CDK_OU=leanstacks
CDK_OWNER=platform-team
CDK_CORS_ALLOW_ORIGIN=https://example.com
CDK_APP_LOGGING_ENABLED=true
CDK_APP_LOGGING_LEVEL=debug
CDK_APP_LOGGING_FORMAT=json
```

**Important:** Never commit `.env` files containing sensitive information to source control.

### Resource Tagging

All AWS resources created by the CDK are automatically tagged with the following tags:

| Tag | Description | Source |
| ------- | ------------------------------ | -------------- |
| `App` | Application name | `CDK_APP_NAME` |
| `Env` | Environment (dev, qat, prd) | `CDK_ENV` |
| `OU` | Organizational Unit | `CDK_OU` |
| `Owner` | Team or individual responsible | `CDK_OWNER` |

These tags are used for cost allocation, resource management, and identifying resources in AWS.

### Environment-Specific Settings

Different environments may require different configuration values. Consider these recommendations:

#### Development (dev)

- `CDK_APP_LOGGING_LEVEL=debug` - Verbose logging for development
- `CDK_CORS_ALLOW_ORIGIN=*` - Allow all origins for easier testing
- Use minimal resource sizes to reduce costs

#### QA Testing (qat)

- `CDK_APP_LOGGING_LEVEL=info` - Balanced logging
- `CDK_CORS_ALLOW_ORIGIN=https://qat.example.com` - Restrict to QA environment
- Use production-like resource sizes

#### Production (prd)

- `CDK_APP_LOGGING_LEVEL=warn` or `error` - Minimal logging for performance
- `CDK_CORS_ALLOW_ORIGIN=https://example.com` - Restrict to production domain
- Use appropriate resource sizes and retention policies
- Enable additional monitoring and alerting

---

## Configuration Flow

The configuration flow from infrastructure to application is as follows:

1. **Infrastructure Deployment**
- CDK reads `CDK_*` environment variables
- CDK provisions AWS resources with configured values
- Lambda functions receive environment variables from CDK configuration

2. **Application Runtime**
- Lambda functions read their environment variables
- Application config validates variables using Zod schemas
- Application uses validated configuration for runtime behavior

### Mapping: Infrastructure → Application

Infrastructure configuration variables are passed to Lambda functions with modified names:

| Infrastructure Variable | Lambda Environment Variable |
| ------------------------- | --------------------------- |
| `CDK_APP_LOGGING_ENABLED` | `LOGGING_ENABLED` |
| `CDK_APP_LOGGING_LEVEL` | `LOGGING_LEVEL` |
| `CDK_APP_LOGGING_FORMAT` | `LOGGING_FORMAT` |
| `CDK_CORS_ALLOW_ORIGIN` | `CORS_ALLOW_ORIGIN` |
| (DynamoDB table name) | `TASKS_TABLE` |
| (AWS Region) | `AWS_REGION` |

---

## Troubleshooting

### Configuration Validation Errors

If you encounter configuration validation errors:

1. **Check required variables** - Ensure all required variables are set
2. **Verify enum values** - Check that enum values match allowed options
3. **Review error messages** - Validation errors include the field name and specific issue

Example error:

```
Configuration validation failed:
LOGGING_LEVEL: Invalid enum value. Expected 'debug' | 'info' | 'warn' | 'error', received 'verbose'
```

### Environment Variable Precedence

Environment variables can be set in multiple places. The precedence order is:

1. System environment variables (highest priority)
2. `.env` file (infrastructure only)
3. Default values in schema (lowest priority)

---

## Best Practices

1. **Never commit secrets** - Use AWS Secrets Manager or Parameter Store for sensitive data
2. **Use .env for local development** - Keep local configuration separate from code
3. **Document custom variables** - Update this guide when adding new configuration options
4. **Validate early** - Use Zod schemas to catch configuration errors at startup
5. **Use environment-specific values** - Configure resources appropriately for each environment
6. **Tag all resources** - Ensure proper tagging for cost allocation and management
72 changes: 36 additions & 36 deletions docs/InfrastructureGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -307,17 +307,17 @@ The lambda-starter infrastructure uses a modular, environment-aware design:

All configuration is managed through environment variables prefixed with `CDK_`:

| Variable | Required | Description | Default |
| ------------------------ | -------- | -------------------------- | ---------------- |
| `CDK_APP_NAME` | No | Application name | `lambda-starter` |
| `CDK_ENV` | Yes | Environment | - |
| `CDK_ACCOUNT` | No | AWS account ID override | From AWS CLI |
| `CDK_REGION` | No | AWS region override | From AWS CLI |
| `CDK_OU` | No | Organizational unit | `leanstacks` |
| `CDK_OWNER` | No | Resource owner | `unknown` |
| `CDK_APP_ENABLE_LOGGING` | No | Enable application logging | `true` |
| `CDK_APP_LOGGING_LEVEL` | No | Application logging level | `info` |
| `CDK_APP_LOGGING_FORMAT` | No | Application logging format | `json` |
| Variable | Required | Description | Default |
| ------------------------- | -------- | -------------------------- | ---------------- |
| `CDK_APP_NAME` | No | Application name | `lambda-starter` |
| `CDK_ENV` | Yes | Environment | - |
| `CDK_ACCOUNT` | No | AWS account ID override | From AWS CLI |
| `CDK_REGION` | No | AWS region override | From AWS CLI |
| `CDK_OU` | No | Organizational unit | `leanstacks` |
| `CDK_OWNER` | No | Resource owner | `unknown` |
| `CDK_APP_LOGGING_ENABLED` | No | Enable application logging | `true` |
| `CDK_APP_LOGGING_LEVEL` | No | Application logging level | `info` |
| `CDK_APP_LOGGING_FORMAT` | No | Application logging format | `json` |

### Configuration Validation

Expand Down Expand Up @@ -406,9 +406,9 @@ const tableName = process.env.TASK_TABLE_NAME;
- **Bundling**: Automatic TypeScript compilation with esbuild
- **Environment Variables**:
- `TASKS_TABLE`: DynamoDB table name
- `ENABLE_LOGGING`: Logging enabled flag (from `CDK_APP_ENABLE_LOGGING`)
- `LOG_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOG_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)
- `LOGGING_ENABLED`: Logging enabled flag (from `CDK_APP_LOGGING_ENABLED`)
- `LOGGING_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOGGING_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)

**CloudWatch Logs**:

Expand Down Expand Up @@ -440,9 +440,9 @@ const tableName = process.env.TASK_TABLE_NAME;
- **Bundling**: Automatic TypeScript compilation with esbuild
- **Environment Variables**:
- `TASKS_TABLE`: DynamoDB table name
- `ENABLE_LOGGING`: Logging enabled flag (from `CDK_APP_ENABLE_LOGGING`)
- `LOG_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOG_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)
- `LOGGING_ENABLED`: Logging enabled flag (from `CDK_APP_LOGGING_ENABLED`)
- `LOGGING_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOGGING_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)

**CloudWatch Logs**:

Expand Down Expand Up @@ -474,9 +474,9 @@ const tableName = process.env.TASK_TABLE_NAME;
- **Bundling**: Automatic TypeScript compilation with esbuild
- **Environment Variables**:
- `TASKS_TABLE`: DynamoDB table name
- `ENABLE_LOGGING`: Logging enabled flag (from `CDK_APP_ENABLE_LOGGING`)
- `LOG_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOG_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)
- `LOGGING_ENABLED`: Logging enabled flag (from `CDK_APP_LOGGING_ENABLED`)
- `LOGGING_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOGGING_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)

**CloudWatch Logs**:

Expand Down Expand Up @@ -508,9 +508,9 @@ const tableName = process.env.TASK_TABLE_NAME;
- **Bundling**: Automatic TypeScript compilation with esbuild
- **Environment Variables**:
- `TASKS_TABLE`: DynamoDB table name
- `ENABLE_LOGGING`: Logging enabled flag (from `CDK_APP_ENABLE_LOGGING`)
- `LOG_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOG_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)
- `LOGGING_ENABLED`: Logging enabled flag (from `CDK_APP_LOGGING_ENABLED`)
- `LOGGING_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOGGING_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)

**CloudWatch Logs**:

Expand Down Expand Up @@ -542,9 +542,9 @@ const tableName = process.env.TASK_TABLE_NAME;
- **Bundling**: Automatic TypeScript compilation with esbuild
- **Environment Variables**:
- `TASKS_TABLE`: DynamoDB table name
- `ENABLE_LOGGING`: Logging enabled flag (from `CDK_APP_ENABLE_LOGGING`)
- `LOG_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOG_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)
- `LOGGING_ENABLED`: Logging enabled flag (from `CDK_APP_LOGGING_ENABLED`)
- `LOGGING_LEVEL`: Minimum log level (from `CDK_APP_LOGGING_LEVEL`)
- `LOGGING_FORMAT`: Log output format (from `CDK_APP_LOGGING_FORMAT`)

**CloudWatch Logs**:

Expand Down Expand Up @@ -643,37 +643,37 @@ const tableName = process.env.TASK_TABLE_NAME;

The Lambda stack uses environment variables to configure application behavior:

- **CDK_APP_ENABLE_LOGGING**: Controls whether logging is enabled in Lambda functions
- **CDK_APP_LOGGING_ENABLED**: Controls whether logging is enabled in Lambda functions
- Set to `true` (default) or `false`
- Passed to Lambda as `ENABLE_LOGGING` environment variable
- Passed to Lambda as `LOGGING_ENABLED` environment variable
- When disabled, Lambda functions produce minimal log output

- **CDK_APP_LOGGING_LEVEL**: Sets the minimum log level for application logs
- Valid values: `debug`, `info` (default), `warn`, `error`
- Passed to Lambda as `LOG_LEVEL` environment variable
- Passed to Lambda as `LOGGING_LEVEL` environment variable
- Controls verbosity of application logging

- **CDK_APP_LOGGING_FORMAT**: Sets the log output format
- Valid values: `text`, `json` (default)
- Passed to Lambda as `LOG_FORMAT` environment variable
- Passed to Lambda as `LOGGING_FORMAT` environment variable
- `json`: Structured JSON logs ideal for CloudWatch Logs Insights and log aggregation
- `text`: Human-readable text format with stringified context

**Example Usage**:

```bash
# Development with debug logging in text format
CDK_APP_ENABLE_LOGGING=true
CDK_APP_LOGGING_ENABLED=true
CDK_APP_LOGGING_LEVEL=debug
CDK_APP_LOGGING_FORMAT=text

# Production with info logging in JSON format
CDK_APP_ENABLE_LOGGING=true
CDK_APP_LOGGING_ENABLED=true
CDK_APP_LOGGING_LEVEL=info
CDK_APP_LOGGING_FORMAT=json

# Disable logging (not recommended)
CDK_APP_ENABLE_LOGGING=false
CDK_APP_LOGGING_ENABLED=false
```

### Resource Tagging
Expand Down Expand Up @@ -819,7 +819,7 @@ npm run cdk watch
# 1. Configure for dev
cat > .env << EOF
CDK_ENV=dev
CDK_APP_ENABLE_LOGGING=true
CDK_APP_LOGGING_ENABLED=true
CDK_APP_LOGGING_LEVEL=debug
EOF

Expand All @@ -841,7 +841,7 @@ CDK_ACCOUNT=123456789012
CDK_REGION=us-east-1
CDK_OU=leanstacks
CDK_OWNER=platform-team
CDK_APP_ENABLE_LOGGING=true
CDK_APP_LOGGING_ENABLED=true
CDK_APP_LOGGING_LEVEL=info
EOF

Expand All @@ -859,7 +859,7 @@ npm run deploy
export CDK_ENV=prd
export CDK_ACCOUNT=123456789012
export CDK_REGION=us-east-1
export CDK_APP_ENABLE_LOGGING=true
export CDK_APP_LOGGING_ENABLED=true
export CDK_APP_LOGGING_LEVEL=info

# Deploy without prompts
Expand Down
Loading