ExpressGatewayService class

Manages an ECS Express service. The Express service provides a simplified way to deploy containerized applications with automatic provisioning and management of AWS infrastructure including Application Load Balancers (ALBs), target groups, security groups, and auto-scaling policies. This service offers built-in load balancing, auto-scaling, and networking capabilities with zero-downtime deployments.

> Note: To prevent a race condition during service deletion, make sure to set dependsOn to the related aws.iam.RolePolicy or aws.iam.RolePolicyAttachment resources. Otherwise, the policy may be destroyed too soon and the ECS service will then get stuck in the DRAINING state.

Example Usage

Basic Usage

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.ecs.ExpressGatewayService("example", {
    primaryContainer: {
        image: "nginx:latest",
    },
    executionRoleArn: execution.arn,
    infrastructureRoleArn: infrastructure.arn,
});
import pulumi
import pulumi_aws as aws

example = aws.ecs.ExpressGatewayService("example",
    primary_container={
        "image": "nginx:latest",
    },
    execution_role_arn=execution["arn"],
    infrastructure_role_arn=infrastructure["arn"])
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() =>
{
    var example = new Aws.Ecs.ExpressGatewayService("example", new()
    {
        PrimaryContainer = new Aws.Ecs.Inputs.ExpressGatewayServicePrimaryContainerArgs
        {
            Image = "nginx:latest",
        },
        ExecutionRoleArn = execution.Arn,
        InfrastructureRoleArn = infrastructure.Arn,
    });

});
package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/ecs"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := ecs.NewExpressGatewayService(ctx, "example", &ecs.ExpressGatewayServiceArgs{
			PrimaryContainer: &ecs.ExpressGatewayServicePrimaryContainerArgs{
				Image: pulumi.String("nginx:latest"),
			},
			ExecutionRoleArn:      pulumi.Any(execution.Arn),
			InfrastructureRoleArn: pulumi.Any(infrastructure.Arn),
		})
		if err != nil {
			return err
		}
		return nil
	})
}
pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

resource "aws_ecs_expressgatewayservice" "example" {
  primary_container = {
    image = "nginx:latest"
  }
  execution_role_arn      = execution.arn
  infrastructure_role_arn = infrastructure.arn
}
package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.ecs.ExpressGatewayService;
import com.pulumi.aws.ecs.ExpressGatewayServiceArgs;
import com.pulumi.aws.ecs.inputs.ExpressGatewayServicePrimaryContainerArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new ExpressGatewayService("example", ExpressGatewayServiceArgs.builder()
            .primaryContainer(ExpressGatewayServicePrimaryContainerArgs.builder()
                .image("nginx:latest")
                .build())
            .executionRoleArn(execution.arn())
            .infrastructureRoleArn(infrastructure.arn())
            .build());

    }
}
resources:
  example:
    type: aws:ecs:ExpressGatewayService
    properties:
      primaryContainer:
        image: nginx:latest
      executionRoleArn: ${execution.arn}
      infrastructureRoleArn: ${infrastructure.arn}

Container Logging, Environment Variables, and Secrets

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.ecs.ExpressGatewayService("example", {
    primaryContainer: {
        awsLogsConfigurations: [{
            logGroup: app.name,
        }],
        environments: [
            {
                name: "ENV",
                value: "production",
            },
            {
                name: "PORT",
                value: "8080",
            },
        ],
        secrets: [{
            name: "DB_PASSWORD",
            valueFrom: dbPassword.arn,
        }],
        image: "my-app:latest",
        containerPort: 8080,
        commands: ["./start.sh"],
    },
    executionRoleArn: execution.arn,
    infrastructureRoleArn: infrastructure.arn,
    healthCheckPath: "/health",
});
import pulumi
import pulumi_aws as aws

