Pulse AWS reference

CLI flags and Python exports for pulse-aws.

CLI: pulse-aws

pulse-aws deploy [options]
pulse-aws verify [options]
pulse-aws teardown [options]

deploy

Defaults applied even when omitted:

• Docker build args always include APP_FILE, WEB_ROOT, PULSE_SERVER_ADDRESS.
• ECS task env always includes PULSE_SERVER_ADDRESS.
• CDK commands run against the packaged pulse_aws/cdk app unless --cdk-workdir is set.

Path rules:

• Host-path flags resolve from the directory where you run pulse-aws.
• --app-file and --web-root are Docker-context paths, not host paths.

verify

teardown

Python API exports

from pulse_aws import (
    AWSECSPlugin,
    DeploymentError,
    DockerBuild,
    HealthCheckConfig,
    ReaperConfig,
    TaskConfig,
    deploy,
)

DockerBuild

DockerBuild(
    dockerfile_path: Path,
    context_path: Path,
    build_args: dict[str, str] = {},
)

• dockerfile_path: path to Dockerfile.
• context_path: Docker build context.
• build_args: extra docker build args.

TaskConfig

TaskConfig(
    cpu: str = "256",
    memory: str = "512",
    desired_count: int = 2,
    env_vars: dict[str, str] = {},
    drain_poll_seconds: int = 5,
    drain_grace_seconds: int = 20,
)

HealthCheckConfig

HealthCheckConfig(
    path: str = "/_pulse/health",
    interval_seconds: int = 30,
    timeout_seconds: int = 5,
    healthy_threshold: int = 2,
    unhealthy_threshold: int = 3,
    wait_for_health: bool = True,
    min_healthy_targets: int = 2,
    task_grace_period_seconds: int = 60,
)

ReaperConfig

ReaperConfig(
    schedule_minutes: int = 1,
    max_age_hours: float = 1.0,
    deployment_timeout: float = 1.0,
)

deploy

async def deploy(
    *,
    domain: str,
    deployment_name: str,
    docker: DockerBuild,
    task: TaskConfig | None = None,
    health_check: HealthCheckConfig | None = None,
    reaper: ReaperConfig | None = None,
    certificate_arn: str | None = None,
    cdk_bin: str = "cdk",
    cdk_workdir: Path | str | None = None,
) -> dict[str, str]:
    ...

cdk_bin points to the CDK executable or wrapper script.

cdk_workdir is an advanced override that points deploy at a custom CDK app directory. If omitted, pulse-aws uses the packaged CDK app that ships inside pulse_aws/cdk.

Return keys:

• deployment_id
• service_arn
• target_group_arn
• task_def_arn
• image_uri
• cluster_name
• alb_dns_name
• marked_draining_count
• certificate_arn
• domain_ready
• domain_proxied

DeploymentError

Raised when deployment operations fail.

AWSECSPlugin

Required env vars (prod/ci):

• PULSE_AWS_DEPLOYMENT_NAME
• PULSE_AWS_DEPLOYMENT_ID
• PULSE_AWS_DRAIN_POLL_SECONDS
• PULSE_AWS_DRAIN_GRACE_SECONDS

Optional env vars:

• ECS_CONTAINER_METADATA_URI_V4 (auto in ECS)
• PULSE_AWS_TASK_ID (fallback task id)

Behavior:

• polls SSM for drain state
• writes task readiness state to SSM
• adds pulse_deployment to prerender and Socket.IO query directives for existing render sessions. New tabs/sessions do not send this query unless they reuse those same directives.
• exposes /_pulse/meta as a deployment-metadata endpoint used by pulse-aws verify
• Uses ALB target-group lb_cookie stickiness to keep requests on the same ECS task within a matched deployment.
• New sessions without the affinity query follow the default listener action, which is the latest deployment.

In dev, missing required vars disables the plugin. In prod/ci, missing vars raise on startup.

See also

• Pulse AWS — Dockerfile + workflow
• Deployment concepts — how deployments work
• Packages index — all add-ons