Zero-Downtime Blue-Green Deployment Pipelines for Laravel Applications on AWS
Architectural Overview: Blue-Green Deployments on AWS
Achieving zero-downtime deployments for a Laravel application on AWS requires a robust strategy that isolates production traffic from the deployment process. Blue-Green deployment is a pattern that addresses this by maintaining two identical production environments: “Blue” (current production) and “Green” (staging/new production). Traffic is initially directed to Blue. When a new version is ready, it’s deployed to Green. After thorough testing, a traffic switch is performed, redirecting all incoming requests from Blue to Green. This allows for instant rollback by simply switching traffic back to Blue if issues arise.
For a Laravel application, this typically involves managing:
- Application servers (e.g., EC2 instances, ECS tasks)
- Database (e.g., RDS, Aurora)
- Load Balancer (e.g., ALB)
- DNS (e.g., Route 53)
- Caching layers (e.g., ElastiCache)
- Deployment automation (e.g., CodePipeline, Jenkins, custom scripts)
Setting Up the Environments: EC2 and ALB
We’ll use AWS Elastic Compute Cloud (EC2) instances for our application servers and an Application Load Balancer (ALB) to manage traffic. The key to Blue-Green is having two distinct sets of EC2 instances, each running the same Laravel application code but potentially different versions. The ALB will have two target groups, one for each environment (Blue and Green).
First, let’s define our EC2 Auto Scaling Groups and Launch Configurations. We’ll assume you have a base AMI with your Laravel dependencies installed and your application code deployed via a CI/CD pipeline. For simplicity, we’ll use a single EC2 instance configuration, but in production, you’d leverage Auto Scaling Groups for high availability and scalability.
EC2 Launch Configuration (Conceptual)
This is a conceptual representation. In practice, you’d create this via the AWS CLI or Console, often using a user data script to pull the latest code or specific version from S3/CodeDeploy.
# Example User Data Script (Bash) #!/bin/bash # Install dependencies (if not in AMI) # sudo apt-get update -y # sudo apt-get install -y php php-cli php-fpm php-mysql ... # Fetch application code (e.g., from S3) aws s3 sync s3://your-app-bucket/laravel-app/v1.0.0 /var/www/html # Set permissions chown -R www-data:www-data /var/www/html chmod -R 755 /var/www/html # Install Composer dependencies cd /var/www/html composer install --no-dev --optimize-autoloader # Run migrations (carefully, see database section) # php artisan migrate --force # Clear cache php artisan cache:clear php artisan config:clear php artisan route:clear php artisan view:clear # Restart web server/PHP-FPM sudo systemctl restart apache2 # or nginx, php-fpm
ALB Target Groups
We need two target groups, one for the “Blue” environment and one for the “Green” environment. These target groups will point to the EC2 instances running our Laravel application.
Let’s assume your EC2 instances are in a private subnet and accessible via a security group that allows traffic from the ALB. The ALB itself will be in public subnets.
Target Group Creation (AWS CLI Example)
# Create Blue Target Group
aws elbv2 create-target-group \
--name laravel-blue-tg \
--protocol HTTP \
--port 80 \
--vpc-id vpc-xxxxxxxxxxxxxxxxx \
--target-type instance \
--health-check-protocol HTTP \
--health-check-path /health \
--healthy-threshold-count 3 \
--unhealthy-threshold-count 3 \
--timeout-seconds 5 \
--interval-seconds 30
# Create Green Target Group
aws elbv2 create-target-group \
--name laravel-green-tg \
--protocol HTTP \
--port 80 \
--vpc-id vpc-xxxxxxxxxxxxxxxxx \
--target-type instance \
--health-check-protocol HTTP \
--health-check-path /health \
--healthy-threshold-count 3 \
--unhealthy-threshold-count 3 \
--timeout-seconds 5 \
--interval-seconds 30
You’ll need to create a simple `/health` endpoint in your Laravel application (e.g., in `routes/web.php` or `routes/api.php`) that returns a 200 OK status. This is crucial for the ALB to determine if an instance is healthy.
// routes/web.php
use Illuminate\Support\Facades\Route;
Route::get('/health', function () {
// Optionally, check database connection or other critical services
try {
DB::connection()->getPdo();
return response('OK', 200);
} catch (\Exception $e) {
return response('Service Unavailable', 503);
}
});
ALB Listener Rules
Initially, the ALB listener will forward all traffic to the Blue target group. We’ll modify this rule during the deployment process.
Initial Listener Rule (AWS CLI Example)
# Assuming you have an ALB ARN and Listener ARN
ALB_ARN="arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/my-laravel-alb/xxxxxxxxxxxxxxxxx"
LISTENER_ARN="arn:aws:elasticloadbalancing:us-east-1:123456789012:listener/app/my-laravel-alb/xxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyy"
BLUE_TG_ARN=$(aws elbv2 describe-target-groups --names laravel-blue-tg --query 'TargetGroups[0].TargetGroupArn' --output text)
# Create the default rule forwarding to Blue
aws elbv2 create-rule \
--listener-arn $LISTENER_ARN \
--conditions '{"Field": "path-pattern", "Values": ["*"]}' \
--priority 1 \
--actions '{"Type": "forward", "TargetGroupArn": "'$BLUE_TG_ARN'"}'
Database Considerations for Zero-Downtime
Database schema changes are the trickiest part of zero-downtime deployments. A common strategy is to use “backward-compatible” changes. This means that a new application version can run with the old schema, and the old application version can run with the new schema. This is often achieved through phased rollouts.
Phased Migration Strategy
- Step 1: Add New Columns/Tables (No Breaking Changes): Deploy a new version of your Laravel application that *adds* new columns or tables required by the upcoming feature. This version should be able to gracefully handle the absence of these new columns if they haven’t been populated yet.
- Step 2: Deploy Code that Uses New Schema: Once the new columns/tables exist, deploy a version of your application that starts *writing* to these new columns/tables. This version must still be backward-compatible, meaning it can read from the old schema if necessary.
- Step 3: Data Migration (Optional, Background): If you need to backfill data into the new columns/tables, do this in a separate, background process that doesn’t impact application availability.
- Step 4: Remove Old Columns/Tables: Once you are confident that all application instances are running the new code and no longer rely on the old schema, deploy a version that *removes* the old columns or tables.
Laravel’s migration system can be used for this. You’ll need to carefully manage the order of migrations and potentially use multiple deployment cycles. For critical production systems, consider tools like Phinx or custom scripts that offer more granular control over migration execution and rollback.
Database Replication and Read Replicas
For read-heavy applications, consider using RDS Read Replicas. During a deployment, you can potentially direct read traffic to a replica that is being updated or to a separate replica for the Green environment, minimizing load on the primary database.
Automating the Blue-Green Deployment Pipeline
AWS CodePipeline is an excellent service for orchestrating Blue-Green deployments. We can define stages for building, testing, and deploying to the Green environment, followed by a manual approval step before switching traffic.
AWS CodePipeline Setup
A typical pipeline might look like this:
- Source Stage: Connects to your Git repository (e.g., CodeCommit, GitHub).
- Build Stage: Builds your application artifact (e.g., Docker image, ZIP archive). This might involve running Composer install, clearing caches, etc.
- Deploy to Green Stage: Deploys the artifact to the Green EC2 instances. This is where you’d use CodeDeploy or custom Lambda functions to update the Green environment.
- Test Stage: Runs automated integration and end-to-end tests against the Green environment.
- Manual Approval Stage: Pauses the pipeline for manual verification.
- Switch Traffic Stage: Updates the ALB listener rule to point to the Green target group.
- Rollback Stage (Conditional): If tests fail or manual approval is denied, the pipeline can be configured to revert changes or simply not proceed with the traffic switch.
CodeDeploy for EC2 Deployments
AWS CodeDeploy can manage the deployment of your Laravel application to the EC2 instances in the Green environment. You’ll need to configure CodeDeploy to deploy to the specific Auto Scaling Group or set of instances designated for Green.
`appspec.yml` Example for CodeDeploy
version: 0.0
os: linux
files:
- source: /
destination: /var/www/html # Your Laravel application root
hooks:
BeforeInstall:
- location: scripts/before_install.sh
timeout: 300
runas: root
AfterInstall:
- location: scripts/after_install.sh
timeout: 300
runas: root
ApplicationStart:
- location: scripts/application_start.sh
timeout: 300
runas: root
ApplicationStop:
- location: scripts/application_stop.sh
timeout: 300
runas: root
Deployment Scripts (Conceptual)
# scripts/before_install.sh #!/bin/bash # Stop web server to prevent serving stale content during deployment sudo systemctl stop apache2 # or nginx # Optional: Drain connections from ALB if using advanced CodeDeploy lifecycle hooks # This is more complex and often handled by ALB deregistration timeouts. # Clean up old files if necessary rm -rf /var/www/html/*
# scripts/after_install.sh #!/bin/bash # Copy new application files from the deployment bundle # CodeDeploy handles the file transfer based on appspec.yml # Install Composer dependencies cd /var/www/html composer install --no-dev --optimize-autoloader # Set permissions chown -R www-data:www-data /var/www/html chmod -R 755 /var/www/html # Run migrations (use with extreme caution, see database section) # php artisan migrate --force
# scripts/application_start.sh #!/bin/bash # Clear caches and restart services php /var/www/html/artisan cache:clear php /var/www/html/artisan config:clear php /var/www/html/artisan route:clear php /var/www/html/artisan view:clear # Restart web server/PHP-FPM sudo systemctl start apache2 # or nginx, php-fpm
Traffic Switching Mechanism
The critical step is switching traffic. This is done by modifying the ALB listener rule. We need to change the `TargetGroupArn` in the rule that directs traffic to the Green target group.
Switching Traffic (AWS CLI Example)
# Get the ARN of the rule currently forwarding to Blue
# You'll need to know the rule ARN or query for it.
# Assuming you have the rule ARN that forwards to Blue:
BLUE_RULE_ARN="arn:aws:elasticloadbalancing:us-east-1:123456789012:listener-rule/app/my-laravel-alb/xxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz"
GREEN_TG_ARN=$(aws elbv2 describe-target-groups --names laravel-green-tg --query 'TargetGroups[0].TargetGroupArn' --output text)
# Modify the rule to forward to Green
aws elbv2 modify-rule \
--rule-arn $BLUE_RULE_ARN \
--actions '[{"Type": "forward", "TargetGroupArn": "'$GREEN_TG_ARN'"}]'
# IMPORTANT: Ensure the Green target group is healthy BEFORE this step.
# The ALB will gradually shift traffic.
This command modifies the existing rule. A more robust approach in CodePipeline might involve: 1. Creating a *new* rule with a higher priority that forwards to Green. 2. Modifying the *default* rule (priority 1) to forward to Green. 3. Deleting the old rule that forwarded to Blue. This ensures a clean switch and simplifies rollback.
Rollback Strategy
If issues are detected after the traffic switch, rollback is as simple as reversing the traffic switch. You would modify the ALB listener rule again to point back to the Blue target group. The Blue environment, untouched during the Green deployment, is ready to receive traffic immediately.
Rolling Back Traffic (AWS CLI Example)
# Assuming you have the rule ARN that now forwards to Green:
GREEN_RULE_ARN="arn:aws:elasticloadbalancing:us-east-1:123456789012:listener-rule/app/my-laravel-alb/xxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz"
BLUE_TG_ARN=$(aws elbv2 describe-target-groups --names laravel-blue-tg --query 'TargetGroups[0].TargetGroupArn' --output text)
# Modify the rule to forward back to Blue
aws elbv2 modify-rule \
--rule-arn $GREEN_RULE_ARN \
--actions '[{"Type": "forward", "TargetGroupArn": "'$BLUE_TG_ARN'"}]'
Advanced Considerations and Best Practices
Session Management
Ensure your Laravel application uses a shared session driver (e.g., Redis, Memcached, Database) that is accessible by both Blue and Green environments. This prevents users from being logged out during the traffic switch.
Caching
Similarly, use a shared caching backend (e.g., ElastiCache for Redis/Memcached). Clear relevant caches during deployment if necessary, but avoid clearing all caches if possible, as this can impact performance.
Environment Variables
Manage environment-specific configurations carefully. Use AWS Systems Manager Parameter Store or Secrets Manager to store sensitive information and application configurations. Ensure both Blue and Green environments can access the correct configuration for their respective deployments.
Testing in Green
Thorough automated testing (unit, integration, E2E) against the Green environment before switching traffic is paramount. Consider using tools like Cypress, Selenium, or Laravel Dusk for automated browser testing. You might also perform manual smoke tests during the approval phase.
Canary Deployments
For even greater safety, consider a canary deployment strategy. Instead of switching 100% of traffic at once, gradually shift a small percentage (e.g., 1%, 5%, 10%) to the Green environment. Monitor performance and error rates closely. If everything is stable, increase the percentage until 100% of traffic is on Green. AWS ALB supports weighted target groups, which can facilitate this.
Weighted Target Groups (Conceptual)
# Example of modifying rules for weighted traffic (e.g., 90% Blue, 10% Green)
# This requires creating a new rule or modifying an existing one to have multiple actions with weights.
# Get ARNs
BLUE_TG_ARN=$(aws elbv2 describe-target-groups --names laravel-blue-tg --query 'TargetGroups[0].TargetGroupArn' --output text)
GREEN_TG_ARN=$(aws elbv2 describe-target-groups --names laravel-green-tg --query 'TargetGroups[0].TargetGroupArn' --output text)
LISTENER_ARN="arn:aws:elasticloadbalancing:us-east-1:123456789012:listener/app/my-laravel-alb/xxxxxxxxxxxxxxxxx/yyyyyyyyyyyyyyyy"
# Create a new rule with weighted targets
aws elbv2 create-rule \
--listener-arn $LISTENER_ARN \
--conditions '{"Field": "path-pattern", "Values": ["*"]}' \
--priority 2 \ # Higher priority than the default rule
--actions '[
{"Type": "forward", "TargetGroupArn": "'$BLUE_TG_ARN'", "Weight": 90},
{"Type": "forward", "TargetGroupArn": "'$GREEN_TG_ARN'", "Weight": 10}
]'
This setup requires careful management of rule priorities and weights. The full Blue-Green switch would then involve setting the weight for Blue to 0 and Green to 100.