example = aws.ecs.ExpressGatewayService("example",
    primary_container={
        "aws_logs_configurations": [{
            "log_group": app["name"],
        }],
        "environments": [
            {
                "name": "ENV",
                "value": "production",
            },
            {
                "name": "PORT",
                "value": "8080",
            },
        ],
        "secrets": [{
            "name": "DB_PASSWORD",
            "value_from": db_password["arn"],
        }],
        "image": "my-app:latest",
        "container_port": 8080,
        "commands": ["./start.sh"],
    },
    execution_role_arn=execution["arn"],
    infrastructure_role_arn=infrastructure["arn"],
    health_check_path="/health")
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() =>
{
    var example = new Aws.Ecs.ExpressGatewayService("example", new()
    {
        PrimaryContainer = new Aws.Ecs.Inputs.ExpressGatewayServicePrimaryContainerArgs
        {
            AwsLogsConfigurations = new[]
            {
                new Aws.Ecs.Inputs.ExpressGatewayServicePrimaryContainerAwsLogsConfigurationArgs
                {
                    LogGroup = app.Name,
                },
            },
            Environments = new[]
            {
                new Aws.Ecs.Inputs.ExpressGatewayServicePrimaryContainerEnvironmentArgs
                {
                    Name = "ENV",
                    Value = "production",
                },
                new Aws.Ecs.Inputs.ExpressGatewayServicePrimaryContainerEnvironmentArgs
                {
                    Name = "PORT",
                    Value = "8080",
                },
            },
            Secrets = new[]
            {
                new Aws.Ecs.Inputs.ExpressGatewayServicePrimaryContainerSecretArgs
                {
                    Name = "DB_PASSWORD",
                    ValueFrom = dbPassword.Arn,
                },
            },
            Image = "my-app:latest",
            ContainerPort = 8080,
            Commands = new[]
            {
                "./start.sh",
            },
        },
        ExecutionRoleArn = execution.Arn,
        InfrastructureRoleArn = infrastructure.Arn,
        HealthCheckPath = "/health",
    });

});
package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/ecs"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := ecs.NewExpressGatewayService(ctx, "example", &ecs.ExpressGatewayServiceArgs{
			PrimaryContainer: &ecs.ExpressGatewayServicePrimaryContainerArgs{
				AwsLogsConfigurations: ecs.ExpressGatewayServicePrimaryContainerAwsLogsConfigurationArray{
					&ecs.ExpressGatewayServicePrimaryContainerAwsLogsConfigurationArgs{
						LogGroup: pulumi.Any(app.Name),
					},
				},
				Environments: ecs.ExpressGatewayServicePrimaryContainerEnvironmentArray{
					&ecs.ExpressGatewayServicePrimaryContainerEnvironmentArgs{
						Name:  pulumi.String("ENV"),
						Value: pulumi.String("production"),
					},
					&ecs.ExpressGatewayServicePrimaryContainerEnvironmentArgs{
						Name:  pulumi.String("PORT"),
						Value: pulumi.String("8080"),
					},
				},
				Secrets: ecs.ExpressGatewayServicePrimaryContainerSecretArray{
					&ecs.ExpressGatewayServicePrimaryContainerSecretArgs{
						Name:      pulumi.String("DB_PASSWORD"),
						ValueFrom: pulumi.Any(dbPassword.Arn),
					},
				},
				Image:         pulumi.String("my-app:latest"),
				ContainerPort: pulumi.Int(8080),
				Commands: pulumi.StringArray{
					pulumi.String("./start.sh"),
				},
			},
			ExecutionRoleArn:      pulumi.Any(execution.Arn),
			InfrastructureRoleArn: pulumi.Any(infrastructure.Arn),
			HealthCheckPath:       pulumi.String("/health"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}
pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

