pulse-aws 0.1.0__tar.gz

pulse_aws-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.3
+Name: pulse-aws
+Version: 0.1.0
+Summary: Add your description here
+Author: Erwin Kuhn
+Author-email: Erwin Kuhn <erwin.kuhn@protonmail.com>
+Requires-Dist: aws-cdk-lib>=2.160.0,<3.0
+Requires-Dist: constructs>=10.0.0,<11.0.0
+Requires-Dist: boto3>=1.35.0,<2.0.0
+Requires-Dist: botocore>=1.35.0,<2.0.0
+Requires-Dist: httpx>=0.27.0,<1.0.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# pulse-aws
+
+AWS deployment utilities for Pulse applications on ECS Fargate.
+
+## Features
+
+- **Zero-downtime deployments** with header-based sticky sessions
+- **Automatic ACM certificate management** with DNS validation
+- **DNS configuration detection** - automatically detects and guides you through DNS setup
+- **Baseline infrastructure** as code using AWS CDK
+- **Multi-version support** - run multiple deployments simultaneously
+
+## Quick Start
+
+```bash
+# Install
+uv add pulse-aws
+
+# Deploy
+uv run scripts/deploy.py
+```
+
+## Architecture
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for a detailed overview of:
+
+- Infrastructure resources and how they relate
+- Traffic routing with sticky sessions
+- Zero-downtime deployment workflow
+- Security architecture
+
+## Deployment Workflow
+
+The deployment script orchestrates the full workflow:
+
+### 1. ACM Certificate
+
+```python
+from pulse_aws import ensure_acm_certificate
+
+cert = await ensure_acm_certificate("api.example.com")
+```
+
+- Creates or retrieves an ACM certificate
+- Provides DNS validation records if needed
+- Waits for certificate to be ISSUED
+
+### 2. Baseline Infrastructure
+
+```python
+from pulse_aws import ensure_baseline_stack
+
+outputs = await ensure_baseline_stack(
+    "prod",
+    certificate_arn=cert.arn,
+)
+```
+
+Creates shared infrastructure:
+
+- VPC with public/private subnets
+- Application Load Balancer with HTTPS listener
+- ECS Fargate cluster
+- ECR repository
+- CloudWatch log group
+- Security groups
+
+### 3. DNS Configuration Check
+
+```python
+from pulse_aws import check_domain_dns
+
+dns_config = check_domain_dns(domain, alb_dns_name)
+if dns_config:
+    print(dns_config.format_for_display())
+```
+
+Automatically checks if your domain resolves to the ALB:
+
+- ✅ **Already configured**: Silent success
+- ✅ **Proxied through Cloudflare**: Treated as configured once records point to Cloudflare
+- ⚠️ **Not configured**: Shows exact DNS record to add
+
+Example output:
+
+```
+⚠️  Domain DNS Configuration Required
+============================================================
+
+🔗 Configure DNS for test.stoneware.rocks
+
+Add the following records to your DNS provider:
+
+  • Type: CNAME
+    Name: test.stoneware.rocks
+    Value: test-alb-514905529.us-east-2.elb.amazonaws.com
+    (Route traffic to Application Load Balancer)
+
+Once the records are added, your domain will be live within a few minutes.
+```
+
+### 4. Deploy Application
+
+```python
+from pulse_aws import (
+    generate_deployment_id,
+    build_and_push_image,
+    register_task_definition,
+    create_service_and_target_group,
+    install_listener_rules_and_switch_traffic,
+)
+
+deployment_id = generate_deployment_id("prod")
+image_uri = await build_and_push_image(...)
+task_def_arn = await register_task_definition(...)
+service_arn, tg_arn = await create_service_and_target_group(...)
+await install_listener_rules_and_switch_traffic(...)  # Waits for health checks
+```
+
+- Builds and pushes Docker image to ECR (with correct x86_64 architecture)
+- Registers ECS task definition with IAM roles
+- Creates target group and attaches to ALB listener
+- Creates ECS service with 2 Fargate tasks
+- **Waits for targets to pass health checks (zero-downtime)**
+- Switches default traffic to new deployment
+
+## Zero-Downtime Deployments
+
+Each deployment gets a unique ID (e.g., `prod-20251027-122112Z`):
+
+1. **New deployment starts** - New tasks spin up alongside old tasks
+2. **Header-based routing** - ALB creates a rule: `X-Pulse-Render-Affinity: <deployment-id>` → target group
+3. **Default action switches** - New users get new version
+4. **Old sessions continue** - Existing users stick to old version via header
+5. **Drain old deployment** - When ready, call drain endpoint to shut down gracefully
+
+```bash
+# Drain an old deployment
+curl -X POST \
+  -H "Authorization: Bearer <drain-secret>" \
+  https://api.example.com/drain
+```
+
+## Configuration
+
+### Environment Variables
+
+- `AWS_PROFILE` - AWS profile to use
+- `AWS_REGION` - AWS region (or set in `~/.aws/config`)
+
+### Deployment Settings
+
+```python
+# In your deploy script
+deployment_name = "prod"  # Used for resource naming
+domain = "api.example.com"  # Your domain
+dockerfile_path = Path("Dockerfile")  # Path to Dockerfile
+```
+
+## Security
+
+**Defense in depth:**
+
+- ALB in public subnets (internet-facing)
+- ECS tasks in private subnets (no direct internet access)
+- NAT gateway for task outbound internet
+- ALB security group: Only 80/443 from internet
+- Service security group: Only 8000 from ALB
+- IAM roles with least privilege
+
+## Development
+
+```bash
+# Run tests
+uv run pytest packages/pulse-aws/tests/
+
+# Deploy test environment
+AWS_PROFILE=your-profile uv run packages/pulse-aws/scripts/deploy.py
+```
+
+## Troubleshooting
+
+### Certificate validation stuck
+
+If certificate stays in `PENDING_VALIDATION`:
+
+1. Check DNS validation records are added correctly
+2. Wait 5-10 minutes for DNS propagation
+3. Use `dig` to verify: `dig _xxx.yourdomain.com CNAME`
+
+### Domain not accessible after deployment
+
+1. Check DNS record points to ALB: `dig yourdomain.com`
+2. Wait for DNS propagation (can take 5-60 minutes)
+3. Verify ALB is healthy: Visit ALB DNS directly
+
+### Tasks failing health checks
+
+1. Check logs: `aws logs tail /aws/pulse/{env}/app --follow`
+2. Verify tasks are listening on port 8000
+3. Check `/_health` endpoint returns 200
+
+## License
+
+MIT

