From 873fe68fab4cd84edc7df8f7d7c281fbbe92f678 Mon Sep 17 00:00:00 2001 From: Paul Pollack Date: Thu, 14 May 2026 17:48:07 -0400 Subject: [PATCH 1/4] feat(deploy-on-aws): add Elastic Beanstalk skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a new elastic-beanstalk skill to the deploy-on-aws plugin covering Elastic Beanstalk on EC2 for web and worker applications. EB is positioned as an application management service (AWS manages lifecycle) vs ECS/EKS as infrastructure management services (user manages lifecycle). New files: - skills/elastic-beanstalk/SKILL.md — routing, workflow, defaults - skills/elastic-beanstalk/references/platforms.md — platform detection - skills/elastic-beanstalk/references/configuration.md — ebextensions, hooks Modified existing files: - defaults.md — override triggers and Heroku migration row - security.md — VPC, SG, IAM, logging entries for EB - cost-estimation.md — EB pricing (free service, underlying costs) - deploy SKILL.md — principle and reference link Co-Authored-By: Claude Opus 4.6 --- plugins/deploy-on-aws/skills/deploy/SKILL.md | 2 + .../deploy/references/cost-estimation.md | 24 +++ .../skills/deploy/references/defaults.md | 22 ++- .../skills/deploy/references/security.md | 29 ++-- .../skills/elastic-beanstalk/SKILL.md | 160 ++++++++++++++++++ .../references/configuration.md | 104 ++++++++++++ .../elastic-beanstalk/references/platforms.md | 49 ++++++ 7 files changed, 374 insertions(+), 16 deletions(-) create mode 100644 plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md create mode 100644 plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md create mode 100644 plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md diff --git a/plugins/deploy-on-aws/skills/deploy/SKILL.md b/plugins/deploy-on-aws/skills/deploy/SKILL.md index 29ac7b1c..894e28ef 100644 --- a/plugins/deploy-on-aws/skills/deploy/SKILL.md +++ b/plugins/deploy-on-aws/skills/deploy/SKILL.md @@ -57,9 +57,11 @@ to ensure patterns follow AWS recommendations. - Don't ask "Lambda or Fargate?" - just pick the obvious one - If genuinely ambiguous, then ask - **Never recommend AWS App Runner** — it is in maintenance mode. Use ECS Express Mode instead. +- When user explicitly requests a managed application platform or signals low infrastructure involvement, route to Elastic Beanstalk ## References - [Service defaults](references/defaults.md) - [Security defaults](references/security.md) - [Cost estimation patterns](references/cost-estimation.md) +- [Elastic Beanstalk skill](../elastic-beanstalk/SKILL.md) diff --git a/plugins/deploy-on-aws/skills/deploy/references/cost-estimation.md b/plugins/deploy-on-aws/skills/deploy/references/cost-estimation.md index 51a457f5..6bf085ca 100644 --- a/plugins/deploy-on-aws/skills/deploy/references/cost-estimation.md +++ b/plugins/deploy-on-aws/skills/deploy/references/cost-estimation.md @@ -25,6 +25,7 @@ Use the **awspricing** MCP server to get accurate cost estimates before generati | Lambda | `AWSLambda` | Requests and duration | | DynamoDB | `AmazonDynamoDB` | On-demand or provisioned | | Secrets Manager | `AWSSecretsManager` | Per secret per month | +| Elastic Beanstalk | N/A (free service) | No EB charge; query EC2, AWSELB for actual costs | ## Fargate Pricing @@ -70,6 +71,19 @@ storage (GB-month), and I/O (standard config only). - ~$130-400/month depending on load +## Elastic Beanstalk Pricing + +Elastic Beanstalk itself has no service fee. Cost equals the underlying AWS +resources provisioned for the environment (EC2, ELB, EBS, CloudWatch). +Query awspricing MCP server for region-accurate estimates. Approximate +us-east-1 pricing: + +**Dev web (1x t3.small + ALB):** ~$35-40/month +**Dev worker (1x t3.small, no ALB):** ~$15-20/month +**Production web (4x t3.medium + ALB, Multi-AZ):** ~$150-200/month + +Include EBS volume costs (8GB gp3 default: ~$1/month per instance). + ## Quick Reference Estimates **Small web app (Fargate + Aurora Serverless v2 + ALB):** @@ -97,6 +111,16 @@ storage (GB-month), and I/O (standard config only). - Low traffic: ~$5-20/month - High traffic: scales with requests +**Web app on Elastic Beanstalk:** + +- Dev (1 instance + ALB): ~$35-40/month +- Production (load-balanced, Multi-AZ): ~$80-200/month + +**Web app on EB + Aurora Serverless v2:** + +- Dev: ~$80-130/month +- Production: ~$200-400/month + ## Presenting Estimates Always show: diff --git a/plugins/deploy-on-aws/skills/deploy/references/defaults.md b/plugins/deploy-on-aws/skills/deploy/references/defaults.md index 60f77ceb..c46b182d 100644 --- a/plugins/deploy-on-aws/skills/deploy/references/defaults.md +++ b/plugins/deploy-on-aws/skills/deploy/references/defaults.md @@ -6,11 +6,12 @@ Default AWS service selections. Override only when user explicitly requests alte | App Pattern | Default | Override Trigger | | ----------------------------------------------------- | -------------------- | ---------------------------------------- | -| Web framework (Django, Rails, Express, FastAPI, etc.) | Fargate + ALB | "serverless" → Lambda + API Gateway | +| Web framework (Django, Rails, Express, FastAPI, etc.) | Fargate + ALB | "serverless" → Lambda + API Gateway; "managed platform" or "Elastic Beanstalk" → Elastic Beanstalk | | Static site / SPA | Amplify Hosting | "S3" or "more control" → S3 + CloudFront | -| Background workers | Fargate | Short tasks (<15min) → Lambda | +| Background workers | Fargate | Short tasks (<15min) → Lambda; "managed platform" or "Elastic Beanstalk" → Elastic Beanstalk (Worker) | | Scheduled jobs | EventBridge + Lambda | Long-running → EventBridge + Fargate | -| API-only (no web UI) | Fargate + ALB | "serverless" → API Gateway + Lambda | +| API-only (no web UI) | Fargate + ALB | "serverless" → API Gateway + Lambda; "managed platform" or "Elastic Beanstalk" → Elastic Beanstalk | +| Existing Heroku/Render/Railway app migrating to AWS | Elastic Beanstalk | "container orchestration" or "ECS" → Fargate + ALB; "serverless" → Lambda | > **⚠️ App Runner is in maintenance mode** — AWS has moved App Runner to maintenance mode. Do **not** recommend App Runner for new workloads. Use **ECS Express Mode** instead. @@ -30,6 +31,13 @@ or has existing CloudFront infrastructure. Use `amplify_docs` topic in awsknowledge MCP for framework-specific guidance (React, Next.js, Vue, Angular, etc.). +### Why Elastic Beanstalk for managed platform deployments + +Elastic Beanstalk is an application management service: the user provides code, +AWS manages deployments, scaling, patching, monitoring, and health response. +Choose when the user wants production-grade reliability with the lowest ongoing +maintenance cost. Choose Fargate when the user wants direct container control. + ## Database | Data Pattern | Default (Dev) | Default (Prod) | Override Trigger | @@ -83,9 +91,11 @@ type safety without requiring Python/Java knowledge. If user's repo already has | Component | Dev | Production | | ----------------- | ------------- | -------------- | -| Fargate | 0.5 vCPU, 1GB | 1+ vCPU, 2+ GB | -| Aurora Serverless | 0.5-2 ACU | 2-16+ ACU | -| ALB | Single AZ OK | Multi-AZ | +| Fargate | 0.5 vCPU, 1GB | 1+ vCPU, 2+ GB | +| Aurora Serverless | 0.5-2 ACU | 2-16+ ACU | +| ALB | Single AZ OK | Multi-AZ | +| Elastic Beanstalk (web) | 1x t3.small + ALB | 2-4x t3.medium + ALB, Multi-AZ | +| Elastic Beanstalk (worker) | 1x t3.small | 2-4x t3.medium | Default to **dev sizing** unless user says "production", "prod", or "production-ready". diff --git a/plugins/deploy-on-aws/skills/deploy/references/security.md b/plugins/deploy-on-aws/skills/deploy/references/security.md index 7da9e513..bf7870bf 100644 --- a/plugins/deploy-on-aws/skills/deploy/references/security.md +++ b/plugins/deploy-on-aws/skills/deploy/references/security.md @@ -58,11 +58,13 @@ When serving static content via CloudFront: | Component | Default (Dev) | Default (Prod) | | ----------------- | -------------------------------- | -------------------------------- | -| Fargate tasks | Private subnet + NAT Gateway | Private subnet + NAT Gateway | -| ALB | Public subnet | Public subnet | -| RDS/Aurora | Private subnet (no public IP) | Private subnet (no public IP) | -| Amazon DocumentDB | Private subnet (no public IP) | Private subnet (no public IP) | -| Lambda | VPC-attached if DB access needed | VPC-attached if DB access needed | +| Fargate tasks | Private subnet + NAT Gateway | Private subnet + NAT Gateway | +| ALB | Public subnet | Public subnet | +| RDS/Aurora | Private subnet (no public IP) | Private subnet (no public IP) | +| Amazon DocumentDB | Private subnet (no public IP) | Private subnet (no public IP) | +| Lambda | VPC-attached if DB access needed | VPC-attached if DB access needed | +| EB web instances | Private subnet + ALB in public | Private subnet + ALB in public | +| EB worker instances | Private subnet + NAT Gateway | Private subnet + NAT Gateway | ### Why private subnets for compute @@ -82,6 +84,8 @@ Use `awsknowledge` topic `vpc_patterns` for multi-AZ production layouts. | Service-linked roles | Use AWS-managed where available | | Cross-service access | Via IAM roles, never access keys | | Admin access | Not created (user manages separately) | +| EB instance profile | Least privilege (S3 for deploys, CloudWatch, ECR if Docker) | +| EB service role | AWS-managed (aws-elasticbeanstalk-service-role) | ### Principle: Explicit grants only @@ -95,11 +99,14 @@ Consult `awsiac` MCP for IAM policy patterns by service. | Component | Default Inbound | Default Outbound | | ----------------- | ---------------------------- | ------------------ | -| ALB | 443 from 0.0.0.0/0 | Fargate SG only | -| Fargate | ALB SG only (on app port) | 443 (HTTPS), DB SG | -| RDS/Aurora | Fargate SG only (on DB port) | None | -| Amazon DocumentDB | Fargate SG only (port 27017) | None | -| Lambda (VPC) | None | 443, DB SG | +| ALB | 443 from 0.0.0.0/0 | Fargate SG only | +| Fargate | ALB SG only (on app port) | 443 (HTTPS), DB SG | +| RDS/Aurora | Fargate SG only (on DB port) | None | +| Amazon DocumentDB | Fargate SG only (port 27017) | None | +| Lambda (VPC) | None | 443, DB SG | +| EB ALB | 443 from 0.0.0.0/0 | EB instances SG only | +| EB web instances | EB ALB SG only (on app port) | 443 (HTTPS), DB SG | +| EB worker instances | None (EB health agent is local) | 443 (HTTPS), DB SG | ### Why deny-by-default @@ -165,6 +172,8 @@ Before deployment, run available checks: | RDS/Aurora logs | Error log only | Error + slow query + audit | | Amazon DocumentDB logs | Profiler (slow ops) | Profiler + audit | | S3 Access Logs | Disabled | Enabled | +| EB application logs | CloudWatch Logs agent | CloudWatch Logs + enhanced health | +| EB platform logs | Disabled | Enabled (CloudWatch Logs) | ### Why minimal logging in dev diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md new file mode 100644 index 00000000..d2c05d27 --- /dev/null +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md @@ -0,0 +1,160 @@ +--- +name: elastic-beanstalk +description: "Deploy to AWS Elastic Beanstalk. Triggers on: elastic beanstalk, EB, managed EC2 platform, web app with managed patching, worker on EC2, Heroku alternative, don't want to manage servers or containers, migrate from Heroku, managed operational lifecycle. Covers Elastic Beanstalk on EC2 for web and worker applications." +--- + +# Elastic Beanstalk + +Deploy web and worker applications to production on AWS with full lifecycle +management. Elastic Beanstalk is an application management service: the user +provides application code, AWS manages everything underneath (deployment, scaling, +patching, monitoring, health response). + +## When to Use + +Elastic Beanstalk is the right choice when: + +- User explicitly asks for Elastic Beanstalk, EB, or a managed application platform +- User says "don't want to manage servers", "managed patching", or "Heroku-like" +- User is migrating from Heroku, Render, or Railway +- User wants AWS to manage ongoing operational lifecycle (patching, scaling, + health monitoring, rollback, deployments) after initial setup +- App is a web framework, API, or background worker on a standard runtime and + the user signals low infrastructure involvement + +Elastic Beanstalk is NOT the right choice when: + +- User explicitly wants serverless/Lambda (event-driven, scale-to-zero) +- User wants fine-grained container orchestration control (use ECS) +- User already has Kubernetes expertise and wants direct K8s access (use EKS) +- App is a static site or SPA (use Amplify Hosting for the frontend; deploy the + backend API separately if present) +- User already has ECS task definitions or Fargate configuration + +## Key Distinction + +ECS and EKS are infrastructure management services: the user defines and +operates the deployment infrastructure (task definitions, services, clusters, +scaling policies) and owns ongoing operational decisions. Elastic Beanstalk is +an application management service: the user provides source code or a Docker +image, and AWS provisions and operates the production environment on an ongoing +basis. The result is the same reliability, but with lower ongoing maintenance +cost because operational responsibility stays with the provider. + +Both models support IaC (CDK, CloudFormation, Terraform). The distinction is not +about tooling — it is about who manages the lifecycle after deployment. + +## Workflow + +This skill is invoked after the deploy skill selects Elastic Beanstalk as the +deployment target. The deploy skill handles codebase analysis and cost estimation. +This skill handles EB-specific configuration: + +1. **Map to platform** - Select the EB platform branch (see [platforms](references/platforms.md)) +2. **Configure** - Environment type (web server or worker), instance size, scaling +3. **Generate** - EB CLI project, CDK, or Terraform (see IaC section below) +4. **Deploy** - `eb create` or CDK/Terraform deploy with user confirmation + +## Defaults + +| Setting | Dev | Production | +| --- | --- | --- | +| Environment type (web) | Load-balanced (min=1, max=1) | Load-balanced, Multi-AZ | +| Environment type (worker) | Auto Scaling group (min=1, max=1) | Auto Scaling group (min=2, max=4) | +| Instance | t3.small | t3.medium or larger | +| Deployments | All-at-once | Rolling with additional batch | +| Health reporting | Enhanced | Enhanced | +| Managed updates | Enabled (weekly) | Enabled (maintenance window) | +| HTTPS (web only) | ACM certificate + ALB | ACM certificate + ALB | + +Default to **dev** unless user says "production" or "prod." + +Always use load-balanced environments for web server types. This ensures +instances stay in private subnets behind an ALB, HTTPS terminates via ACM +automatically, and scaling up later is a config change rather than an environment +type migration. Dev deployments with min=max=1 cause brief downtime on deploy +(single instance, all-at-once). If zero-downtime dev is needed, use min=1 max=2 +with rolling. + +Worker environments do not have load balancers — they receive work from SQS and +are scaled via Auto Scaling group settings. + +## Environment Types + +| Signal in Codebase | Environment Type | +| --- | --- | +| HTTP listener, web framework, API routes | Web server | +| Queue-based consumer, SQS processing, no HTTP serving | Worker | +| HTTP serving + queue-based background processing | Web server + separate Worker environment | + +Worker environments receive work via an SQS queue managed by Elastic Beanstalk. +EB's SQS daemon sends HTTP POST requests to the application at a configurable +path (default: `POST /`). The application must expose this HTTP endpoint to +process each message — no SQS SDK integration required. + +Worker environments also support periodic tasks via `cron.yaml` for scheduled +jobs (alternative to EventBridge + Lambda when the user is already using EB). + +If the app uses in-process background threads or async tasks (not queue-based), +a single web server environment is sufficient — do not create a separate Worker. + +## IaC Generation + +**Default: EB CLI** when the user wants the fastest path to production or has no +existing IaC project: + +- `eb init --region ` (creates `.elasticbeanstalk/config.yml`) +- `eb create --elb-type application` (web server environments) +- `eb create --tier worker` (worker environments) +- Subsequent deployments: `eb deploy` +- `.ebextensions/` and platform hooks for customization + +**Override: CDK (TypeScript)** when the user has an existing CDK project, wants +repeatable IaC, or explicitly requests it: + +- `CfnApplication` +- `CfnEnvironment` +- `CfnConfigurationTemplate` + +**Override: Terraform** when the user's repo already has Terraform: + +- `aws_elastic_beanstalk_application` +- `aws_elastic_beanstalk_environment` + +CDK and Terraform templates are scannable by `cfn-nag`/`checkov` pre-deploy. +EB CLI deployments enforce security via the option settings configured in +`.ebextensions/` and the defaults in this skill. + +## Security + +Apply these automatically: + +- Web server instances in private subnets behind ALB +- Worker instances in private subnets with NAT Gateway for outbound +- HTTPS via ACM certificate on ALB (web server environments) +- IAM instance profile with least-privilege permissions +- Enhanced health reporting enabled +- Managed platform updates enabled +- Security groups: ALB accepts 443, instances accept only from ALB + +See the deploy skill's [security defaults](../deploy/references/security.md) +for encryption, VPC placement, and IAM patterns. + +## Cost + +Elastic Beanstalk has no service fee. Cost = underlying AWS resources. +Query the awspricing MCP server for region-accurate estimates. Approximate +us-east-1 pricing: + +| Configuration | Estimated Monthly Cost | +| --- | --- | +| Dev web (1x t3.small + ALB) | ~$35-40 | +| Dev worker (1x t3.small, no ALB) | ~$15-20 | +| Production web (4x t3.medium + ALB, Multi-AZ) | ~$150-200 | + +Add RDS/Aurora costs separately if database is included. + +## References + +- [Supported platforms and detection](references/platforms.md) +- [Configuration and customization](references/configuration.md) diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md new file mode 100644 index 00000000..1418b54e --- /dev/null +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md @@ -0,0 +1,104 @@ +# Configuration and Customization + +## Configuration Hierarchy + +Elastic Beanstalk configuration is applied in this order (later overrides earlier +for option settings): + +1. Platform defaults (managed by AWS) +2. Saved configurations (reusable templates) +3. `.ebextensions/*.config` files (in source bundle) +4. Platform hooks (`/platform/hooks/prebuild/`, `predeploy/`, `postdeploy/`) +5. Environment properties (set via console/CLI/API) + +For option settings, later sources override earlier ones. `.ebextensions` and +platform hooks also support resource declarations and deploy-time commands that +are not expressible as option settings. + +Platform hooks are the preferred customization mechanism on AL2023. Use +`.ebextensions/` for option settings and resource declarations; use platform +hooks for shell scripts that run during deployment lifecycle. + +## `.ebextensions/` Patterns + +Place YAML `.config` files in `.ebextensions/` at the source bundle root. +Common patterns: + +### Install system packages + +```yaml +packages: + yum: + ImageMagick: [] + postgresql-devel: [] +``` + +### Run commands on deploy + +```yaml +container_commands: + 01_migrate: + command: "python manage.py migrate --noinput" + leader_only: true +``` + +Use `leader_only: true` for commands that should run on only one instance +(database migrations, cache warmup). + +## Procfile + +Define the process to run. EB uses this instead of platform defaults: + +``` +web: gunicorn myapp.wsgi --bind 0.0.0.0:8000 +``` + +For worker environments, the Procfile defines the HTTP server that receives +SQS daemon POST requests (not a queue consumer like Celery — EB Workers use +HTTP, not a message broker SDK). + +## Environment Properties and Secrets + +Set application configuration as environment variables. Never hardcode secrets +in `.ebextensions/` or source code. Reference secrets via Secrets Manager: + +```yaml +option_settings: + aws:elasticbeanstalk:application:environment: + DB_SECRET_ARN: arn:aws:secretsmanager:us-east-1:123456789:secret:myapp/db + APP_ENV: production +``` + +The application reads the secret value at runtime using the Secrets Manager SDK. +Provision databases and secrets as separate resources (via CDK, Terraform, or +console) — not coupled to the EB environment lifecycle. + +## Deployment Policies + +| Policy | Use Case | Downtime | +| --- | --- | --- | +| All at once | Dev environments | Yes | +| Rolling | Production, cost-sensitive | No (partial capacity) | +| Rolling with additional batch | Production, full capacity | No | +| Immutable | Production, safest | No | + +Default: All at once for dev, Rolling with additional batch for production. + +## Health Check Configuration + +```yaml +option_settings: + aws:elasticbeanstalk:environment:process:default: + HealthCheckPath: /health + HealthCheckInterval: '15' + HealthyThresholdCount: '3' + UnhealthyThresholdCount: '5' +``` + +Always configure a dedicated health check endpoint. Do not use `/` if it +performs database queries or heavy computation. + +The agent should verify that the application exposes a health check endpoint +(default: `/health`). If no health route exists, scaffold a minimal one that +returns 200 OK. The ALB health check will fail without this, causing deployment +to roll back. diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md new file mode 100644 index 00000000..d5ea297c --- /dev/null +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md @@ -0,0 +1,49 @@ +# Supported Platforms + +These rules apply after Elastic Beanstalk has been selected as the deployment +target by the deploy skill. + +Detect the application's language and framework, then map to an EB platform branch. + +## Platform Detection + +| Signal in Codebase | EB Platform | Notes | +| --- | --- | --- | +| `requirements.txt`, `Pipfile`, `pyproject.toml` | Python on AL2023 | Django, Flask, FastAPI | +| `package.json` (backend Node.js) | Node.js on AL2023 | Express, NestJS, Fastify, Hono | +| `pom.xml`, `build.gradle`, `.jar`/`.war` | Corretto on AL2023 | Spring Boot, Quarkus | +| `Gemfile`, `config.ru` | Ruby on AL2023 | Rails, Sinatra | +| `go.mod` | Go on AL2023 | Any Go HTTP server | +| `*.csproj`, `*.sln` (ASP.NET Core) | .NET on AL2023 | ASP.NET Core on Linux | +| `*.csproj`, `*.sln` (.NET Framework) | .NET on Windows Server | IIS, .NET Framework 4.x | +| `composer.json` | PHP on AL2023 | Laravel, Symfony | +| `Dockerfile` | Docker on AL2023 | Any containerized app | + +## Platform Selection Rules + +1. If `Dockerfile` exists AND a language runtime is also detected, prefer the + language platform unless the Dockerfile adds system dependencies not available + in the managed platform. +2. If multiple languages detected, prefer Docker platform. +3. Always use Amazon Linux 2023 unless the app requires Windows (.NET Framework, + IIS dependencies). +4. For Java apps: if `.war` file, deploy to Tomcat platform. If `.jar` with + embedded server (Spring Boot), use Corretto platform. +5. Always use the latest supported runtime version unless the application + specifies a version constraint (e.g., `engines` in `package.json`, + `` in `.csproj`). + +## Supported Deployment Artifacts + +| Platform | Accepted Input | +| --- | --- | +| Language platforms | Source bundle (zip of source code) | +| Docker | Source bundle containing Dockerfile | +| Docker (pre-built) | Dockerfile with `FROM` referencing ECR/registry image | + +## Worker Platform Considerations + +Worker environments use the same platforms as web server environments. The +difference is the SQS daemon that delivers messages to the application over HTTP +on `localhost`. The application must expose an HTTP endpoint (default: `POST /`) +that processes each message. From f648eb92b4a6e490e2dbaee006ffabad33bcc12f Mon Sep 17 00:00:00 2001 From: Paul Pollack Date: Tue, 19 May 2026 15:42:47 -0400 Subject: [PATCH 2/4] style: fix table alignment to pass markdownlint and dprint checks --- .../deploy/references/cost-estimation.md | 28 ++++---- .../skills/deploy/references/defaults.md | 26 +++---- .../skills/deploy/references/security.md | 72 +++++++++---------- .../skills/elastic-beanstalk/SKILL.md | 36 +++++----- .../references/configuration.md | 12 ++-- .../elastic-beanstalk/references/platforms.md | 30 ++++---- 6 files changed, 102 insertions(+), 102 deletions(-) diff --git a/plugins/deploy-on-aws/skills/deploy/references/cost-estimation.md b/plugins/deploy-on-aws/skills/deploy/references/cost-estimation.md index 6bf085ca..dbdf30c8 100644 --- a/plugins/deploy-on-aws/skills/deploy/references/cost-estimation.md +++ b/plugins/deploy-on-aws/skills/deploy/references/cost-estimation.md @@ -11,20 +11,20 @@ Use the **awspricing** MCP server to get accurate cost estimates before generati ## Service Codes -| Service | Code | Notes | -| ----------------- | ------------------- | ---------------------------------------------- | -| Fargate | `AmazonECS` | Filter by `usagetype` containing "Fargate" | -| Aurora PostgreSQL | `AmazonRDS` | Filter: `databaseEngine` = "Aurora PostgreSQL" | -| Aurora MySQL | `AmazonRDS` | Filter: `databaseEngine` = "Aurora MySQL" | -| RDS PostgreSQL | `AmazonRDS` | Filter: `databaseEngine` = "PostgreSQL" | -| Amazon DocumentDB | `AmazonDocDB` | MongoDB-compatible managed database | -| ALB | `AWSELB` | Application Load Balancer | -| S3 | `AmazonS3` | Storage and requests | -| CloudFront | `AmazonCloudFront` | CDN distribution | -| Amplify | `AWSAmplify` | Hosting, build minutes | -| Lambda | `AWSLambda` | Requests and duration | -| DynamoDB | `AmazonDynamoDB` | On-demand or provisioned | -| Secrets Manager | `AWSSecretsManager` | Per secret per month | +| Service | Code | Notes | +| ----------------- | ------------------- | ------------------------------------------------ | +| Fargate | `AmazonECS` | Filter by `usagetype` containing "Fargate" | +| Aurora PostgreSQL | `AmazonRDS` | Filter: `databaseEngine` = "Aurora PostgreSQL" | +| Aurora MySQL | `AmazonRDS` | Filter: `databaseEngine` = "Aurora MySQL" | +| RDS PostgreSQL | `AmazonRDS` | Filter: `databaseEngine` = "PostgreSQL" | +| Amazon DocumentDB | `AmazonDocDB` | MongoDB-compatible managed database | +| ALB | `AWSELB` | Application Load Balancer | +| S3 | `AmazonS3` | Storage and requests | +| CloudFront | `AmazonCloudFront` | CDN distribution | +| Amplify | `AWSAmplify` | Hosting, build minutes | +| Lambda | `AWSLambda` | Requests and duration | +| DynamoDB | `AmazonDynamoDB` | On-demand or provisioned | +| Secrets Manager | `AWSSecretsManager` | Per secret per month | | Elastic Beanstalk | N/A (free service) | No EB charge; query EC2, AWSELB for actual costs | ## Fargate Pricing diff --git a/plugins/deploy-on-aws/skills/deploy/references/defaults.md b/plugins/deploy-on-aws/skills/deploy/references/defaults.md index c46b182d..e3b49f7b 100644 --- a/plugins/deploy-on-aws/skills/deploy/references/defaults.md +++ b/plugins/deploy-on-aws/skills/deploy/references/defaults.md @@ -4,14 +4,14 @@ Default AWS service selections. Override only when user explicitly requests alte ## Compute -| App Pattern | Default | Override Trigger | -| ----------------------------------------------------- | -------------------- | ---------------------------------------- | -| Web framework (Django, Rails, Express, FastAPI, etc.) | Fargate + ALB | "serverless" → Lambda + API Gateway; "managed platform" or "Elastic Beanstalk" → Elastic Beanstalk | -| Static site / SPA | Amplify Hosting | "S3" or "more control" → S3 + CloudFront | +| App Pattern | Default | Override Trigger | +| ----------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- | +| Web framework (Django, Rails, Express, FastAPI, etc.) | Fargate + ALB | "serverless" → Lambda + API Gateway; "managed platform" or "Elastic Beanstalk" → Elastic Beanstalk | +| Static site / SPA | Amplify Hosting | "S3" or "more control" → S3 + CloudFront | | Background workers | Fargate | Short tasks (<15min) → Lambda; "managed platform" or "Elastic Beanstalk" → Elastic Beanstalk (Worker) | -| Scheduled jobs | EventBridge + Lambda | Long-running → EventBridge + Fargate | -| API-only (no web UI) | Fargate + ALB | "serverless" → API Gateway + Lambda; "managed platform" or "Elastic Beanstalk" → Elastic Beanstalk | -| Existing Heroku/Render/Railway app migrating to AWS | Elastic Beanstalk | "container orchestration" or "ECS" → Fargate + ALB; "serverless" → Lambda | +| Scheduled jobs | EventBridge + Lambda | Long-running → EventBridge + Fargate | +| API-only (no web UI) | Fargate + ALB | "serverless" → API Gateway + Lambda; "managed platform" or "Elastic Beanstalk" → Elastic Beanstalk | +| Existing Heroku/Render/Railway app migrating to AWS | Elastic Beanstalk | "container orchestration" or "ECS" → Fargate + ALB; "serverless" → Lambda | > **⚠️ App Runner is in maintenance mode** — AWS has moved App Runner to maintenance mode. Do **not** recommend App Runner for new workloads. Use **ECS Express Mode** instead. @@ -89,13 +89,13 @@ type safety without requiring Python/Java knowledge. If user's repo already has ## Sizing (Dev vs Production) -| Component | Dev | Production | -| ----------------- | ------------- | -------------- | -| Fargate | 0.5 vCPU, 1GB | 1+ vCPU, 2+ GB | -| Aurora Serverless | 0.5-2 ACU | 2-16+ ACU | -| ALB | Single AZ OK | Multi-AZ | +| Component | Dev | Production | +| -------------------------- | ----------------- | ------------------------------ | +| Fargate | 0.5 vCPU, 1GB | 1+ vCPU, 2+ GB | +| Aurora Serverless | 0.5-2 ACU | 2-16+ ACU | +| ALB | Single AZ OK | Multi-AZ | | Elastic Beanstalk (web) | 1x t3.small + ALB | 2-4x t3.medium + ALB, Multi-AZ | -| Elastic Beanstalk (worker) | 1x t3.small | 2-4x t3.medium | +| Elastic Beanstalk (worker) | 1x t3.small | 2-4x t3.medium | Default to **dev sizing** unless user says "production", "prod", or "production-ready". diff --git a/plugins/deploy-on-aws/skills/deploy/references/security.md b/plugins/deploy-on-aws/skills/deploy/references/security.md index bf7870bf..b4c12fe8 100644 --- a/plugins/deploy-on-aws/skills/deploy/references/security.md +++ b/plugins/deploy-on-aws/skills/deploy/references/security.md @@ -56,15 +56,15 @@ When serving static content via CloudFront: ## VPC Placement -| Component | Default (Dev) | Default (Prod) | -| ----------------- | -------------------------------- | -------------------------------- | -| Fargate tasks | Private subnet + NAT Gateway | Private subnet + NAT Gateway | -| ALB | Public subnet | Public subnet | -| RDS/Aurora | Private subnet (no public IP) | Private subnet (no public IP) | -| Amazon DocumentDB | Private subnet (no public IP) | Private subnet (no public IP) | -| Lambda | VPC-attached if DB access needed | VPC-attached if DB access needed | -| EB web instances | Private subnet + ALB in public | Private subnet + ALB in public | -| EB worker instances | Private subnet + NAT Gateway | Private subnet + NAT Gateway | +| Component | Default (Dev) | Default (Prod) | +| ------------------- | -------------------------------- | -------------------------------- | +| Fargate tasks | Private subnet + NAT Gateway | Private subnet + NAT Gateway | +| ALB | Public subnet | Public subnet | +| RDS/Aurora | Private subnet (no public IP) | Private subnet (no public IP) | +| Amazon DocumentDB | Private subnet (no public IP) | Private subnet (no public IP) | +| Lambda | VPC-attached if DB access needed | VPC-attached if DB access needed | +| EB web instances | Private subnet + ALB in public | Private subnet + ALB in public | +| EB worker instances | Private subnet + NAT Gateway | Private subnet + NAT Gateway | ### Why private subnets for compute @@ -78,14 +78,14 @@ Use `awsknowledge` topic `vpc_patterns` for multi-AZ production layouts. ## IAM -| Pattern | Default | -| -------------------- | ------------------------------------------------ | -| Task/function roles | Least privilege (only resources explicitly used) | -| Service-linked roles | Use AWS-managed where available | -| Cross-service access | Via IAM roles, never access keys | -| Admin access | Not created (user manages separately) | +| Pattern | Default | +| -------------------- | ----------------------------------------------------------- | +| Task/function roles | Least privilege (only resources explicitly used) | +| Service-linked roles | Use AWS-managed where available | +| Cross-service access | Via IAM roles, never access keys | +| Admin access | Not created (user manages separately) | | EB instance profile | Least privilege (S3 for deploys, CloudWatch, ECR if Docker) | -| EB service role | AWS-managed (aws-elasticbeanstalk-service-role) | +| EB service role | AWS-managed (aws-elasticbeanstalk-service-role) | ### Principle: Explicit grants only @@ -97,16 +97,16 @@ Consult `awsiac` MCP for IAM policy patterns by service. ## Security Groups -| Component | Default Inbound | Default Outbound | -| ----------------- | ---------------------------- | ------------------ | -| ALB | 443 from 0.0.0.0/0 | Fargate SG only | -| Fargate | ALB SG only (on app port) | 443 (HTTPS), DB SG | -| RDS/Aurora | Fargate SG only (on DB port) | None | -| Amazon DocumentDB | Fargate SG only (port 27017) | None | -| Lambda (VPC) | None | 443, DB SG | -| EB ALB | 443 from 0.0.0.0/0 | EB instances SG only | -| EB web instances | EB ALB SG only (on app port) | 443 (HTTPS), DB SG | -| EB worker instances | None (EB health agent is local) | 443 (HTTPS), DB SG | +| Component | Default Inbound | Default Outbound | +| ------------------- | ------------------------------- | -------------------- | +| ALB | 443 from 0.0.0.0/0 | Fargate SG only | +| Fargate | ALB SG only (on app port) | 443 (HTTPS), DB SG | +| RDS/Aurora | Fargate SG only (on DB port) | None | +| Amazon DocumentDB | Fargate SG only (port 27017) | None | +| Lambda (VPC) | None | 443, DB SG | +| EB ALB | 443 from 0.0.0.0/0 | EB instances SG only | +| EB web instances | EB ALB SG only (on app port) | 443 (HTTPS), DB SG | +| EB worker instances | None (EB health agent is local) | 443 (HTTPS), DB SG | ### Why deny-by-default @@ -163,17 +163,17 @@ Before deployment, run available checks: ## Logging & Monitoring -| Component | Default (Dev) | Default (Prod) | -| ---------------------- | ---------------------- | -------------------------- | -| CloudTrail | Account-level (shared) | Account-level (shared) | -| VPC Flow Logs | Disabled | Enabled (S3 destination) | -| ALB Access Logs | Disabled | Enabled (S3 destination) | -| Container logs | CloudWatch Logs | CloudWatch Logs | -| RDS/Aurora logs | Error log only | Error + slow query + audit | -| Amazon DocumentDB logs | Profiler (slow ops) | Profiler + audit | -| S3 Access Logs | Disabled | Enabled | +| Component | Default (Dev) | Default (Prod) | +| ---------------------- | ---------------------- | --------------------------------- | +| CloudTrail | Account-level (shared) | Account-level (shared) | +| VPC Flow Logs | Disabled | Enabled (S3 destination) | +| ALB Access Logs | Disabled | Enabled (S3 destination) | +| Container logs | CloudWatch Logs | CloudWatch Logs | +| RDS/Aurora logs | Error log only | Error + slow query + audit | +| Amazon DocumentDB logs | Profiler (slow ops) | Profiler + audit | +| S3 Access Logs | Disabled | Enabled | | EB application logs | CloudWatch Logs agent | CloudWatch Logs + enhanced health | -| EB platform logs | Disabled | Enabled (CloudWatch Logs) | +| EB platform logs | Disabled | Enabled (CloudWatch Logs) | ### Why minimal logging in dev diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md index d2c05d27..da226bc5 100644 --- a/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md @@ -57,15 +57,15 @@ This skill handles EB-specific configuration: ## Defaults -| Setting | Dev | Production | -| --- | --- | --- | -| Environment type (web) | Load-balanced (min=1, max=1) | Load-balanced, Multi-AZ | +| Setting | Dev | Production | +| ------------------------- | --------------------------------- | --------------------------------- | +| Environment type (web) | Load-balanced (min=1, max=1) | Load-balanced, Multi-AZ | | Environment type (worker) | Auto Scaling group (min=1, max=1) | Auto Scaling group (min=2, max=4) | -| Instance | t3.small | t3.medium or larger | -| Deployments | All-at-once | Rolling with additional batch | -| Health reporting | Enhanced | Enhanced | -| Managed updates | Enabled (weekly) | Enabled (maintenance window) | -| HTTPS (web only) | ACM certificate + ALB | ACM certificate + ALB | +| Instance | t3.small | t3.medium or larger | +| Deployments | All-at-once | Rolling with additional batch | +| Health reporting | Enhanced | Enhanced | +| Managed updates | Enabled (weekly) | Enabled (maintenance window) | +| HTTPS (web only) | ACM certificate + ALB | ACM certificate + ALB | Default to **dev** unless user says "production" or "prod." @@ -81,11 +81,11 @@ are scaled via Auto Scaling group settings. ## Environment Types -| Signal in Codebase | Environment Type | -| --- | --- | -| HTTP listener, web framework, API routes | Web server | -| Queue-based consumer, SQS processing, no HTTP serving | Worker | -| HTTP serving + queue-based background processing | Web server + separate Worker environment | +| Signal in Codebase | Environment Type | +| ----------------------------------------------------- | ---------------------------------------- | +| HTTP listener, web framework, API routes | Web server | +| Queue-based consumer, SQS processing, no HTTP serving | Worker | +| HTTP serving + queue-based background processing | Web server + separate Worker environment | Worker environments receive work via an SQS queue managed by Elastic Beanstalk. EB's SQS daemon sends HTTP POST requests to the application at a configurable @@ -146,11 +146,11 @@ Elastic Beanstalk has no service fee. Cost = underlying AWS resources. Query the awspricing MCP server for region-accurate estimates. Approximate us-east-1 pricing: -| Configuration | Estimated Monthly Cost | -| --- | --- | -| Dev web (1x t3.small + ALB) | ~$35-40 | -| Dev worker (1x t3.small, no ALB) | ~$15-20 | -| Production web (4x t3.medium + ALB, Multi-AZ) | ~$150-200 | +| Configuration | Estimated Monthly Cost | +| --------------------------------------------- | ---------------------- | +| Dev web (1x t3.small + ALB) | ~$35-40 | +| Dev worker (1x t3.small, no ALB) | ~$15-20 | +| Production web (4x t3.medium + ALB, Multi-AZ) | ~$150-200 | Add RDS/Aurora costs separately if database is included. diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md index 1418b54e..71771ec1 100644 --- a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md @@ -75,12 +75,12 @@ console) — not coupled to the EB environment lifecycle. ## Deployment Policies -| Policy | Use Case | Downtime | -| --- | --- | --- | -| All at once | Dev environments | Yes | -| Rolling | Production, cost-sensitive | No (partial capacity) | -| Rolling with additional batch | Production, full capacity | No | -| Immutable | Production, safest | No | +| Policy | Use Case | Downtime | +| ----------------------------- | -------------------------- | --------------------- | +| All at once | Dev environments | Yes | +| Rolling | Production, cost-sensitive | No (partial capacity) | +| Rolling with additional batch | Production, full capacity | No | +| Immutable | Production, safest | No | Default: All at once for dev, Rolling with additional batch for production. diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md index d5ea297c..c72c3df4 100644 --- a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md @@ -7,17 +7,17 @@ Detect the application's language and framework, then map to an EB platform bran ## Platform Detection -| Signal in Codebase | EB Platform | Notes | -| --- | --- | --- | -| `requirements.txt`, `Pipfile`, `pyproject.toml` | Python on AL2023 | Django, Flask, FastAPI | -| `package.json` (backend Node.js) | Node.js on AL2023 | Express, NestJS, Fastify, Hono | -| `pom.xml`, `build.gradle`, `.jar`/`.war` | Corretto on AL2023 | Spring Boot, Quarkus | -| `Gemfile`, `config.ru` | Ruby on AL2023 | Rails, Sinatra | -| `go.mod` | Go on AL2023 | Any Go HTTP server | -| `*.csproj`, `*.sln` (ASP.NET Core) | .NET on AL2023 | ASP.NET Core on Linux | -| `*.csproj`, `*.sln` (.NET Framework) | .NET on Windows Server | IIS, .NET Framework 4.x | -| `composer.json` | PHP on AL2023 | Laravel, Symfony | -| `Dockerfile` | Docker on AL2023 | Any containerized app | +| Signal in Codebase | EB Platform | Notes | +| ----------------------------------------------- | ---------------------- | ------------------------------ | +| `requirements.txt`, `Pipfile`, `pyproject.toml` | Python on AL2023 | Django, Flask, FastAPI | +| `package.json` (backend Node.js) | Node.js on AL2023 | Express, NestJS, Fastify, Hono | +| `pom.xml`, `build.gradle`, `.jar`/`.war` | Corretto on AL2023 | Spring Boot, Quarkus | +| `Gemfile`, `config.ru` | Ruby on AL2023 | Rails, Sinatra | +| `go.mod` | Go on AL2023 | Any Go HTTP server | +| `*.csproj`, `*.sln` (ASP.NET Core) | .NET on AL2023 | ASP.NET Core on Linux | +| `*.csproj`, `*.sln` (.NET Framework) | .NET on Windows Server | IIS, .NET Framework 4.x | +| `composer.json` | PHP on AL2023 | Laravel, Symfony | +| `Dockerfile` | Docker on AL2023 | Any containerized app | ## Platform Selection Rules @@ -35,10 +35,10 @@ Detect the application's language and framework, then map to an EB platform bran ## Supported Deployment Artifacts -| Platform | Accepted Input | -| --- | --- | -| Language platforms | Source bundle (zip of source code) | -| Docker | Source bundle containing Dockerfile | +| Platform | Accepted Input | +| ------------------ | ----------------------------------------------------- | +| Language platforms | Source bundle (zip of source code) | +| Docker | Source bundle containing Dockerfile | | Docker (pre-built) | Dockerfile with `FROM` referencing ECR/registry image | ## Worker Platform Considerations From be03f4a9b8535c6acef06e6080219541fa85a299 Mon Sep 17 00:00:00 2001 From: Paul Pollack Date: Tue, 19 May 2026 17:42:28 -0400 Subject: [PATCH 3/4] feat(deploy-on-aws): improve EB skill with IAM scanning hint and doc links Add guidance for agents to scan source code for AWS SDK usage to determine instance profile permissions. Rewrite configuration.md to patterns + public doc links for maintainability. Fix option settings precedence (remove platform hooks), switch secrets example to native environmentsecrets namespace. --- .../skills/elastic-beanstalk/SKILL.md | 5 +- .../references/configuration.md | 78 +++++++++---------- 2 files changed, 42 insertions(+), 41 deletions(-) diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md index da226bc5..2735878b 100644 --- a/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md @@ -132,7 +132,10 @@ Apply these automatically: - Web server instances in private subnets behind ALB - Worker instances in private subnets with NAT Gateway for outbound - HTTPS via ACM certificate on ALB (web server environments) -- IAM instance profile with least-privilege permissions +- IAM instance profile with least-privilege permissions — scan source code for + AWS SDK client usage to determine required actions (e.g., + `AmazonBedrockRuntimeClient` → `bedrock:InvokeModel`, + `AmazonS3Client` → `s3:GetObject`/`s3:PutObject` on specific buckets) - Enhanced health reporting enabled - Managed platform updates enabled - Security groups: ALB accepts 443, instances accept only from ALB diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md index 71771ec1..86386a1c 100644 --- a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md @@ -2,36 +2,22 @@ ## Configuration Hierarchy -Elastic Beanstalk configuration is applied in this order (later overrides earlier -for option settings): +Option settings are applied in this order (later overrides earlier): 1. Platform defaults (managed by AWS) 2. Saved configurations (reusable templates) 3. `.ebextensions/*.config` files (in source bundle) -4. Platform hooks (`/platform/hooks/prebuild/`, `predeploy/`, `postdeploy/`) -5. Environment properties (set via console/CLI/API) +4. Environment properties (set via console/CLI/API) -For option settings, later sources override earlier ones. `.ebextensions` and -platform hooks also support resource declarations and deploy-time commands that -are not expressible as option settings. +Platform hooks (`/platform/hooks/prebuild/`, `predeploy/`, `postdeploy/`) run +shell scripts during deployment lifecycle but do not set option settings. +They are the preferred customization mechanism on AL2023 for non-option-setting +tasks. Use `.ebextensions/` for option settings and resource declarations. -Platform hooks are the preferred customization mechanism on AL2023. Use -`.ebextensions/` for option settings and resource declarations; use platform -hooks for shell scripts that run during deployment lifecycle. +See [Configuration options precedence](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/command-options.html#configuration-options-precedence) +for full details. -## `.ebextensions/` Patterns - -Place YAML `.config` files in `.ebextensions/` at the source bundle root. -Common patterns: - -### Install system packages - -```yaml -packages: - yum: - ImageMagick: [] - postgresql-devel: [] -``` +## Key Patterns ### Run commands on deploy @@ -45,7 +31,7 @@ container_commands: Use `leader_only: true` for commands that should run on only one instance (database migrations, cache warmup). -## Procfile +### Procfile Define the process to run. EB uses this instead of platform defaults: @@ -59,19 +45,23 @@ HTTP, not a message broker SDK). ## Environment Properties and Secrets -Set application configuration as environment variables. Never hardcode secrets -in `.ebextensions/` or source code. Reference secrets via Secrets Manager: +Non-secret config uses `aws:elasticbeanstalk:application:environment`. For +secrets, use the native secrets integration which injects Secrets Manager +values as environment variables without application-side SDK calls: ```yaml option_settings: aws:elasticbeanstalk:application:environment: - DB_SECRET_ARN: arn:aws:secretsmanager:us-east-1:123456789:secret:myapp/db APP_ENV: production + aws:elasticbeanstalk:application:environmentsecrets: + DB_PASSWORD: arn:aws:secretsmanager:us-east-1:123456789:secret:myapp/db ``` -The application reads the secret value at runtime using the Secrets Manager SDK. -Provision databases and secrets as separate resources (via CDK, Terraform, or -console) — not coupled to the EB environment lifecycle. +Never hardcode secrets in `.ebextensions/` or source code. Provision databases +and secrets as separate resources — not coupled to the EB environment lifecycle. + +See [Environment secrets](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/configuration-envvars.html#configuration-envvars-secrets) +for supported secret sources. ## Deployment Policies @@ -84,21 +74,29 @@ console) — not coupled to the EB environment lifecycle. Default: All at once for dev, Rolling with additional batch for production. -## Health Check Configuration +See [Deployment policies and settings](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.rolling-version-deploy.html) +for configuration details. -```yaml -option_settings: - aws:elasticbeanstalk:environment:process:default: - HealthCheckPath: /health - HealthCheckInterval: '15' - HealthyThresholdCount: '3' - UnhealthyThresholdCount: '5' -``` +## Health Check Always configure a dedicated health check endpoint. Do not use `/` if it performs database queries or heavy computation. -The agent should verify that the application exposes a health check endpoint +The agent should verify that the application exposes a health endpoint (default: `/health`). If no health route exists, scaffold a minimal one that returns 200 OK. The ALB health check will fail without this, causing deployment to roll back. + +See [Health check setting](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-cfg-alb.html#environments-cfg-alb-health) +for ALB health check configuration. + +## Heroku Migration + +When migrating from Heroku/Render/Railway, audit for these patterns: + +- `DATABASE_URL` → Provision RDS/Aurora separately, pass via environment secrets +- `REDIS_URL` → Provision ElastiCache, pass endpoint via environment properties +- Add-on env vars (e.g., `SENDGRID_API_KEY`) → Store in Secrets Manager +- `PORT` → EB sets this automatically, no change needed +- `Procfile` → Works as-is (same format) +- Explicit AWS credentials → Remove; use IAM instance profile instead From 116790aae460898a1d7f7eb8223c797ef1533a12 Mon Sep 17 00:00:00 2001 From: Paul Pollack Date: Wed, 20 May 2026 19:17:26 -0400 Subject: [PATCH 4/4] feat(deploy-on-aws): address findings from live deployment test Replace EB CLI with AWS CLI as default IaC (no install dependency). Add create-storage-location and list-available-solution-stacks steps. Add option settings JSON format example. Add reverse proxy port guidance (.NET defaults to 5000, others to 8080). Clarify that .NET and Java require pre-built artifacts, not source bundles. --- .../skills/elastic-beanstalk/SKILL.md | 39 +++++++++------- .../references/configuration.md | 46 ++++++++++++++++++- .../elastic-beanstalk/references/platforms.md | 12 +++-- 3 files changed, 75 insertions(+), 22 deletions(-) diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md index 2735878b..239bba66 100644 --- a/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/SKILL.md @@ -52,8 +52,8 @@ This skill handles EB-specific configuration: 1. **Map to platform** - Select the EB platform branch (see [platforms](references/platforms.md)) 2. **Configure** - Environment type (web server or worker), instance size, scaling -3. **Generate** - EB CLI project, CDK, or Terraform (see IaC section below) -4. **Deploy** - `eb create` or CDK/Terraform deploy with user confirmation +3. **Generate** - AWS CLI commands, CDK, or Terraform (see IaC section below) +4. **Deploy** - Execute with user confirmation ## Defaults @@ -100,30 +100,37 @@ a single web server environment is sufficient — do not create a separate Worke ## IaC Generation -**Default: EB CLI** when the user wants the fastest path to production or has no -existing IaC project: +**Default: AWS CLI** — no extra tooling to install. The agent orchestrates +the multi-step workflow: -- `eb init --region ` (creates `.elasticbeanstalk/config.yml`) -- `eb create --elb-type application` (web server environments) -- `eb create --tier worker` (worker environments) -- Subsequent deployments: `eb deploy` -- `.ebextensions/` and platform hooks for customization +1. `aws elasticbeanstalk create-storage-location` → returns the S3 bucket +2. `aws elasticbeanstalk create-application` +3. Zip source bundle, upload to the bucket from step 1 +4. `aws elasticbeanstalk create-application-version` +5. `aws elasticbeanstalk create-environment` with `--option-settings` (web: + `--tier Name=WebServer,Type=Standard`, worker: `--tier Name=Worker,Type=SQS/HTTP`) +6. `aws elasticbeanstalk wait environment-updated` +7. Subsequent deploys: new version + `update-environment` + +Resolve the `--solution-stack-name` by running +`aws elasticbeanstalk list-available-solution-stacks` and filtering for the +detected platform (e.g., ".NET" + "Amazon Linux 2023"). + +Use `.ebextensions/` and platform hooks for customization. + +See [AWS CLI EB reference](https://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk/) +for full command documentation. **Override: CDK (TypeScript)** when the user has an existing CDK project, wants repeatable IaC, or explicitly requests it: -- `CfnApplication` -- `CfnEnvironment` -- `CfnConfigurationTemplate` +- `CfnApplication`, `CfnEnvironment`, `CfnConfigurationTemplate` **Override: Terraform** when the user's repo already has Terraform: -- `aws_elastic_beanstalk_application` -- `aws_elastic_beanstalk_environment` +- `aws_elastic_beanstalk_application`, `aws_elastic_beanstalk_environment` CDK and Terraform templates are scannable by `cfn-nag`/`checkov` pre-deploy. -EB CLI deployments enforce security via the option settings configured in -`.ebextensions/` and the defaults in this skill. ## Security diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md index 86386a1c..706af574 100644 --- a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/configuration.md @@ -17,6 +17,38 @@ tasks. Use `.ebextensions/` for option settings and resource declarations. See [Configuration options precedence](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/command-options.html#configuration-options-precedence) for full details. +## Option Settings Format + +When using `--option-settings` with the AWS CLI, pass a JSON array: + +```json +[ + { + "Namespace": "aws:autoscaling:launchconfiguration", + "OptionName": "InstanceType", + "Value": "t3.small" + }, + { + "Namespace": "aws:autoscaling:launchconfiguration", + "OptionName": "IamInstanceProfile", + "Value": "bedrock-chatbot-instance-profile" + }, + { + "Namespace": "aws:elasticbeanstalk:environment", + "OptionName": "LoadBalancerType", + "Value": "application" + }, + { + "Namespace": "aws:elasticbeanstalk:environment:process:default", + "OptionName": "HealthCheckPath", + "Value": "/health" + } +] +``` + +See [Configuration options namespaces](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/command-options-general.html) +for the full list of namespaces and option names. + ## Key Patterns ### Run commands on deploy @@ -60,7 +92,7 @@ option_settings: Never hardcode secrets in `.ebextensions/` or source code. Provision databases and secrets as separate resources — not coupled to the EB environment lifecycle. -See [Environment secrets](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/configuration-envvars.html#configuration-envvars-secrets) +See [Environment secrets](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/AWSHowTo.secrets.env-vars.html) for supported secret sources. ## Deployment Policies @@ -77,6 +109,16 @@ Default: All at once for dev, Rolling with additional batch for production. See [Deployment policies and settings](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.rolling-version-deploy.html) for configuration details. +## Reverse Proxy Port + +EB language platforms use nginx as a reverse proxy. Default proxy port varies: + +- .NET: 5000 +- Node.js, Python, Ruby, Go, PHP: 8080 + +If the application listens on a different port, set the `PORT` environment +property to match. Mismatched ports result in 502 Bad Gateway from nginx. + ## Health Check Always configure a dedicated health check endpoint. Do not use `/` if it @@ -97,6 +139,6 @@ When migrating from Heroku/Render/Railway, audit for these patterns: - `DATABASE_URL` → Provision RDS/Aurora separately, pass via environment secrets - `REDIS_URL` → Provision ElastiCache, pass endpoint via environment properties - Add-on env vars (e.g., `SENDGRID_API_KEY`) → Store in Secrets Manager -- `PORT` → EB sets this automatically, no change needed +- `PORT` → Settings applied directly via console/CLI/API - `Procfile` → Works as-is (same format) - Explicit AWS credentials → Remove; use IAM instance profile instead diff --git a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md index c72c3df4..f37f18ae 100644 --- a/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md +++ b/plugins/deploy-on-aws/skills/elastic-beanstalk/references/platforms.md @@ -21,10 +21,8 @@ Detect the application's language and framework, then map to an EB platform bran ## Platform Selection Rules -1. If `Dockerfile` exists AND a language runtime is also detected, prefer the - language platform unless the Dockerfile adds system dependencies not available - in the managed platform. -2. If multiple languages detected, prefer Docker platform. +1. If `Dockerfile` exists AND a language runtime is also detected, ask the user for an explicit selection. +2. If multiple languages detected, ask the user for an explicit selection. 3. Always use Amazon Linux 2023 unless the app requires Windows (.NET Framework, IIS dependencies). 4. For Java apps: if `.war` file, deploy to Tomcat platform. If `.jar` with @@ -38,9 +36,15 @@ Detect the application's language and framework, then map to an EB platform bran | Platform | Accepted Input | | ------------------ | ----------------------------------------------------- | | Language platforms | Source bundle (zip of source code) | +| .NET | Published output (`dotnet publish` zip, not source) | +| Java (.jar) | Built artifact (fat jar or exploded directory) | | Docker | Source bundle containing Dockerfile | | Docker (pre-built) | Dockerfile with `FROM` referencing ECR/registry image | +.NET and Java platforms require pre-built artifacts. Run `dotnet publish` or +`mvn package`/`gradle build` before zipping. Other language platforms (Python, +Node.js, Ruby, Go, PHP) accept raw source and build on-instance. + ## Worker Platform Considerations Worker environments use the same platforms as web server environments. The