resource "aws_ecs_expressgatewayservice" "example" {
  primary_container = {
    aws_logs_configurations = [{
      "logGroup" = app.name
    }]
    environments = [{
      "name"  = "ENV"
      "value" = "production"
      }, {
      "name"  = "PORT"
      "value" = "8080"
    }]
    secrets = [{
      "name"      = "DB_PASSWORD"
      "valueFrom" = dbPassword.arn
    }]
    image          = "my-app:latest"
    container_port = 8080
    commands       = ["./start.sh"]
  }
  execution_role_arn      = execution.arn
  infrastructure_role_arn = infrastructure.arn
  health_check_path       = "/health"
}
package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.ecs.ExpressGatewayService;
import com.pulumi.aws.ecs.ExpressGatewayServiceArgs;
import com.pulumi.aws.ecs.inputs.ExpressGatewayServicePrimaryContainerArgs;
import com.pulumi.aws.ecs.inputs.ExpressGatewayServicePrimaryContainerAwsLogsConfigurationArgs;
import com.pulumi.aws.ecs.inputs.ExpressGatewayServicePrimaryContainerEnvironmentArgs;
import com.pulumi.aws.ecs.inputs.ExpressGatewayServicePrimaryContainerSecretArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new ExpressGatewayService("example", ExpressGatewayServiceArgs.builder()
            .primaryContainer(ExpressGatewayServicePrimaryContainerArgs.builder()
                .awsLogsConfigurations(ExpressGatewayServicePrimaryContainerAwsLogsConfigurationArgs.builder()
                    .logGroup(app.name())
                    .build())
                .environments(
                    ExpressGatewayServicePrimaryContainerEnvironmentArgs.builder()
                        .name("ENV")
                        .value("production")
                        .build(),
                    ExpressGatewayServicePrimaryContainerEnvironmentArgs.builder()
                        .name("PORT")
                        .value("8080")
                        .build())
                .secrets(ExpressGatewayServicePrimaryContainerSecretArgs.builder()
                    .name("DB_PASSWORD")
                    .valueFrom(dbPassword.arn())
                    .build())
                .image("my-app:latest")
                .containerPort(8080)
                .commands("./start.sh")
                .build())
            .executionRoleArn(execution.arn())
            .infrastructureRoleArn(infrastructure.arn())
            .healthCheckPath("/health")
            .build());

    }
}
resources:
  example:
    type: aws:ecs:ExpressGatewayService
    properties:
      primaryContainer:
        awsLogsConfigurations:
          - logGroup: ${app.name}
        environments:
          - name: ENV
            value: production
          - name: PORT
            value: '8080'
        secrets:
          - name: DB_PASSWORD
            valueFrom: ${dbPassword.arn}
        image: my-app:latest
        containerPort: 8080
        commands:
          - ./start.sh
      executionRoleArn: ${execution.arn}
      infrastructureRoleArn: ${infrastructure.arn}
      healthCheckPath: /health

Custom Networking

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = new aws.ecs.ExpressGatewayService("example", {
    primaryContainer: {
        image: "nginx:latest",
        containerPort: 80,
    },
    networkConfigurations: [{
        subnets: [
            privateA.id,
            privateB.id,
        ],
        securityGroups: [app.id],
    }],
    serviceName: "my-express-service",
    cluster: main.name,
    executionRoleArn: execution.arn,
    infrastructureRoleArn: infrastructure.arn,
    cpu: "256",
    memory: "512",
});
import pulumi
import pulumi_aws as aws

example = aws.ecs.ExpressGatewayService("example",
    primary_container={
        "image": "nginx:latest",
        "container_port": 80,
    },
    network_configurations=[{
        "subnets": [
            private_a["id"],
            private_b["id"],
        ],
        "security_groups": [app["id"]],
    }],
    service_name="my-express-service",
    cluster=main["name"],
    execution_role_arn=execution["arn"],
    infrastructure_role_arn=infrastructure["arn"],
    cpu="256",
    memory="512")
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() =>
{
    var example = new Aws.Ecs.ExpressGatewayService("example", new()
    {
        PrimaryContainer = new Aws.Ecs.Inputs.ExpressGatewayServicePrimaryContainerArgs
        {
            Image = "nginx:latest",
            ContainerPort = 80,
        },
        NetworkConfigurations = new[]
        {
            new Aws.Ecs.Inputs.ExpressGatewayServiceNetworkConfigurationArgs
            {
                Subnets = new[]
                {
                    privateA.Id,
                    privateB.Id,
                },
                SecurityGroups = new[]
                {
                    app.Id,
                },
            },
        },
        ServiceName = "my-express-service",
        Cluster = main.Name,
        ExecutionRoleArn = execution.Arn,
        InfrastructureRoleArn = infrastructure.Arn,
        Cpu = "256",
        Memory = "512",
    });

});
package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/ecs"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := ecs.NewExpressGatewayService(ctx, "example", &ecs.ExpressGatewayServiceArgs{
			PrimaryContainer: &ecs.ExpressGatewayServicePrimaryContainerArgs{
				Image:         pulumi.String("nginx:latest"),
				ContainerPort: pulumi.Int(80),
			},
			NetworkConfigurations: ecs.ExpressGatewayServiceNetworkConfigurationArray{
				&ecs.ExpressGatewayServiceNetworkConfigurationArgs{
					Subnets: pulumi.StringArray{
						privateA.Id,
						privateB.Id,
					},
					SecurityGroups: pulumi.StringArray{
						app.Id,
					},
				},
			},
			ServiceName:           pulumi.String("my-express-service"),
			Cluster:               pulumi.Any(main.Name),
			ExecutionRoleArn:      pulumi.Any(execution.Arn),
			InfrastructureRoleArn: pulumi.Any(infrastructure.Arn),
			Cpu:                   pulumi.String("256"),
			Memory:                pulumi.String("512"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}
pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

resource "aws_ecs_expressgatewayservice" "example" {
  primary_container = {
    image          = "nginx:latest"
    container_port = 80
  }
  network_configurations {
    subnets         = [privateA.id, privateB.id]
    security_groups = [app.id]
  }
  service_name            = "my-express-service"
  cluster                 = main.name
  execution_role_arn      = execution.arn
  infrastructure_role_arn = infrastructure.arn
  cpu                     = "256"
  memory                  = "512"
}
package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.ecs.ExpressGatewayService;
import com.pulumi.aws.ecs.ExpressGatewayServiceArgs;
import com.pulumi.aws.ecs.inputs.ExpressGatewayServicePrimaryContainerArgs;
import com.pulumi.aws.ecs.inputs.ExpressGatewayServiceNetworkConfigurationArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var example = new ExpressGatewayService("example", ExpressGatewayServiceArgs.builder()
            .primaryContainer(ExpressGatewayServicePrimaryContainerArgs.builder()
                .image("nginx:latest")
                .containerPort(80)
                .build())
            .networkConfigurations(ExpressGatewayServiceNetworkConfigurationArgs.builder()
                .subnets(
                    privateA.id(),
                    privateB.id())
                .securityGroups(app.id())
                .build())
            .serviceName("my-express-service")
            .cluster(main.name())
            .executionRoleArn(execution.arn())
            .infrastructureRoleArn(infrastructure.arn())
            .cpu("256")
            .memory("512")
            .build());

    }
}
resources:
  example:
    type: aws:ecs:ExpressGatewayService
    properties:
      primaryContainer:
        image: nginx:latest
        containerPort: 80
      networkConfigurations:
        - subnets:
            - ${privateA.id}
            - ${privateB.id}
          securityGroups:
            - ${app.id}
      serviceName: my-express-service
      cluster: ${main.name}
      executionRoleArn: ${execution.arn}
      infrastructureRoleArn: ${infrastructure.arn}
      cpu: '256'
      memory: '512'

Service Updates and Deletion

Updates

When you update an Express service configuration, a new service revision is created and deployed using a canary deployment strategy with zero downtime. For more information, see Updating an Express service.

Deletion

When an Express service is deleted, it enters a DRAINING state where existing tasks are allowed to complete gracefully before termination. The deletion process is irreversible - once initiated, the service and all its associated AWS infrastructure (load balancers, target groups, etc.) will be permanently removed. During the draining process, no new tasks are started, and the service becomes unavailable once all tasks have completed.

Import

Using pulumi import, import ECS Express Gateway Services using the service ARN. For example:

$ pulumi import aws:ecs/expressGatewayService:ExpressGatewayService example arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-express-gateway-service

Constructors

ExpressGatewayService(String name, {ExpressGatewayServiceArgs? args, CustomResourceOptions? options})
Creates a new ExpressGatewayService. name The Pulumi resource name. args Arguments used to configure this ExpressGatewayService. The set of arguments for ExpressGatewayService. options Resource options controlling this resource's behavior.
ExpressGatewayService.reference(String urn)
Creates a typed reference to an existing ExpressGatewayService resource.

Properties