pulse_aws-0.1.0/README.md

@@ -0,0 +1,205 @@
+# pulse-aws
+
+AWS deployment utilities for Pulse applications on ECS Fargate.
+
+## Features
+
+- **Zero-downtime deployments** with header-based sticky sessions
+- **Automatic ACM certificate management** with DNS validation
+- **DNS configuration detection** - automatically detects and guides you through DNS setup
+- **Baseline infrastructure** as code using AWS CDK
+- **Multi-version support** - run multiple deployments simultaneously
+
+## Quick Start
+
+```bash
+# Install
+uv add pulse-aws
+
+# Deploy
+uv run scripts/deploy.py
+```
+
+## Architecture
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for a detailed overview of:
+
+- Infrastructure resources and how they relate
+- Traffic routing with sticky sessions
+- Zero-downtime deployment workflow
+- Security architecture
+
+## Deployment Workflow
+
+The deployment script orchestrates the full workflow:
+
+### 1. ACM Certificate
+
+```python
+from pulse_aws import ensure_acm_certificate
+
+cert = await ensure_acm_certificate("api.example.com")
+```
+
+- Creates or retrieves an ACM certificate
+- Provides DNS validation records if needed
+- Waits for certificate to be ISSUED
+
+### 2. Baseline Infrastructure
+
+```python
+from pulse_aws import ensure_baseline_stack
+
+outputs = await ensure_baseline_stack(
+    "prod",
+    certificate_arn=cert.arn,
+)
+```
+
+Creates shared infrastructure:
+
+- VPC with public/private subnets
+- Application Load Balancer with HTTPS listener
+- ECS Fargate cluster
+- ECR repository
+- CloudWatch log group
+- Security groups
+
+### 3. DNS Configuration Check
+
+```python
+from pulse_aws import check_domain_dns
+
+dns_config = check_domain_dns(domain, alb_dns_name)
+if dns_config:
+    print(dns_config.format_for_display())
+```
+
+Automatically checks if your domain resolves to the ALB:
+
+- ✅ **Already configured**: Silent success
+- ✅ **Proxied through Cloudflare**: Treated as configured once records point to Cloudflare
+- ⚠️ **Not configured**: Shows exact DNS record to add
+
+Example output:
+
+```
+⚠️  Domain DNS Configuration Required
+============================================================
+
+🔗 Configure DNS for test.stoneware.rocks
+
+Add the following records to your DNS provider:
+
+  • Type: CNAME
+    Name: test.stoneware.rocks
+    Value: test-alb-514905529.us-east-2.elb.amazonaws.com
+    (Route traffic to Application Load Balancer)
+
+Once the records are added, your domain will be live within a few minutes.
+```
+
+### 4. Deploy Application
+
+```python
+from pulse_aws import (
+    generate_deployment_id,
+    build_and_push_image,
+    register_task_definition,
+    create_service_and_target_group,
+    install_listener_rules_and_switch_traffic,
+)
+
+deployment_id = generate_deployment_id("prod")
+image_uri = await build_and_push_image(...)
+task_def_arn = await register_task_definition(...)
+service_arn, tg_arn = await create_service_and_target_group(...)
+await install_listener_rules_and_switch_traffic(...)  # Waits for health checks
+```
+
+- Builds and pushes Docker image to ECR (with correct x86_64 architecture)
+- Registers ECS task definition with IAM roles
+- Creates target group and attaches to ALB listener
+- Creates ECS service with 2 Fargate tasks
+- **Waits for targets to pass health checks (zero-downtime)**
+- Switches default traffic to new deployment
+
+## Zero-Downtime Deployments
+
+Each deployment gets a unique ID (e.g., `prod-20251027-122112Z`):
+
+1. **New deployment starts** - New tasks spin up alongside old tasks
+2. **Header-based routing** - ALB creates a rule: `X-Pulse-Render-Affinity: <deployment-id>` → target group
+3. **Default action switches** - New users get new version
+4. **Old sessions continue** - Existing users stick to old version via header
+5. **Drain old deployment** - When ready, call drain endpoint to shut down gracefully
+
+```bash
+# Drain an old deployment
+curl -X POST \
+  -H "Authorization: Bearer <drain-secret>" \
+  https://api.example.com/drain
+```
+
+## Configuration
+
+### Environment Variables
+
+- `AWS_PROFILE` - AWS profile to use
+- `AWS_REGION` - AWS region (or set in `~/.aws/config`)
+
+### Deployment Settings
+
+```python
+# In your deploy script
+deployment_name = "prod"  # Used for resource naming
+domain = "api.example.com"  # Your domain
+dockerfile_path = Path("Dockerfile")  # Path to Dockerfile
+```
+
+## Security
+
+**Defense in depth:**
+
+- ALB in public subnets (internet-facing)
+- ECS tasks in private subnets (no direct internet access)
+- NAT gateway for task outbound internet
+- ALB security group: Only 80/443 from internet
+- Service security group: Only 8000 from ALB
+- IAM roles with least privilege
+
+## Development
+
+```bash
+# Run tests
+uv run pytest packages/pulse-aws/tests/
+
+# Deploy test environment
+AWS_PROFILE=your-profile uv run packages/pulse-aws/scripts/deploy.py
+```
+
+## Troubleshooting
+
+### Certificate validation stuck
+
+If certificate stays in `PENDING_VALIDATION`:
+
+1. Check DNS validation records are added correctly
+2. Wait 5-10 minutes for DNS propagation
+3. Use `dig` to verify: `dig _xxx.yourdomain.com CNAME`
+
+### Domain not accessible after deployment
+
+1. Check DNS record points to ALB: `dig yourdomain.com`
+2. Wait for DNS propagation (can take 5-60 minutes)
+3. Verify ALB is healthy: Visit ALB DNS directly
+
+### Tasks failing health checks
+
+1. Check logs: `aws logs tail /aws/pulse/{env}/app --follow`
+2. Verify tasks are listening on port 8000
+3. Check `/_health` endpoint returns 200
+
+## License
+
+MIT

