Cursor rule

1---
2name: beanstalk-deploy
3description: "Robust deployment patterns for Elastic Beanstalk with GitHub Actions, Pulumi, and edge case handling"
4globs:
5  - "**/.github/workflows/*deploy*.yml"
6  - "**/.github/workflows/*beanstalk*.yml"
7  - "**/infra/**/*.ts"
8  - "**/infrastructure/**/*.ts"
9  - "**/Pulumi*.yaml"
10  - "**/package.json"
11alwaysApply: false
12---
13 
14# AWS Elastic Beanstalk Deployment Best Practices
15 
16Apply these production-tested patterns when working with Elastic Beanstalk deployments, especially with GitHub Actions and Pulumi infrastructure.
17 
18## 🎯 Core Principles
19 
201. **Always verify infrastructure health** before deploying
212. **Never assume resources are ready** - implement retry logic
223. **Handle terminated environments** gracefully with state cleanup
234. **Use concurrency control** to prevent deployment conflicts
245. **Pre-install dependencies** for faster, more reliable deploys
256. **Implement comprehensive error handling** with fallbacks
26 
27## 🏗️ Infrastructure Health Checks
28 
29**ALWAYS check infrastructure status before deploying:**
30 
31```yaml
32- name: Check infrastructure status
33  run: |
34    echo "🔍 Checking infrastructure status..."
35 
36    # Get environment name from Pulumi state (without deploying)
37    EB_ENVIRONMENT_NAME=$(pulumi stack output ebEnvironmentName 2>/dev/null || echo "")
38 
39    if [ -z "$EB_ENVIRONMENT_NAME" ]; then
40      echo "🔍 No environment found in Pulumi state. Will deploy infrastructure..."
41    else
42      echo "🔍 Checking environment status: $EB_ENVIRONMENT_NAME"
43 
44      # Check if environment exists and is healthy
45      EB_ENV_STATUS=$(aws elasticbeanstalk describe-environments \
46        --environment-names "$EB_ENVIRONMENT_NAME" \
47        --query "Environments[0].Status" --output text 2>/dev/null || echo "NOT_FOUND")
48 
49      if [ "$EB_ENV_STATUS" = "Terminated" ] || [ "$EB_ENV_STATUS" = "NOT_FOUND" ]; then
50        echo "⚠️  Environment is $EB_ENV_STATUS. Deleting from Pulumi state..."
51 
52        # Delete environment from Pulumi state
53        EB_URN=$(pulumi stack --show-urns | awk '/aws:elasticbeanstalk\/environment:Environment/ {print $1; exit}')
54        if [ -n "$EB_URN" ]; then
55          echo "🔧 Deleting: $EB_URN"
56          pulumi state delete "$EB_URN" --force
57        fi
58 
59        echo "🔄 Infrastructure will be recreated..."
60      else
61        echo "✅ Environment exists: $EB_ENV_STATUS"
62 
63        # Check if infrastructure changes needed
64        if pulumi preview --diff --expect-no-changes 2>/dev/null; then
65          echo "✅ No infrastructure changes needed"
66        else
67          echo "🔄 Infrastructure changes detected"
68        fi
69      fi
70    fi
71```
72 
73**Why**: Prevents deploying to orphaned resources, automatically recovers from terminated environments, saves money on zombie resources.
74 
75## ⏳ Beanstalk Readiness Verification
76 
77**ALWAYS wait for environment to be fully ready:**
78 
79```yaml
80- name: Verify Elastic Beanstalk environment exists
81  run: |
82    echo "🔍 Verifying Elastic Beanstalk environment..."
83    EB_ENVIRONMENT_NAME="${{ steps.get-resources.outputs.eb_environment_name }}"
84 
85    # Wait until environment exists
86    echo "⏳ Waiting for environment to exist..."
87    aws elasticbeanstalk wait environment-exists \
88      --environment-names "$EB_ENVIRONMENT_NAME" || true
89 
90    # Wait until environment is Ready (with 30 retries)
91    for i in {1..30}; do
92      ENV_STATUS=$(aws elasticbeanstalk describe-environments \
93        --environment-names "$EB_ENVIRONMENT_NAME" \
94        --query "Environments[0].Status" --output text 2>/dev/null || echo "NOT_FOUND")
95      ENV_HEALTH=$(aws elasticbeanstalk describe-environments \
96        --environment-names "$EB_ENVIRONMENT_NAME" \
97        --query "Environments[0].Health" --output text 2>/dev/null || echo "UNKNOWN")
98 
99      echo "⏳ EB Status: $ENV_STATUS, Health: $ENV_HEALTH (attempt $i/30)"
100 
101      if [ "$ENV_STATUS" = "Ready" ]; then
102        echo "✅ Environment is Ready"
103        break
104      fi
105      sleep 20  # Wait 20 seconds between checks (10 minutes total)
106    done
107 
108    if [ "$ENV_STATUS" != "Ready" ]; then
109      echo "⚠️  Environment not Ready after 10 minutes. Continuing with caution..."
110    fi
111```
112 
113**Why**: Prevents timing-related failures, ensures environment is provisioned before app deployment, provides visibility into provisioning progress.
114 
115## 🔒 HTTPS/SSL Configuration
116 
117**CRITICAL: Classic Load Balancer vs Application Load Balancer**
118 
119Elastic Beanstalk environments can use either Classic Load Balancer (CLB) or Application Load Balancer (ALB). The HTTPS listener configuration is **completely different** between them.
120 
121### Checking Your Load Balancer Type
122 
123```bash
124# Check load balancer type
125aws elasticbeanstalk describe-configuration-settings \
126  --environment-name <env-name> \
127  --application-name <app-name> \
128  --query 'ConfigurationSettings[0].OptionSettings[?Namespace==`aws:elasticbeanstalk:environment`]' \
129  --output json | grep LoadBalancerType
130```
131 
132**Outputs:**
133- `"Value": "classic"` → Use Classic Load Balancer config
134- `"Value": "application"` → Use Application Load Balancer config
135 
136### Classic Load Balancer HTTPS Configuration
137 
138**Use namespace: `aws:elb:listener:443`**
139 
140```typescript
141// Pulumi configuration for Classic Load Balancer
142...(certificate && certValidationComplete
143  ? [
144      {
145        namespace: "aws:elb:listener:443",
146        name: "ListenerProtocol",
147        value: "HTTPS",
148      },
149      {
150        namespace: "aws:elb:listener:443",
151        name: "InstancePort",
152        value: "80",
153      },
154      {
155        namespace: "aws:elb:listener:443",
156        name: "InstanceProtocol",
157        value: "HTTP",
158      },
159      {
160        namespace: "aws:elb:listener:443",
161        name: "SSLCertificateId",
162        value: certValidationComplete.certificateArn,
163      },
164      {
165        namespace: "aws:elb:listener:443",
166        name: "ListenerEnabled",
167        value: "true",
168      },
169    ]
170  : [])
171```
172 
173### Application Load Balancer (ALBv2) HTTPS Configuration
174 
175**Use namespace: `aws:elbv2:listener:443`**
176 
177```typescript
178// Pulumi configuration for Application Load Balancer
179...(certificate && certValidationComplete
180  ? [
181      {
182        namespace: "aws:elbv2:listener:443",
183        name: "Protocol",
184        value: "HTTPS",
185      },
186      {
187        namespace: "aws:elbv2:listener:443",
188        name: "SSLCertificateArns",
189        value: certValidationComplete.certificateArn,
190      },
191      {
192        namespace: "aws:elbv2:listener:443",
193        name: "SSLPolicy",
194        value: "ELBSecurityPolicy-TLS13-1-2-2021-06",
195      },
196    ]
197  : [])
198```
199 
200### Common Symptoms of Misconfiguration
201 
202**Problem:** `https://your-domain.com` times out or refuses connection, but `http://` works fine
203 
204**Diagnosis:**
205```bash
206# 1. Check if HTTPS listener exists
207aws elasticbeanstalk describe-configuration-settings \
208  --environment-name <env-name> \
209  --application-name <app-name> \
210  --query 'ConfigurationSettings[0].OptionSettings[?contains(Namespace, `listener`)]'
211 
212# 2. Check certificate status
213aws acm list-certificates --region <region> \
214  --query 'CertificateSummaryList[?contains(DomainName, `your-domain.com`)]'
215 
216# 3. Verify DNS resolution
217nslookup your-domain.com
218 
219# 4. Test load balancer directly
220curl -I http://<load-balancer-endpoint>/health
221```
222 
223**Root Cause:** Using `aws:elbv2:listener:443` config on a Classic Load Balancer (or vice versa)
224 
225**Fix:** Update Pulumi infrastructure code with correct namespace based on load balancer type, then run:
226```bash
227cd infrastructure
228pulumi up
229```
230 
231**Why**: Mixing Classic and ALBv2 configuration namespaces silently fails - the HTTPS listener is never created, leaving port 443 closed while the environment appears healthy.
232 
233See full documentation for complete deployment patterns, Pulumi configuration, monitoring, and production checklist.