childResources → Set<Resource>
finalinherited
cluster ↔ Output<String>
Name or ARN of the ECS cluster. Defaults to default.
latefinal
completionSources ↔ Map<String, IOutputCompletionSource>
latefinalinherited
cpu ↔ Output<String>
Number of CPU units used by the task. Valid values are powers of 2 between 256 and 4096. Defaults to 1024.
latefinal
currentDeployment ↔ Output<String>
(Deprecated) ARN of the current deployment.
latefinal
executionRoleArn ↔ Output<String>
ARN of the IAM role that allows ECS to pull container images and publish container logs to Amazon CloudWatch.
latefinal
hashCode → int
The hash code for this object.
no setterinherited
healthCheckPath ↔ Output<String>
Path for health check requests. Defaults to /.
latefinal
id ↔ Output<String>
getter/setter pairinherited
infrastructureRoleArn ↔ Output<String>
ARN of the IAM role that allows ECS to manage AWS infrastructure on your behalf. Important: The infrastructure role cannot be modified after the service is created. Changing this forces a new resource to be created.
latefinal
ingressPaths ↔ Output<List<ExpressGatewayServiceIngressPath>>
List of ingress paths for the service. See ingressPaths Block below.
latefinal
isCustom → bool
Returns whether this resource is provider-managed.
no setterinherited
isProtected → bool
Returns whether this resource is protected from deletion.
no setterinherited
isRemote → bool
Whether this resource is registered as remote.
no setterinherited
isResourceReference → bool
Whether this instance represents a resource value returned over RPC.
finalinherited
memory ↔ Output<String>
Amount of memory (in MiB) used by the task. Valid values are between 512 and 8192. Defaults to 2048.
latefinal
networkConfigurations ↔ Output<List<ExpressGatewayServiceNetworkConfiguration>>
Network configuration for the service. See networkConfiguration Block below.
latefinal
primaryContainer ↔ Output<ExpressGatewayServicePrimaryContainer>
latefinal
region ↔ Output<String>
AWS region where the service will be created. If not specified, the region configured in the provider will be used.
latefinal
resourceTransforms → List<ResourceTransform>
Inherited/explicit async transforms.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scalingTargets ↔ Output<List<ExpressGatewayServiceScalingTarget>>
Auto-scaling configuration for the service. See scalingTarget Block below.
latefinal
serviceArn ↔ Output<String>
ARN of the Express Gateway Service.
latefinal
serviceName ↔ Output<String>
Name of the service. If not specified, a name will be generated. Changing this forces a new resource to be created.
latefinal
serviceRevisionArn ↔ Output<String>
ARN of the service revision.
latefinal
tags ↔ Output<Map<String, String>?>
Key-value map of resource tags. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
latefinal
tagsAll ↔ Output<Map<String, String>>
Map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.
latefinal
taskRoleArn ↔ Output<String?>
ARN of the IAM role that allows your Amazon ECS container task to make calls to other AWS services.
latefinal
timeouts ↔ Output<ExpressGatewayServiceTimeouts?>
latefinal
transformations → List<ResourceTransformation>
Inherited/explicit legacy transformations.
no setterinherited
urn ↔ Output<String>
latefinalinherited
waitForSteadyState ↔ Output<bool>
Whether to wait for the service to reach a steady state before considering the operation complete. Defaults to false.
latefinal

Methods

failId(Object error) → void
Completes this resource ID with an error when registration fails.
inherited
failOutputs(Object error) → void
Completes all output properties with error.
inherited
failUrn(Object error) → void
Completes this resource URN with an error when registration fails.
inherited
getProvider(String moduleMember) → ProviderResource?
Returns provider for moduleMember's package, if configured.
inherited
getResourceName() → String
Returns this resource's logical name.
inherited
getResourceType() → String
Returns this resource's Pulumi type token.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
registerOutput<T>(String propertyName, {Object? decoder(Object?)?, bool isSecret = false}) → Output<T>
Registers a dynamic output property for this resource.
inherited
resolveId(String? value, {required bool isKnown}) → void
Resolves the provider-assigned ID for this resource.
inherited
resolveOutputs(Struct outputs) → void
Resolves all output properties from a monitor response payload.
inherited
resolveUrn(String value) → void
Resolves this resource's URN once assigned by the engine.
inherited
serializeProperties(Map<String, dynamic> properties) → Future<Struct>
Serializes resource properties for RPC transmission.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

get(String name, Input<String> id, {ExpressGatewayServiceState? state, CustomResourceOptions? options}) → ExpressGatewayService
Gets an existing ExpressGatewayService resource's state with the given name and id.