pulse_aws-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "pulse-aws"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "Erwin Kuhn", email = "erwin.kuhn@protonmail.com" }]
+requires-python = ">=3.11"
+dependencies = [
+    "aws-cdk-lib>=2.160.0,<3.0",
+    "constructs>=10.0.0,<11.0.0",
+    "boto3>=1.35.0,<2.0.0",
+    "botocore>=1.35.0,<2.0.0",
+    "httpx>=0.27.0,<1.0.0",
+]
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["uv_build>=0.9.4,<0.10.0"]
+build-backend = "uv_build"

pulse_aws-0.1.0/src/pulse_aws/__init__.py

@@ -0,0 +1,104 @@
+# ########################
+# ##### NOTES ON IMPORT FORMAT
+# ########################
+#
+# This file defines Pulse's public API. Imports need to be structured/formatted so as to to ensure
+# that the broadest possible set of static analyzers understand Pulse's public API as intended.
+# The below guidelines ensure this is the case.
+#
+# (1) All imports in this module intended to define exported symbols should be of the form `from
+# pulse.foo import X as X`. This is because imported symbols are not by default considered public
+# by static analyzers. The redundant alias form `import X as X` overwrites the private imported `X`
+# with a public `X` bound to the same value. It is also possible to expose `X` as public by listing
+# it inside `__all__`, but the redundant alias form is preferred here due to easier maintainability.
+
+# (2) All imports should target the module in which a symbol is actually defined, rather than a
+# container module where it is imported.
+
+from .baseline import (
+	BaselineStackError as BaselineStackError,
+)
+from .baseline import (
+	BaselineStackOutputs as BaselineStackOutputs,
+)
+from .baseline import (
+	check_domain_dns as check_domain_dns,
+)
+from .baseline import (
+	ensure_baseline_stack as ensure_baseline_stack,
+)
+from .certificate import (
+	AcmCertificate as AcmCertificate,
+)
+from .certificate import (
+	CertificateError as CertificateError,
+)
+from .certificate import (
+	DnsConfiguration as DnsConfiguration,
+)
+from .certificate import (
+	DnsRecord as DnsRecord,
+)
+from .certificate import (
+	domain_uses_cloudflare_proxy as domain_uses_cloudflare_proxy,
+)
+from .certificate import (
+	ensure_acm_certificate as ensure_acm_certificate,
+)
+from .config import (
+	DockerBuild as DockerBuild,
+)
+from .config import (
+	HealthCheckConfig as HealthCheckConfig,
+)
+from .config import (
+	ReaperConfig as ReaperConfig,
+)
+from .config import (
+	TaskConfig as TaskConfig,
+)
+from .deployment import (
+	DeploymentError as DeploymentError,
+)
+from .deployment import (
+	build_and_push_image as build_and_push_image,
+)
+from .deployment import (
+	create_service_and_target_group as create_service_and_target_group,
+)
+from .deployment import (
+	deploy as deploy,
+)
+from .deployment import (
+	generate_deployment_id as generate_deployment_id,
+)
+from .deployment import (
+	install_listener_rules_and_switch_traffic as install_listener_rules_and_switch_traffic,
+)
+from .deployment import (
+	register_task_definition as register_task_definition,
+)
+from .deployment import (
+	wait_for_healthy_targets as wait_for_healthy_targets,
+)
+from .plugin import (
+	AWSECSPlugin as AWSECSPlugin,
+)
+from .reporting import (
+	CiReporter as CiReporter,
+)
+from .reporting import (
+	CliReporter as CliReporter,
+)
+from .reporting import (
+	DeploymentContext as DeploymentContext,
+)
+from .reporting import (
+	Reporter as Reporter,
+)
+from .reporting import (
+	create_context as create_context,
+)
+from .teardown import (
+	teardown_baseline_stack as teardown_baseline_stack,
+)