service

ECS services in AWS provide a managed way to run containerized applications. Stackattack creates ECS services with task definitions, load balancer integration, health checks, and service discovery.

import * as saws from "@stackattack/aws";

const ctx = saws.context();
const vpc = saws.vpc(ctx);
const cluster = saws.cluster(ctx, { network: vpc.network("private") });
const app = saws.service(ctx, {
  name: "my-app",
  image: "nginx:latest",
  network: vpc.network("private"),
  cluster
});

export const appUrl = app.internalUrl;

Usage

After deploying a service, you can manage it using:

AWS CLI:

# View service status and tasks
aws ecs describe-services --cluster your-cluster-name --services your-service-name

# View service logs
aws logs tail /aws/ecs/your-service-name --follow

# Scale the service
aws ecs update-service --cluster your-cluster-name --service your-service-name --desired-count 3

Related Components

Services work together with other Stackattack components:

• cluster - Provides compute capacity for running services
• vpc - Provides networking foundation with private/public subnets
• load-balancer - Routes external traffic to services

Costs

ECS service costs depend on the underlying compute resources and are usage-based:

• EC2 instances - If using EC2 capacity providers, you pay for the underlying EC2 instances (~$0.0116/hour for t3.micro). The cluster component manages auto-scaling groups that can scale to zero when no tasks are running.

• Fargate - If using Fargate capacity providers, you pay per vCPU-hour ($0.04048/vCPU/hour) and per GB-hour ($0.004445/GB/hour). A 0.5 vCPU, 1GB task running 24/7 costs ~$15/month.

• Data transfer - Minimal costs for service-to-service communication within the same VPC (typically free). External data transfer follows standard AWS rates.

• CloudWatch Logs - Log storage is ~$0.50/GB/month. Use the logRetention parameter to automatically delete old logs and control costs.

Cost optimization strategies:

• Use the cluster component’s auto-scaling features to scale EC2 instances to zero during low usage
• Set appropriate logRetention periods (default: 30 days)
• Consider spot instances for non-critical workloads through capacity provider configuration

See ECS Pricing for current rates.

service

Creates an ECS service with task definition, load balancer integration, and service discovery.

function service(ctx: Context, args: ServiceArgs): ServiceOutput

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (ServiceArgs) - Configuration arguments for the service

Returns

• (ServiceOutput) - Creates an ECS service with task definition, load balancer integration, and service discovery.

Functions

checkEcsDeployment

Validates that an ECS service deployment matches the expected task definition.

function checkEcsDeployment(service: Service, taskDefinition: TaskDefinition): Output<string>

Parameters

• service (Service) - The ECS service to check
• taskDefinition (TaskDefinition) - The expected task definition

Returns

• (Output<string>) - Validates that an ECS service deployment matches the expected task definition.

getServiceAttributes

function getServiceAttributes(service: Input<ServiceInput>): Output<Service | GetServiceResult>

Parameters

• service (Input<ServiceInput>) -

Returns

• (Output<Service | GetServiceResult>) -

getServiceId

function getServiceId(service: Input<ServiceInput>): Output<string>

Parameters

• service (Input<ServiceInput>) -

Returns

• (Output<string>) -

taskDefinition

Creates an ECS task definition with container configuration, logging, and optional init container.

function taskDefinition(ctx: Context, args: TaskDefinitionArgs): TaskDefinition

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (TaskDefinitionArgs) - Configuration arguments for the task definition

Returns

• (TaskDefinition) - Creates an ECS task definition with container configuration, logging, and optional init container.

Interfaces

ServiceArgs

Configuration arguments for creating an ECS service, extending TaskDefinitionArgs.

Properties

• autoScaling? (Omit<ServiceAutoScalingArgs, "service">) - Specify an auto-scaling configuration for your service. Cannot be used with replicas. See the serviceAutoScaling component for argument documentation.
• cluster (Input<ClusterResourcesInput>) - The ECS cluster to run the service in.
• command? (Input<string[]>) - Optional command to override the container’s default command.
• cpu? (Input<number>) - CPU limit in CPU units, where 1024 = 1 vCPU (defaults to 512).
• domain? (Input<string>) - Custom domain name for external access (requires loadBalancer).
• env? (Record<string, Input<string>>) - Environment variables to pass to the container.
• healthcheck? ({ command?: Input<string>; interval?: Input<number>; path?: Input<string>; retries?: Input<number>; startPeriod?: Input<number> }) - Health check configuration for the container.
• image (Input<string>) - The Docker image to run (e.g., “nginx:latest”, “my-registry/my-app:v1.0”).
• init? ({ command: Input<string[]>; env?: Record<string, Input<string>>; image?: Input<string>; stopTimeout?: Input<number> }) - Configuration for an init container that runs before the main container.
• loadBalancer? (LoadBalancerWithListener) - Load balancer configuration for external traffic routing. This must be passed if domain is specified.
• logGroup? (Input<string>) - The name of a log group to write logs to. If not specified, a new log group will be created with a 30 day retention period.
• memory? (Input<number>) - Memory limit in MB (defaults to 512).
• name (Input<string>) - The name of the container and ECS task family.
• network (NetworkInput) - The VPC network configuration for the service.
• noPrefix? (boolean) - Whether to skip adding a prefix to resource names.
• orderedPlacementStrategies? (Input<Input<ServiceOrderedPlacementStrategy>[]>) - Service level strategy rules that are taken into consideration during task placement. List from top to bottom in order of precedence. Default behavior is to use the binpack strategy on cpu.
• port? (Input<number>) - Port the container exposes (required for load balancer integration).
• replicas? (Input<number>) - Number of tasks to run (cannot be used with autoScaling).
• role? (Input<string>) - IAM role ARN for the task to assume (for AWS API access).
• securityGroups? (Input<Input<string>[]>) - Custom security groups for the service (uses VPC default if not specified).
• zone? (Input<string>) - Route53 hosted zone ID for the domain (auto-detected if not specified).

ServiceOutput

Output from creating an ECS service, containing the service resource and URLs.

Properties

• internalUrl? (Output<string>) - Internal service discovery URL for VPC communication (only available if port is configured)
• service (Service) - The ECS service resource.
• url? (Output<string>) - External URL for the service (only available if domain is configured).

TaskDefinitionArgs

Configuration arguments for creating an ECS task definition.

Properties

• command? (Input<string[]>) - Optional command to override the container’s default command.
• cpu? (Input<number>) - CPU limit in CPU units, where 1024 = 1 vCPU (defaults to 512).
• env? (Record<string, Input<string>>) - Environment variables to pass to the container.
• healthcheck? ({ command?: Input<string>; interval?: Input<number>; path?: Input<string>; retries?: Input<number>; startPeriod?: Input<number> }) - Health check configuration for the container.
• image (Input<string>) - The Docker image to run (e.g., “nginx:latest”, “my-registry/my-app:v1.0”).
• init? ({ command: Input<string[]>; env?: Record<string, Input<string>>; image?: Input<string>; stopTimeout?: Input<number> }) - Configuration for an init container that runs before the main container.
• logGroup? (Input<string>) - The name of a log group to write logs to. If not specified, a new log group will be created with a 30 day retention period.
• memory? (Input<number>) - Memory limit in MB (defaults to 512).
• name (Input<string>) - The name of the container and ECS task family.
• noPrefix? (boolean) - Whether to skip adding a prefix to resource names.
• port? (Input<number>) - Port the container exposes (required for load balancer integration).
• role? (Input<string>) - IAM role ARN for the task to assume (for AWS API access).

Types

ServiceInput

type ServiceInput = string | aws.ecs.Service | ServiceOutput