Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Running workloads on external instances

After an external instance is registered to your cluster, you can run your containerized workloads. The first step is to register a task definition. Amazon ECS provides the requiresCompatibilities parameter to validate the task definition is compatible with your external instances. When you deploy your workload, use the EXTERNAL launch type when creating your service or running your standalone task.

Creating a task definition that is compatible with your external instances

When registering an Amazon ECS task definition, use the requiresCompatibilities parameter and specify EXTERNAL which validates that the task definition is compatible to use when running Amazon ECS workloads on your external instances. For more information, see Creating a task definition using the new console.

The following is an example task definition.

Linux

{
	"requiresCompatibilities": [
		"EXTERNAL"
	],
	"containerDefinitions": [{
		"name": "nginx",
		"image": "public.ecr.aws/nginx/nginx:latest",
		"memory": 256,
		"cpu": 256,
		"essential": true,
		"portMappings": [{
			"containerPort": 80,
			"hostPort": 8080,
			"protocol": "tcp"
		}]
	}],
	"networkMode": "bridge",
	"family": "nginx"
}

Windows

{
	"requiresCompatibilities": [
		"EXTERNAL"
	],
	"containerDefinitions": [{
		"name": "windows-container",
		"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
		"memory": 256,
		"cpu": 512,
		"essential": true,
		"portMappings": [{
			"containerPort": 80,
			"hostPort": 8080,
			"protocol": "tcp"
		}]
	}],
	"networkMode": "bridge",
	"family": "windows-container"
}

Running a standalone task or creating a service

After you register your external instances to your cluster, grant the relevant IAM permissions, and register a valid task definition, you can start to run your workloads on Amazon ECS. When running your standalone tasks or creating a service, specify the EXTERNAL launch type, and the Amazon ECS scheduler places the tasks on your external instances.

For instructions on how to create services, see Creating an Amazon ECS service.

For more information about running standalone tasks, see Run a standalone task.

Verifying your running tasks on an external Windows instance

After you launch a task, you can verify the status by checking the Amazon ECS agent log (ecs-agent.log) which is located in the \ProgramData\Amazon\ECS\log directory.