The Definitive Guide to Managing Dev & Prod Environments in AWS Serverless

Introduction

When building serverless applications on AWS, managing different environments (development, staging, and production) is crucial for maintaining a robust development lifecycle. This comprehensive guide will walk you through setting up and managing development and production environments using AWS Lambda and API Gateway.

Prerequisites

• AWS Account with appropriate permissions
• Basic understanding of AWS Lambda and API Gateway
• AWS CLI installed and configured
• Basic Node.js knowledge

Step 1: Initial Lambda Function Setup

1.1 Creating the Lambda Function

1. Navigate to Lambda Console
2. Click “Create function”
3. Choose “Author from scratch”
4. Configure basic settings:

• Function name: myServiceFunction
• Runtime: Node.js 20.x
• Architecture: x86_64 or arm64
• Select the IAM role (if created earlier) or keep the default execution role to ‘Create a new role with basic Lambda permissions’

1.1 Creating the Lambda function

1.2 Implementing Environment-Aware Code

exports.handler = async (event) => {
    try {
        // Validate stage variables
        if (!event.stageVariables || !event.stageVariables.aws_env) {
            throw new Error('Stage variable aws_env is not configured');
        }
        
        const aws_env = event.stageVariables.aws_env;
        
        // Configure environment-specific resources
        let t_user_details;
        if (aws_env === "dev") {
            t_user_details = process.env.TABLE_USER_DETAILS_DEV;
        } else if (aws_env === "prod") {
            t_user_details = process.env.TABLE_USER_DETAILS_PROD;
        } else if (aws_env === "staging") {
            // Similarly add details for staging environment too
        } else {
            throw new Error(`Invalid environment: ${aws_env}`);
        }
        
        // Add logging for debugging
        console.log('Environment:', aws_env);
        console.log('Table:', t_user_details);
        
        // Your function logic here
        const response = {
            statusCode: 200,
            body: JSON.stringify({
                message: `Running in ${aws_env} environment`,
                tableUsed: t_user_details
            }),
        };
        return response;
        
    } catch (error) {
        console.error('Error:', error);
        return {
            statusCode: 500,
            body: JSON.stringify({
                message: 'Internal server error',
                errorDetails: process.env.aws_env === 'dev' ? error.message : undefined
            })
        };
    }
};

1.3 Setting Up Environment Variables

1. Navigate to Configuration → Environment variables
2. Add the following variables:

• TABLE_USER_DETAILS_DEV = user-details-dev
• TABLE_USER_DETAILS_PROD = user-details-prod

Note: Environment variables are:

• Encrypted at rest using AWS KMS
• Available during function execution
• Specific to each version when published

The above variables are just examples of how different table names could be called based on different environments.

1.3 Setting Up Environment Variables

Step 2: Version Management and Aliases

2.1 Understanding Lambda Versions

Lambda versions are immutable snapshots of your function, including:

• Function code
• Configuration (memory, timeout, etc.)
• Environment variables
• Lambda layers
• Function description

Key points about versioning:

• $LATEST is always the latest code
• Published versions get numeric IDs (1, 2, 3, etc.)
• Each version has a unique ARN
• Versions are immutable — cannot be changed once published

2.2 Publishing Versions

1. Test your function thoroughly
2. Navigate to Version → Publish new version
3. Add a description of changes, as shown below, and click “Publish”

Version 1:
- Initial production release
- Basic CRUD operations
- Environment variable support

2.2 Publishing Versions

2.3 Creating and Managing Aliases

Create aliases for each environment:

1. Go to “Aliases” tab
2. Click “Create alias”
3. Set up the following:

For Development:

Name: dev
Description: Development environment
Version: $LATEST

For Staging:

Name: staging
Description: Staging environment
Version: (specific version number)

For Production:

Name: prod
Description: Production environment
Version: (specific version number)
Additional configuration: 
- Enable weighted alias for blue-green deployment (optional)
- Configure routing additional version (optional)

2.3 Creating and Managing Aliases

2.4 Best Practices for Version Management

Version Promotion Strategy:

• Test thoroughly in dev ($LATEST)
• Publish new version
• Point staging alias to new version
• Test in staging
• Update prod alias after validation

Rollback Strategy:

• Keep previous version ARN documented
• Update alias to point to previous version if needed
• Maintain deployment history

Monitoring Considerations:

• Set up separate CloudWatch alarms for each alias
• Monitor error rates and duration metrics
• Configure X-Ray tracing for detailed analysis

Step 3: API Gateway Configuration

3.1 Creating the API Resource

• Navigate to API Gateway
• Create a new REST API

• Create a new resource and method

• Configure the Lambda integration

Choose the Lambda function for integration created above

3.2 Configuring Lambda Integration

• Edit the Integration Request

• In the Lambda Function field, modify the ARN to include stage variables and add :${stageVariables.aws_env}at the end

3.3 Setting Up IAM Permissions

• As soon as you add the above, you will see the below permission command. Copy this full command and take it into an editor (Notepad, VS Code, etc.)

• Modify this full command so as to change ${stageVariables.aws_env} to dev, staging, and prod based upon your environments and aliases created above.
• Run each of this AWS CLI commands in CloudShell to grant necessary permissions:

# For development environment (Example Only)
aws lambda add-permission \
    --function-name "arn:aws:lambda:us-east-1:92178:function:myLamdaFunction:dev" \
    --source-arn "arn:aws:execute-api:us-east-1:92178:api-id/*/HTTP-METHOD/resource-path" \
    --principal apigateway.amazonaws.com \
    --statement-id unique-statement-id \
    --action lambda:InvokeFunction

3.4 Deploying the API

1. Select your API resource
2. Click “Actions” → “Deploy API”
3. Select the target stage or set up a new one, preferably “development”.
4. Repeat for each stage

3.5 Creating API Stages

1. Go to Stages in API Gateway
2. Create three stages: dev, staging, and prod
3. For each stage, add a stage variable:

• Name: aws_env
• Value: dev/staging/prod (respective to the stage)

Step 4: Testing the Setup

4.1 Testing Different Environments

Test your API endpoints using the different stage URLs:

If created properly, it should look something like below:
Development:
https://api-id.execute-api.region.amazonaws.com/dev/resource-path
Staging:
https://api-id.execute-api.region.amazonaws.com/staging/resource-path
Production:
https://api-id.execute-api.region.amazonaws.com/prod/resource-path

Coming Next: AWS Cognito Integration

In the next part of this series, we’ll cover how to:

• Set up separate Cognito user pools for dev and prod environments
• Integrate Cognito with our existing API Gateway setup
• Manage user authentication across different environments

Best Practices and Considerations

1. Version Control: Always version your Lambda functions before deploying to production
2. Environment Variables: Keep environment-specific configurations in environment variables
3. Testing: Thoroughly test changes in dev and staging before promoting to production
4. Monitoring: Set up separate CloudWatch alarms and metrics for each environment
5. Access Control: Implement strict IAM policies to control who can deploy to different environments

Troubleshooting Common Issues

Permission Issues

• Verify IAM roles and policies
• Check Lambda execution role permissions
• Ensure API Gateway has permission to invoke Lambda

Stage Variable Problems

• Confirm stage variables are properly set
• Verify Lambda alias exists
• Check API Gateway logs for any integration errors

Deployment Issues

• Clear API Gateway cache if changes aren’t reflecting
• Verify correct Lambda version is associated with aliases
• Check CloudWatch logs for detailed error messages

Conclusion

This setup provides a robust foundation for managing multiple environments in your AWS serverless architecture. By following these steps, you can maintain separate development, staging, and production environments while ensuring proper isolation and configuration management.

Remember to always follow AWS best practices for security and resource management, and regularly review and update your configurations as your application evolves.

Resources

• AWS Lambda Documentation
• API Gateway Documentation
• AWS CLI Reference

Hey there! I’m Parth Amin, an AWS Certified Solutions Architect Associate with a passion for cloud architecture and AI innovation. During the week, I help drive tech modernization initiatives as a Senior Consultant at Cognizant, where I guide enterprises through their cloud transformation journeys and manage large-scale migrations.

On weekends, you’ll find me building thisorthis.ai — a platform I created to help people compare responses from multiple AI models side by side. If you’ve ever wondered which AI model works best for your specific needs, this tool lets you test them simultaneously, saving you valuable time and effort.

If you found this guide helpful, I’d love to connect with you on LinkedIn! Please feel free to share this guide with your network — knowledge grows by sharing, and I’m always excited to help fellow developers build better cloud solutions.

Want to discuss AWS architectures, AI implementations, or tech modernization? Let’s connect and explore ideas together!