CreateCapacityProvider

$result = $client->createCapacityProvider([/* ... */]);
$promise = $client->createCapacityProviderAsync([/* ... */]);

Creates a new capacity provider. Capacity providers are associated with an Amazon ECS cluster and are used in capacity provider strategies to facilitate cluster auto scaling.

Only capacity providers that use an Auto Scaling group can be created. Amazon ECS tasks on Fargate use the FARGATE and FARGATE_SPOT capacity providers. These providers are available to all accounts in the Amazon Web Services Regions that Fargate supports.

Parameter Syntax

$result = $client->createCapacityProvider([
    'autoScalingGroupProvider' => [ // REQUIRED
        'autoScalingGroupArn' => '<string>', // REQUIRED
        'managedDraining' => 'ENABLED|DISABLED',
        'managedScaling' => [
            'instanceWarmupPeriod' => <integer>,
            'maximumScalingStepSize' => <integer>,
            'minimumScalingStepSize' => <integer>,
            'status' => 'ENABLED|DISABLED',
            'targetCapacity' => <integer>,
        ],
        'managedTerminationProtection' => 'ENABLED|DISABLED',
    ],
    'name' => '<string>', // REQUIRED
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'capacityProvider' => [
        'autoScalingGroupProvider' => [
            'autoScalingGroupArn' => '<string>',
            'managedDraining' => 'ENABLED|DISABLED',
            'managedScaling' => [
                'instanceWarmupPeriod' => <integer>,
                'maximumScalingStepSize' => <integer>,
                'minimumScalingStepSize' => <integer>,
                'status' => 'ENABLED|DISABLED',
                'targetCapacity' => <integer>,
            ],
            'managedTerminationProtection' => 'ENABLED|DISABLED',
        ],
        'capacityProviderArn' => '<string>',
        'name' => '<string>',
        'status' => 'ACTIVE|INACTIVE',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'updateStatus' => 'DELETE_IN_PROGRESS|DELETE_COMPLETE|DELETE_FAILED|UPDATE_IN_PROGRESS|UPDATE_COMPLETE|UPDATE_FAILED',
        'updateStatusReason' => '<string>',
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

LimitExceededException:

The limit for the resource was exceeded.

UpdateInProgressException:

There's already a current Amazon ECS container agent update in progress on the container instance that's specified. If the container agent becomes disconnected while it's in a transitional stage, such as PENDING or STAGING, the update process can get stuck in that state. However, when the agent reconnects, it resumes where it stopped previously.

Examples

Example 1: To create a capacity provider

This example creates a capacity provider that uses the specified Auto Scaling group MyASG and has managed scaling and manager termination protection enabled.

$result = $client->createCapacityProvider([
    'name' => 'MyCapacityProvider',
    'autoScalingGroupProvider' => [
        'autoScalingGroupArn' => 'arn:aws:autoscaling:us-east-1:123456789012:autoScalingGroup:57ffcb94-11f0-4d6d-bf60-3bac5EXAMPLE:autoScalingGroupName/MyASG',
        'managedScaling' => [
            'status' => 'ENABLED',
            'targetCapacity' => 100,
        ],
        'managedTerminationProtection' => 'ENABLED',
    ],
]);

Result syntax:

[
    'capacityProvider' => [
        'name' => 'MyCapacityProvider',
        'autoScalingGroupProvider' => [
            'autoScalingGroupArn' => 'arn:aws:autoscaling:us-east-1:132456789012:autoScalingGroup:57ffcb94-11f0-4d6d-bf60-3bac5EXAMPLE:autoScalingGroupName/MyASG',
            'managedScaling' => [
                'instanceWarmupPeriod' => 300,
                'maximumScalingStepSize' => 10000,
                'minimumScalingStepSize' => 1,
                'status' => 'ENABLED',
                'targetCapacity' => 100,
            ],
            'managedTerminationProtection' => 'ENABLED',
        ],
        'capacityProviderArn' => 'arn:aws:ecs:us-east-1:123456789012:capacity-provider/MyCapacityProvider',
        'status' => 'ACTIVE',
        'tags' => [
        ],
    ],
]

CreateCluster

$result = $client->createCluster([/* ... */]);
$promise = $client->createClusterAsync([/* ... */]);

Creates a new Amazon ECS cluster. By default, your account receives a default cluster when you launch your first container instance. However, you can create your own cluster with a unique name.

Parameter Syntax

$result = $client->createCluster([
    'capacityProviders' => ['<string>', ...],
    'clusterName' => '<string>',
    'configuration' => [
        'executeCommandConfiguration' => [
            'kmsKeyId' => '<string>',
            'logConfiguration' => [
                'cloudWatchEncryptionEnabled' => true || false,
                'cloudWatchLogGroupName' => '<string>',
                's3BucketName' => '<string>',
                's3EncryptionEnabled' => true || false,
                's3KeyPrefix' => '<string>',
            ],
            'logging' => 'NONE|DEFAULT|OVERRIDE',
        ],
        'managedStorageConfiguration' => [
            'fargateEphemeralStorageKmsKeyId' => '<string>',
            'kmsKeyId' => '<string>',
        ],
    ],
    'defaultCapacityProviderStrategy' => [
        [
            'base' => <integer>,
            'capacityProvider' => '<string>', // REQUIRED
            'weight' => <integer>,
        ],
        // ...
    ],
    'serviceConnectDefaults' => [
        'namespace' => '<string>', // REQUIRED
    ],
    'settings' => [
        [
            'name' => 'containerInsights',
            'value' => '<string>',
        ],
        // ...
    ],
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'cluster' => [
        'activeServicesCount' => <integer>,
        'attachments' => [
            [
                'details' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'id' => '<string>',
                'status' => '<string>',
                'type' => '<string>',
            ],
            // ...
        ],
        'attachmentsStatus' => '<string>',
        'capacityProviders' => ['<string>', ...],
        'clusterArn' => '<string>',
        'clusterName' => '<string>',
        'configuration' => [
            'executeCommandConfiguration' => [
                'kmsKeyId' => '<string>',
                'logConfiguration' => [
                    'cloudWatchEncryptionEnabled' => true || false,
                    'cloudWatchLogGroupName' => '<string>',
                    's3BucketName' => '<string>',
                    's3EncryptionEnabled' => true || false,
                    's3KeyPrefix' => '<string>',
                ],
                'logging' => 'NONE|DEFAULT|OVERRIDE',
            ],
            'managedStorageConfiguration' => [
                'fargateEphemeralStorageKmsKeyId' => '<string>',
                'kmsKeyId' => '<string>',
            ],
        ],
        'defaultCapacityProviderStrategy' => [
            [
                'base' => <integer>,
                'capacityProvider' => '<string>',
                'weight' => <integer>,
            ],
            // ...
        ],
        'pendingTasksCount' => <integer>,
        'registeredContainerInstancesCount' => <integer>,
        'runningTasksCount' => <integer>,
        'serviceConnectDefaults' => [
            'namespace' => '<string>',
        ],
        'settings' => [
            [
                'name' => 'containerInsights',
                'value' => '<string>',
            ],
            // ...
        ],
        'statistics' => [
            [
                'name' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'status' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

NamespaceNotFoundException:

The specified namespace wasn't found.

Examples

Example 1: To create a new cluster

This example creates a cluster in your default region.

$result = $client->createCluster([
    'clusterName' => 'my_cluster',
]);

Result syntax:

[
    'cluster' => [
        'activeServicesCount' => 0,
        'clusterArn' => 'arn:aws:ecs:us-east-1:012345678910:cluster/my_cluster',
        'clusterName' => 'my_cluster',
        'pendingTasksCount' => 0,
        'registeredContainerInstancesCount' => 0,
        'runningTasksCount' => 0,
        'status' => 'ACTIVE',
    ],
]

CreateService

$result = $client->createService([/* ... */]);
$promise = $client->createServiceAsync([/* ... */]);

Runs and maintains your desired number of tasks from a specified task definition. If the number of tasks running in a service drops below the desiredCount, Amazon ECS runs another copy of the task in the specified cluster. To update an existing service, use UpdateService.

In addition to maintaining the desired count of tasks in your service, you can optionally run your service behind one or more load balancers. The load balancers distribute traffic across the tasks that are associated with the service. For more information, see Service load balancing in the Amazon Elastic Container Service Developer Guide.

You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when creating or updating a service. volumeConfigurations is only supported for REPLICA service and not DAEMON service. For more information, see Amazon EBS volumes in the Amazon Elastic Container Service Developer Guide.

Tasks for services that don't use a load balancer are considered healthy if they're in the RUNNING state. Tasks for services that use a load balancer are considered healthy if they're in the RUNNING state and are reported as healthy by the load balancer.

There are two service scheduler strategies available:

• REPLICA - The replica scheduling strategy places and maintains your desired number of tasks across your cluster. By default, the service scheduler spreads tasks across Availability Zones. You can use task placement strategies and constraints to customize task placement decisions. For more information, see Service scheduler concepts in the Amazon Elastic Container Service Developer Guide.

• DAEMON - The daemon scheduling strategy deploys exactly one task on each active container instance that meets all of the task placement constraints that you specify in your cluster. The service scheduler also evaluates the task placement constraints for running tasks. It also stops tasks that don't meet the placement constraints. When using this strategy, you don't need to specify a desired number of tasks, a task placement strategy, or use Service Auto Scaling policies. For more information, see Service scheduler concepts in the Amazon Elastic Container Service Developer Guide.

You can optionally specify a deployment configuration for your service. The deployment is initiated by changing properties. For example, the deployment might be initiated by the task definition or by your desired count of a service. You can use UpdateService. The default value for a replica service for minimumHealthyPercent is 100%. The default value for a daemon service for minimumHealthyPercent is 0%.

If a service uses the ECS deployment controller, the minimum healthy percent represents a lower limit on the number of tasks in a service that must remain in the RUNNING state during a deployment. Specifically, it represents it as a percentage of your desired number of tasks (rounded up to the nearest integer). This happens when any of your container instances are in the DRAINING state if the service contains tasks using the EC2 launch type. Using this parameter, you can deploy without using additional cluster capacity. For example, if you set your service to have desired number of four tasks and a minimum healthy percent of 50%, the scheduler might stop two existing tasks to free up cluster capacity before starting two new tasks. If they're in the RUNNING state, tasks for services that don't use a load balancer are considered healthy . If they're in the RUNNING state and reported as healthy by the load balancer, tasks for services that do use a load balancer are considered healthy . The default value for minimum healthy percent is 100%.

If a service uses the ECS deployment controller, the maximum percent parameter represents an upper limit on the number of tasks in a service that are allowed in the RUNNING or PENDING state during a deployment. Specifically, it represents it as a percentage of the desired number of tasks (rounded down to the nearest integer). This happens when any of your container instances are in the DRAINING state if the service contains tasks using the EC2 launch type. Using this parameter, you can define the deployment batch size. For example, if your service has a desired number of four tasks and a maximum percent value of 200%, the scheduler may start four new tasks before stopping the four older tasks (provided that the cluster resources required to do this are available). The default value for maximum percent is 200%.

If a service uses either the CODE_DEPLOY or EXTERNAL deployment controller types and tasks that use the EC2 launch type, the minimum healthy percent and maximum percent values are used only to define the lower and upper limit on the number of the tasks in the service that remain in the RUNNING state. This is while the container instances are in the DRAINING state. If the tasks in the service use the Fargate launch type, the minimum healthy percent and maximum percent values aren't used. This is the case even if they're currently visible when describing your service.

When creating a service that uses the EXTERNAL deployment controller, you can specify only parameters that aren't controlled at the task set level. The only required parameter is the service name. You control your services using the CreateTaskSet. For more information, see Amazon ECS deployment types in the Amazon Elastic Container Service Developer Guide.

When the service scheduler launches new tasks, it determines task placement. For information about task placement and task placement strategies, see Amazon ECS task placement in the Amazon Elastic Container Service Developer Guide

Parameter Syntax

$result = $client->createService([
    'availabilityZoneRebalancing' => 'ENABLED|DISABLED',
    'capacityProviderStrategy' => [
        [
            'base' => <integer>,
            'capacityProvider' => '<string>', // REQUIRED
            'weight' => <integer>,
        ],
        // ...
    ],
    'clientToken' => '<string>',
    'cluster' => '<string>',
    'deploymentConfiguration' => [
        'alarms' => [
            'alarmNames' => ['<string>', ...], // REQUIRED
            'enable' => true || false, // REQUIRED
            'rollback' => true || false, // REQUIRED
        ],
        'deploymentCircuitBreaker' => [
            'enable' => true || false, // REQUIRED
            'rollback' => true || false, // REQUIRED
        ],
        'maximumPercent' => <integer>,
        'minimumHealthyPercent' => <integer>,
    ],
    'deploymentController' => [
        'type' => 'ECS|CODE_DEPLOY|EXTERNAL', // REQUIRED
    ],
    'desiredCount' => <integer>,
    'enableECSManagedTags' => true || false,
    'enableExecuteCommand' => true || false,
    'healthCheckGracePeriodSeconds' => <integer>,
    'launchType' => 'EC2|FARGATE|EXTERNAL',
    'loadBalancers' => [
        [
            'containerName' => '<string>',
            'containerPort' => <integer>,
            'loadBalancerName' => '<string>',
            'targetGroupArn' => '<string>',
        ],
        // ...
    ],
    'networkConfiguration' => [
        'awsvpcConfiguration' => [
            'assignPublicIp' => 'ENABLED|DISABLED',
            'securityGroups' => ['<string>', ...],
            'subnets' => ['<string>', ...], // REQUIRED
        ],
    ],
    'placementConstraints' => [
        [
            'expression' => '<string>',
            'type' => 'distinctInstance|memberOf',
        ],
        // ...
    ],
    'placementStrategy' => [
        [
            'field' => '<string>',
            'type' => 'random|spread|binpack',
        ],
        // ...
    ],
    'platformVersion' => '<string>',
    'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
    'role' => '<string>',
    'schedulingStrategy' => 'REPLICA|DAEMON',
    'serviceConnectConfiguration' => [
        'enabled' => true || false, // REQUIRED
        'logConfiguration' => [
            'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens', // REQUIRED
            'options' => ['<string>', ...],
            'secretOptions' => [
                [
                    'name' => '<string>', // REQUIRED
                    'valueFrom' => '<string>', // REQUIRED
                ],
                // ...
            ],
        ],
        'namespace' => '<string>',
        'services' => [
            [
                'clientAliases' => [
                    [
                        'dnsName' => '<string>',
                        'port' => <integer>, // REQUIRED
                    ],
                    // ...
                ],
                'discoveryName' => '<string>',
                'ingressPortOverride' => <integer>,
                'portName' => '<string>', // REQUIRED
                'timeout' => [
                    'idleTimeoutSeconds' => <integer>,
                    'perRequestTimeoutSeconds' => <integer>,
                ],
                'tls' => [
                    'issuerCertificateAuthority' => [ // REQUIRED
                        'awsPcaAuthorityArn' => '<string>',
                    ],
                    'kmsKey' => '<string>',
                    'roleArn' => '<string>',
                ],
            ],
            // ...
        ],
    ],
    'serviceName' => '<string>', // REQUIRED
    'serviceRegistries' => [
        [
            'containerName' => '<string>',
            'containerPort' => <integer>,
            'port' => <integer>,
            'registryArn' => '<string>',
        ],
        // ...
    ],
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'taskDefinition' => '<string>',
    'volumeConfigurations' => [
        [
            'managedEBSVolume' => [
                'encrypted' => true || false,
                'filesystemType' => 'ext3|ext4|xfs|ntfs',
                'iops' => <integer>,
                'kmsKeyId' => '<string>',
                'roleArn' => '<string>', // REQUIRED
                'sizeInGiB' => <integer>,
                'snapshotId' => '<string>',
                'tagSpecifications' => [
                    [
                        'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
                        'resourceType' => 'volume', // REQUIRED
                        'tags' => [
                            [
                                'key' => '<string>',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    // ...
                ],
                'throughput' => <integer>,
                'volumeInitializationRate' => <integer>,
                'volumeType' => '<string>',
            ],
            'name' => '<string>', // REQUIRED
        ],
        // ...
    ],
    'vpcLatticeConfigurations' => [
        [
            'portName' => '<string>', // REQUIRED
            'roleArn' => '<string>', // REQUIRED
            'targetGroupArn' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'service' => [
        'availabilityZoneRebalancing' => 'ENABLED|DISABLED',
        'capacityProviderStrategy' => [
            [
                'base' => <integer>,
                'capacityProvider' => '<string>',
                'weight' => <integer>,
            ],
            // ...
        ],
        'clusterArn' => '<string>',
        'createdAt' => <DateTime>,
        'createdBy' => '<string>',
        'deploymentConfiguration' => [
            'alarms' => [
                'alarmNames' => ['<string>', ...],
                'enable' => true || false,
                'rollback' => true || false,
            ],
            'deploymentCircuitBreaker' => [
                'enable' => true || false,
                'rollback' => true || false,
            ],
            'maximumPercent' => <integer>,
            'minimumHealthyPercent' => <integer>,
        ],
        'deploymentController' => [
            'type' => 'ECS|CODE_DEPLOY|EXTERNAL',
        ],
        'deployments' => [
            [
                'capacityProviderStrategy' => [
                    [
                        'base' => <integer>,
                        'capacityProvider' => '<string>',
                        'weight' => <integer>,
                    ],
                    // ...
                ],
                'createdAt' => <DateTime>,
                'desiredCount' => <integer>,
                'failedTasks' => <integer>,
                'fargateEphemeralStorage' => [
                    'kmsKeyId' => '<string>',
                ],
                'id' => '<string>',
                'launchType' => 'EC2|FARGATE|EXTERNAL',
                'networkConfiguration' => [
                    'awsvpcConfiguration' => [
                        'assignPublicIp' => 'ENABLED|DISABLED',
                        'securityGroups' => ['<string>', ...],
                        'subnets' => ['<string>', ...],
                    ],
                ],
                'pendingCount' => <integer>,
                'platformFamily' => '<string>',
                'platformVersion' => '<string>',
                'rolloutState' => 'COMPLETED|FAILED|IN_PROGRESS',
                'rolloutStateReason' => '<string>',
                'runningCount' => <integer>,
                'serviceConnectConfiguration' => [
                    'enabled' => true || false,
                    'logConfiguration' => [
                        'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens',
                        'options' => ['<string>', ...],
                        'secretOptions' => [
                            [
                                'name' => '<string>',
                                'valueFrom' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    'namespace' => '<string>',
                    'services' => [
                        [
                            'clientAliases' => [
                                [
                                    'dnsName' => '<string>',
                                    'port' => <integer>,
                                ],
                                // ...
                            ],
                            'discoveryName' => '<string>',
                            'ingressPortOverride' => <integer>,
                            'portName' => '<string>',
                            'timeout' => [
                                'idleTimeoutSeconds' => <integer>,
                                'perRequestTimeoutSeconds' => <integer>,
                            ],
                            'tls' => [
                                'issuerCertificateAuthority' => [
                                    'awsPcaAuthorityArn' => '<string>',
                                ],
                                'kmsKey' => '<string>',
                                'roleArn' => '<string>',
                            ],
                        ],
                        // ...
                    ],
                ],
                'serviceConnectResources' => [
                    [
                        'discoveryArn' => '<string>',
                        'discoveryName' => '<string>',
                    ],
                    // ...
                ],
                'status' => '<string>',
                'taskDefinition' => '<string>',
                'updatedAt' => <DateTime>,
                'volumeConfigurations' => [
                    [
                        'managedEBSVolume' => [
                            'encrypted' => true || false,
                            'filesystemType' => 'ext3|ext4|xfs|ntfs',
                            'iops' => <integer>,
                            'kmsKeyId' => '<string>',
                            'roleArn' => '<string>',
                            'sizeInGiB' => <integer>,
                            'snapshotId' => '<string>',
                            'tagSpecifications' => [
                                [
                                    'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
                                    'resourceType' => 'volume',
                                    'tags' => [
                                        [
                                            'key' => '<string>',
                                            'value' => '<string>',
                                        ],
                                        // ...
                                    ],
                                ],
                                // ...
                            ],
                            'throughput' => <integer>,
                            'volumeInitializationRate' => <integer>,
                            'volumeType' => '<string>',
                        ],
                        'name' => '<string>',
                    ],
                    // ...
                ],
                'vpcLatticeConfigurations' => [
                    [
                        'portName' => '<string>',
                        'roleArn' => '<string>',
                        'targetGroupArn' => '<string>',
                    ],
                    // ...
                ],
            ],
            // ...
        ],
        'desiredCount' => <integer>,
        'enableECSManagedTags' => true || false,
        'enableExecuteCommand' => true || false,
        'events' => [
            [
                'createdAt' => <DateTime>,
                'id' => '<string>',
                'message' => '<string>',
            ],
            // ...
        ],
        'healthCheckGracePeriodSeconds' => <integer>,
        'launchType' => 'EC2|FARGATE|EXTERNAL',
        'loadBalancers' => [
            [
                'containerName' => '<string>',
                'containerPort' => <integer>,
                'loadBalancerName' => '<string>',
                'targetGroupArn' => '<string>',
            ],
            // ...
        ],
        'networkConfiguration' => [
            'awsvpcConfiguration' => [
                'assignPublicIp' => 'ENABLED|DISABLED',
                'securityGroups' => ['<string>', ...],
                'subnets' => ['<string>', ...],
            ],
        ],
        'pendingCount' => <integer>,
        'placementConstraints' => [
            [
                'expression' => '<string>',
                'type' => 'distinctInstance|memberOf',
            ],
            // ...
        ],
        'placementStrategy' => [
            [
                'field' => '<string>',
                'type' => 'random|spread|binpack',
            ],
            // ...
        ],
        'platformFamily' => '<string>',
        'platformVersion' => '<string>',
        'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
        'roleArn' => '<string>',
        'runningCount' => <integer>,
        'schedulingStrategy' => 'REPLICA|DAEMON',
        'serviceArn' => '<string>',
        'serviceName' => '<string>',
        'serviceRegistries' => [
            [
                'containerName' => '<string>',
                'containerPort' => <integer>,
                'port' => <integer>,
                'registryArn' => '<string>',
            ],
            // ...
        ],
        'status' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'taskDefinition' => '<string>',
        'taskSets' => [
            [
                'capacityProviderStrategy' => [
                    [
                        'base' => <integer>,
                        'capacityProvider' => '<string>',
                        'weight' => <integer>,
                    ],
                    // ...
                ],
                'clusterArn' => '<string>',
                'computedDesiredCount' => <integer>,
                'createdAt' => <DateTime>,
                'externalId' => '<string>',
                'fargateEphemeralStorage' => [
                    'kmsKeyId' => '<string>',
                ],
                'id' => '<string>',
                'launchType' => 'EC2|FARGATE|EXTERNAL',
                'loadBalancers' => [
                    [
                        'containerName' => '<string>',
                        'containerPort' => <integer>,
                        'loadBalancerName' => '<string>',
                        'targetGroupArn' => '<string>',
                    ],
                    // ...
                ],
                'networkConfiguration' => [
                    'awsvpcConfiguration' => [
                        'assignPublicIp' => 'ENABLED|DISABLED',
                        'securityGroups' => ['<string>', ...],
                        'subnets' => ['<string>', ...],
                    ],
                ],
                'pendingCount' => <integer>,
                'platformFamily' => '<string>',
                'platformVersion' => '<string>',
                'runningCount' => <integer>,
                'scale' => [
                    'unit' => 'PERCENT',
                    'value' => <float>,
                ],
                'serviceArn' => '<string>',
                'serviceRegistries' => [
                    [
                        'containerName' => '<string>',
                        'containerPort' => <integer>,
                        'port' => <integer>,
                        'registryArn' => '<string>',
                    ],
                    // ...
                ],
                'stabilityStatus' => 'STEADY_STATE|STABILIZING',
                'stabilityStatusAt' => <DateTime>,
                'startedBy' => '<string>',
                'status' => '<string>',
                'tags' => [
                    [
                        'key' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'taskDefinition' => '<string>',
                'taskSetArn' => '<string>',
                'updatedAt' => <DateTime>,
            ],
            // ...
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

PlatformUnknownException:

The specified platform version doesn't exist.

PlatformTaskDefinitionIncompatibilityException:

The specified platform version doesn't satisfy the required capabilities of the task definition.

AccessDeniedException:

You don't have authorization to perform the requested action.

NamespaceNotFoundException:

The specified namespace wasn't found.

Examples

Example 1: To create a new service

This example creates a service in your default region called ``ecs-simple-service``. The service uses the ``hello_world`` task definition and it maintains 10 copies of that task.

$result = $client->createService([
    'desiredCount' => 10,
    'serviceName' => 'ecs-simple-service',
    'taskDefinition' => 'hello_world',
]);

Result syntax:

[
    'service' => [
        'clusterArn' => 'arn:aws:ecs:us-east-1:012345678910:cluster/default',
        'createdAt' => ,
        'deploymentConfiguration' => [
            'maximumPercent' => 200,
            'minimumHealthyPercent' => 100,
        ],
        'deployments' => [
            [
                'createdAt' => ,
                'desiredCount' => 10,
                'id' => 'ecs-svc/9223370564342348388',
                'pendingCount' => 0,
                'runningCount' => 0,
                'status' => 'PRIMARY',
                'taskDefinition' => 'arn:aws:ecs:us-east-1:012345678910:task-definition/hello_world:6',
                'updatedAt' => ,
            ],
            [
                'createdAt' => ,
                'desiredCount' => 0,
                'id' => 'ecs-svc/9223370564343611322',
                'pendingCount' => 0,
                'runningCount' => 0,
                'status' => 'ACTIVE',
                'taskDefinition' => 'arn:aws:ecs:us-east-1:012345678910:task-definition/hello_world:6',
                'updatedAt' => ,
            ],
        ],
        'desiredCount' => 10,
        'events' => [
        ],
        'loadBalancers' => [
        ],
        'pendingCount' => 0,
        'runningCount' => 0,
        'serviceArn' => 'arn:aws:ecs:us-east-1:012345678910:service/default/ecs-simple-service',
        'serviceName' => 'ecs-simple-service',
        'status' => 'ACTIVE',
        'taskDefinition' => 'arn:aws:ecs:us-east-1:012345678910:task-definition/default/hello_world:6',
    ],
]

Example 2: To create a new service behind a load balancer

This example creates a service in your default region called ``ecs-simple-service-elb``. The service uses the ``ecs-demo`` task definition and it maintains 10 copies of that task. You must reference an existing load balancer in the same region by its name.

$result = $client->createService([
    'desiredCount' => 10,
    'loadBalancers' => [
        [
            'containerName' => 'simple-app',
            'containerPort' => 80,
            'loadBalancerName' => 'EC2Contai-EcsElast-15DCDAURT3ZO2',
        ],
    ],
    'role' => 'ecsServiceRole',
    'serviceName' => 'ecs-simple-service-elb',
    'taskDefinition' => 'console-sample-app-static',
]);

Result syntax:

[
    'service' => [
        'clusterArn' => 'arn:aws:ecs:us-east-1:012345678910:cluster/default',
        'createdAt' => ,
        'deploymentConfiguration' => [
            'maximumPercent' => 200,
            'minimumHealthyPercent' => 100,
        ],
        'deployments' => [
            [
                'createdAt' => ,
                'desiredCount' => 10,
                'id' => 'ecs-svc/9223370564343000923',
                'pendingCount' => 0,
                'runningCount' => 0,
                'status' => 'PRIMARY',
                'taskDefinition' => 'arn:aws:ecs:us-east-1:012345678910:task-definition/console-sample-app-static:6',
                'updatedAt' => ,
            ],
        ],
        'desiredCount' => 10,
        'events' => [
        ],
        'loadBalancers' => [
            [
                'containerName' => 'simple-app',
                'containerPort' => 80,
                'loadBalancerName' => 'EC2Contai-EcsElast-15DCDAURT3ZO2',
            ],
        ],
        'pendingCount' => 0,
        'roleArn' => 'arn:aws:iam::012345678910:role/ecsServiceRole',
        'runningCount' => 0,
        'serviceArn' => 'arn:aws:ecs:us-east-1:012345678910:service/default/ecs-simple-service-elb',
        'serviceName' => 'ecs-simple-service-elb',
        'status' => 'ACTIVE',
        'taskDefinition' => 'arn:aws:ecs:us-east-1:012345678910:task-definition/default/console-sample-app-static:6',
    ],
]

CreateTaskSet

$result = $client->createTaskSet([/* ... */]);
$promise = $client->createTaskSetAsync([/* ... */]);

Create a task set in the specified cluster and service. This is used when a service uses the EXTERNAL deployment controller type. For more information, see Amazon ECS deployment types in the Amazon Elastic Container Service Developer Guide.

For information about the maximum number of task sets and other quotas, see Amazon ECS service quotas in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->createTaskSet([
    'capacityProviderStrategy' => [
        [
            'base' => <integer>,
            'capacityProvider' => '<string>', // REQUIRED
            'weight' => <integer>,
        ],
        // ...
    ],
    'clientToken' => '<string>',
    'cluster' => '<string>', // REQUIRED
    'externalId' => '<string>',
    'launchType' => 'EC2|FARGATE|EXTERNAL',
    'loadBalancers' => [
        [
            'containerName' => '<string>',
            'containerPort' => <integer>,
            'loadBalancerName' => '<string>',
            'targetGroupArn' => '<string>',
        ],
        // ...
    ],
    'networkConfiguration' => [
        'awsvpcConfiguration' => [
            'assignPublicIp' => 'ENABLED|DISABLED',
            'securityGroups' => ['<string>', ...],
            'subnets' => ['<string>', ...], // REQUIRED
        ],
    ],
    'platformVersion' => '<string>',
    'scale' => [
        'unit' => 'PERCENT',
        'value' => <float>,
    ],
    'service' => '<string>', // REQUIRED
    'serviceRegistries' => [
        [
            'containerName' => '<string>',
            'containerPort' => <integer>,
            'port' => <integer>,
            'registryArn' => '<string>',
        ],
        // ...
    ],
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'taskDefinition' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'taskSet' => [
        'capacityProviderStrategy' => [
            [
                'base' => <integer>,
                'capacityProvider' => '<string>',
                'weight' => <integer>,
            ],
            // ...
        ],
        'clusterArn' => '<string>',
        'computedDesiredCount' => <integer>,
        'createdAt' => <DateTime>,
        'externalId' => '<string>',
        'fargateEphemeralStorage' => [
            'kmsKeyId' => '<string>',
        ],
        'id' => '<string>',
        'launchType' => 'EC2|FARGATE|EXTERNAL',
        'loadBalancers' => [
            [
                'containerName' => '<string>',
                'containerPort' => <integer>,
                'loadBalancerName' => '<string>',
                'targetGroupArn' => '<string>',
            ],
            // ...
        ],
        'networkConfiguration' => [
            'awsvpcConfiguration' => [
                'assignPublicIp' => 'ENABLED|DISABLED',
                'securityGroups' => ['<string>', ...],
                'subnets' => ['<string>', ...],
            ],
        ],
        'pendingCount' => <integer>,
        'platformFamily' => '<string>',
        'platformVersion' => '<string>',
        'runningCount' => <integer>,
        'scale' => [
            'unit' => 'PERCENT',
            'value' => <float>,
        ],
        'serviceArn' => '<string>',
        'serviceRegistries' => [
            [
                'containerName' => '<string>',
                'containerPort' => <integer>,
                'port' => <integer>,
                'registryArn' => '<string>',
            ],
            // ...
        ],
        'stabilityStatus' => 'STEADY_STATE|STABILIZING',
        'stabilityStatusAt' => <DateTime>,
        'startedBy' => '<string>',
        'status' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'taskDefinition' => '<string>',
        'taskSetArn' => '<string>',
        'updatedAt' => <DateTime>,
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

PlatformUnknownException:

The specified platform version doesn't exist.

PlatformTaskDefinitionIncompatibilityException:

The specified platform version doesn't satisfy the required capabilities of the task definition.

AccessDeniedException:

You don't have authorization to perform the requested action.

ServiceNotFoundException:

The specified service wasn't found. You can view your available services with ListServices. Amazon ECS services are cluster specific and Region specific.

ServiceNotActiveException:

The specified service isn't active. You can't update a service that's inactive. If you have previously deleted a service, you can re-create it with CreateService.

NamespaceNotFoundException:

The specified namespace wasn't found.

Examples

Example 1: To create a task set

This example creates a task set in a service that uses the EXTERNAL deployment controller.

$result = $client->createTaskSet([
    'cluster' => 'MyCluster',
    'networkConfiguration' => [
        'awsvpcConfiguration' => [
            'securityGroups' => [
                'sg-12344321',
            ],
            'subnets' => [
                'subnet-12344321',
            ],
        ],
    ],
    'service' => 'MyService',
    'taskDefinition' => 'MyTaskDefinition:2',
]);

Result syntax:

[
    'taskSet' => [
        'computedDesiredCount' => 0,
        'createdAt' => ,
        'id' => 'ecs-svc/1234567890123456789',
        'launchType' => 'EC2',
        'loadBalancers' => [
        ],
        'networkConfiguration' => [
            'awsvpcConfiguration' => [
                'assignPublicIp' => 'DISABLED',
                'securityGroups' => [
                    'sg-12344321',
                ],
                'subnets' => [
                    'subnet-12344321',
                ],
            ],
        ],
        'pendingCount' => 0,
        'runningCount' => 0,
        'scale' => [
            'value' => 0,
            'unit' => 'PERCENT',
        ],
        'serviceRegistries' => [
        ],
        'stabilityStatus' => 'STABILIZING',
        'stabilityStatusAt' => ,
        'status' => 'ACTIVE',
        'taskDefinition' => 'arn:aws:ecs:us-west-2:123456789012:task-definition/MyTaskDefinition:2',
        'taskSetArn' => 'arn:aws:ecs:us-west-2:123456789012:task-set/MyCluster/MyService/ecs-svc/1234567890123456789',
        'updatedAt' => ,
    ],
]

DeleteAccountSetting

$result = $client->deleteAccountSetting([/* ... */]);
$promise = $client->deleteAccountSettingAsync([/* ... */]);

Disables an account setting for a specified user, role, or the root user for an account.

Parameter Syntax

$result = $client->deleteAccountSetting([
    'name' => 'serviceLongArnFormat|taskLongArnFormat|containerInstanceLongArnFormat|awsvpcTrunking|containerInsights|fargateFIPSMode|tagResourceAuthorization|fargateTaskRetirementWaitPeriod|guardDutyActivate|defaultLogDriverMode', // REQUIRED
    'principalArn' => '<string>',
]);

Parameter Details

Result Syntax

[
    'setting' => [
        'name' => 'serviceLongArnFormat|taskLongArnFormat|containerInstanceLongArnFormat|awsvpcTrunking|containerInsights|fargateFIPSMode|tagResourceAuthorization|fargateTaskRetirementWaitPeriod|guardDutyActivate|defaultLogDriverMode',
        'principalArn' => '<string>',
        'type' => 'user|aws_managed',
        'value' => '<string>',
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To delete your account setting

This example deletes the account setting for your user for the specified resource type.

$result = $client->deleteAccountSetting([
    'name' => 'serviceLongArnFormat',
]);

Result syntax:

[
    'setting' => [
        'name' => 'serviceLongArnFormat',
        'value' => 'enabled',
        'principalArn' => 'arn:aws:iam:::user/principalName',
    ],
]

Example 2: To delete the account settings for a specific IAM user or IAM role

This example deletes the account setting for a specific IAM user or IAM role for the specified resource type. Only the root user can view or modify the account settings for another user.

$result = $client->deleteAccountSetting([
    'name' => 'containerInstanceLongArnFormat',
    'principalArn' => 'arn:aws:iam:::user/principalName',
]);

Result syntax:

[
    'setting' => [
        'name' => 'containerInstanceLongArnFormat',
        'value' => 'enabled',
        'principalArn' => 'arn:aws:iam:::user/principalName',
    ],
]

DeleteAttributes

$result = $client->deleteAttributes([/* ... */]);
$promise = $client->deleteAttributesAsync([/* ... */]);

Deletes one or more custom attributes from an Amazon ECS resource.

Parameter Syntax

$result = $client->deleteAttributes([
    'attributes' => [ // REQUIRED
        [
            'name' => '<string>', // REQUIRED
            'targetId' => '<string>',
            'targetType' => 'container-instance',
            'value' => '<string>',
        ],
        // ...
    ],
    'cluster' => '<string>',
]);

Parameter Details

Result Syntax

[
    'attributes' => [
        [
            'name' => '<string>',
            'targetId' => '<string>',
            'targetType' => 'container-instance',
            'value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

TargetNotFoundException:

The specified target wasn't found. You can view your available container instances with ListContainerInstances. Amazon ECS container instances are cluster-specific and Region-specific.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To delete a custom attribute from an Amazon ECS instance

This example deletes an attribute named stack from a container instance.

$result = $client->deleteAttributes([
    'attributes' => [
        [
            'name' => 'stack',
            'targetId' => 'aws:ecs:us-west-2:130757420319:container-instance/1c3be8ed-df30-47b4-8f1e-6e68ebd01f34',
        ],
    ],
]);

Result syntax:

[
    'attributes' => [
        [
            'name' => 'stack',
            'value' => 'production',
            'targetId' => 'aws:ecs:us-west-2:130757420319:container-instance/1c3be8ed-df30-47b4-8f1e-6e68ebd01f34',
        ],
    ],
]

DeleteCapacityProvider

$result = $client->deleteCapacityProvider([/* ... */]);
$promise = $client->deleteCapacityProviderAsync([/* ... */]);

Deletes the specified capacity provider.

Prior to a capacity provider being deleted, the capacity provider must be removed from the capacity provider strategy from all services. The UpdateService API can be used to remove a capacity provider from a service's capacity provider strategy. When updating a service, the forceNewDeployment option can be used to ensure that any tasks using the Amazon EC2 instance capacity provided by the capacity provider are transitioned to use the capacity from the remaining capacity providers. Only capacity providers that aren't associated with a cluster can be deleted. To remove a capacity provider from a cluster, you can either use PutClusterCapacityProviders or delete the cluster.

Parameter Syntax

$result = $client->deleteCapacityProvider([
    'capacityProvider' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'capacityProvider' => [
        'autoScalingGroupProvider' => [
            'autoScalingGroupArn' => '<string>',
            'managedDraining' => 'ENABLED|DISABLED',
            'managedScaling' => [
                'instanceWarmupPeriod' => <integer>,
                'maximumScalingStepSize' => <integer>,
                'minimumScalingStepSize' => <integer>,
                'status' => 'ENABLED|DISABLED',
                'targetCapacity' => <integer>,
            ],
            'managedTerminationProtection' => 'ENABLED|DISABLED',
        ],
        'capacityProviderArn' => '<string>',
        'name' => '<string>',
        'status' => 'ACTIVE|INACTIVE',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'updateStatus' => 'DELETE_IN_PROGRESS|DELETE_COMPLETE|DELETE_FAILED|UPDATE_IN_PROGRESS|UPDATE_COMPLETE|UPDATE_FAILED',
        'updateStatusReason' => '<string>',
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To delete a specified capacity provider

This example deletes a specified capacity provider.

$result = $client->deleteCapacityProvider([
    'capacityProvider' => 'arn:aws:ecs:us-west-2:123456789012:capacity-provider/ExampleCapacityProvider',
]);

Result syntax:

[
    'capacityProvider' => [
        'name' => 'ExampleCapacityProvider',
        'autoScalingGroupProvider' => [
            'autoScalingGroupArn' => 'arn:aws:autoscaling:us-west-2:123456789012:autoScalingGroup:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111:autoScalingGroupName/MyAutoScalingGroup',
            'managedScaling' => [
                'maximumScalingStepSize' => 10000,
                'minimumScalingStepSize' => 1,
                'status' => 'ENABLED',
                'targetCapacity' => 100,
            ],
            'managedTerminationProtection' => 'DISABLED',
        ],
        'capacityProviderArn' => 'arn:aws:ecs:us-west-2:123456789012:capacity-provider/ExampleCapacityProvider',
        'status' => 'ACTIVE',
        'tags' => [
        ],
        'updateStatus' => 'DELETE_IN_PROGRESS',
    ],
]

DeleteCluster

$result = $client->deleteCluster([/* ... */]);
$promise = $client->deleteClusterAsync([/* ... */]);

Deletes the specified cluster. The cluster transitions to the INACTIVE state. Clusters with an INACTIVE status might remain discoverable in your account for a period of time. However, this behavior is subject to change in the future. We don't recommend that you rely on INACTIVE clusters persisting.

You must deregister all container instances from this cluster before you may delete it. You can list the container instances in a cluster with ListContainerInstances and deregister them with DeregisterContainerInstance.

Parameter Syntax

$result = $client->deleteCluster([
    'cluster' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'cluster' => [
        'activeServicesCount' => <integer>,
        'attachments' => [
            [
                'details' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'id' => '<string>',
                'status' => '<string>',
                'type' => '<string>',
            ],
            // ...
        ],
        'attachmentsStatus' => '<string>',
        'capacityProviders' => ['<string>', ...],
        'clusterArn' => '<string>',
        'clusterName' => '<string>',
        'configuration' => [
            'executeCommandConfiguration' => [
                'kmsKeyId' => '<string>',
                'logConfiguration' => [
                    'cloudWatchEncryptionEnabled' => true || false,
                    'cloudWatchLogGroupName' => '<string>',
                    's3BucketName' => '<string>',
                    's3EncryptionEnabled' => true || false,
                    's3KeyPrefix' => '<string>',
                ],
                'logging' => 'NONE|DEFAULT|OVERRIDE',
            ],
            'managedStorageConfiguration' => [
                'fargateEphemeralStorageKmsKeyId' => '<string>',
                'kmsKeyId' => '<string>',
            ],
        ],
        'defaultCapacityProviderStrategy' => [
            [
                'base' => <integer>,
                'capacityProvider' => '<string>',
                'weight' => <integer>,
            ],
            // ...
        ],
        'pendingTasksCount' => <integer>,
        'registeredContainerInstancesCount' => <integer>,
        'runningTasksCount' => <integer>,
        'serviceConnectDefaults' => [
            'namespace' => '<string>',
        ],
        'settings' => [
            [
                'name' => 'containerInsights',
                'value' => '<string>',
            ],
            // ...
        ],
        'statistics' => [
            [
                'name' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'status' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

ClusterContainsContainerInstancesException:

You can't delete a cluster that has registered container instances. First, deregister the container instances before you can delete the cluster. For more information, see DeregisterContainerInstance.

ClusterContainsServicesException:

You can't delete a cluster that contains services. First, update the service to reduce its desired task count to 0, and then delete the service. For more information, see UpdateService and DeleteService.

ClusterContainsTasksException:

You can't delete a cluster that has active tasks.

UpdateInProgressException:

There's already a current Amazon ECS container agent update in progress on the container instance that's specified. If the container agent becomes disconnected while it's in a transitional stage, such as PENDING or STAGING, the update process can get stuck in that state. However, when the agent reconnects, it resumes where it stopped previously.

Examples

Example 1: To delete an empty cluster

This example deletes an empty cluster in your default region.

$result = $client->deleteCluster([
    'cluster' => 'my_cluster',
]);

Result syntax:

[
    'cluster' => [
        'activeServicesCount' => 0,
        'clusterArn' => 'arn:aws:ecs:us-east-1:012345678910:cluster/my_cluster',
        'clusterName' => 'my_cluster',
        'pendingTasksCount' => 0,
        'registeredContainerInstancesCount' => 0,
        'runningTasksCount' => 0,
        'status' => 'INACTIVE',
    ],
]

DeleteService

$result = $client->deleteService([/* ... */]);
$promise = $client->deleteServiceAsync([/* ... */]);

Deletes a specified service within a cluster. You can delete a service if you have no running tasks in it and the desired task count is zero. If the service is actively maintaining tasks, you can't delete it, and you must update the service to a desired task count of zero. For more information, see UpdateService.

Parameter Syntax

$result = $client->deleteService([
    'cluster' => '<string>',
    'force' => true || false,
    'service' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'service' => [
        'availabilityZoneRebalancing' => 'ENABLED|DISABLED',
        'capacityProviderStrategy' => [
            [
                'base' => <integer>,
                'capacityProvider' => '<string>',
                'weight' => <integer>,
            ],
            // ...
        ],
        'clusterArn' => '<string>',
        'createdAt' => <DateTime>,
        'createdBy' => '<string>',
        'deploymentConfiguration' => [
            'alarms' => [
                'alarmNames' => ['<string>', ...],
                'enable' => true || false,
                'rollback' => true || false,
            ],
            'deploymentCircuitBreaker' => [
                'enable' => true || false,
                'rollback' => true || false,
            ],
            'maximumPercent' => <integer>,
            'minimumHealthyPercent' => <integer>,
        ],
        'deploymentController' => [
            'type' => 'ECS|CODE_DEPLOY|EXTERNAL',
        ],
        'deployments' => [
            [
                'capacityProviderStrategy' => [
                    [
                        'base' => <integer>,
                        'capacityProvider' => '<string>',
                        'weight' => <integer>,
                    ],
                    // ...
                ],
                'createdAt' => <DateTime>,
                'desiredCount' => <integer>,
                'failedTasks' => <integer>,
                'fargateEphemeralStorage' => [
                    'kmsKeyId' => '<string>',
                ],
                'id' => '<string>',
                'launchType' => 'EC2|FARGATE|EXTERNAL',
                'networkConfiguration' => [
                    'awsvpcConfiguration' => [
                        'assignPublicIp' => 'ENABLED|DISABLED',
                        'securityGroups' => ['<string>', ...],
                        'subnets' => ['<string>', ...],
                    ],
                ],
                'pendingCount' => <integer>,
                'platformFamily' => '<string>',
                'platformVersion' => '<string>',
                'rolloutState' => 'COMPLETED|FAILED|IN_PROGRESS',
                'rolloutStateReason' => '<string>',
                'runningCount' => <integer>,
                'serviceConnectConfiguration' => [
                    'enabled' => true || false,
                    'logConfiguration' => [
                        'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens',
                        'options' => ['<string>', ...],
                        'secretOptions' => [
                            [
                                'name' => '<string>',
                                'valueFrom' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    'namespace' => '<string>',
                    'services' => [
                        [
                            'clientAliases' => [
                                [
                                    'dnsName' => '<string>',
                                    'port' => <integer>,
                                ],
                                // ...
                            ],
                            'discoveryName' => '<string>',
                            'ingressPortOverride' => <integer>,
                            'portName' => '<string>',
                            'timeout' => [
                                'idleTimeoutSeconds' => <integer>,
                                'perRequestTimeoutSeconds' => <integer>,
                            ],
                            'tls' => [
                                'issuerCertificateAuthority' => [
                                    'awsPcaAuthorityArn' => '<string>',
                                ],
                                'kmsKey' => '<string>',
                                'roleArn' => '<string>',
                            ],
                        ],
                        // ...
                    ],
                ],
                'serviceConnectResources' => [
                    [
                        'discoveryArn' => '<string>',
                        'discoveryName' => '<string>',
                    ],
                    // ...
                ],
                'status' => '<string>',
                'taskDefinition' => '<string>',
                'updatedAt' => <DateTime>,
                'volumeConfigurations' => [
                    [
                        'managedEBSVolume' => [
                            'encrypted' => true || false,
                            'filesystemType' => 'ext3|ext4|xfs|ntfs',
                            'iops' => <integer>,
                            'kmsKeyId' => '<string>',
                            'roleArn' => '<string>',
                            'sizeInGiB' => <integer>,
                            'snapshotId' => '<string>',
                            'tagSpecifications' => [
                                [
                                    'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
                                    'resourceType' => 'volume',
                                    'tags' => [
                                        [
                                            'key' => '<string>',
                                            'value' => '<string>',
                                        ],
                                        // ...
                                    ],
                                ],
                                // ...
                            ],
                            'throughput' => <integer>,
                            'volumeInitializationRate' => <integer>,
                            'volumeType' => '<string>',
                        ],
                        'name' => '<string>',
                    ],
                    // ...
                ],
                'vpcLatticeConfigurations' => [
                    [
                        'portName' => '<string>',
                        'roleArn' => '<string>',
                        'targetGroupArn' => '<string>',
                    ],
                    // ...
                ],
            ],
            // ...
        ],
        'desiredCount' => <integer>,
        'enableECSManagedTags' => true || false,
        'enableExecuteCommand' => true || false,
        'events' => [
            [
                'createdAt' => <DateTime>,
                'id' => '<string>',
                'message' => '<string>',
            ],
            // ...
        ],
        'healthCheckGracePeriodSeconds' => <integer>,
        'launchType' => 'EC2|FARGATE|EXTERNAL',
        'loadBalancers' => [
            [
                'containerName' => '<string>',
                'containerPort' => <integer>,
                'loadBalancerName' => '<string>',
                'targetGroupArn' => '<string>',
            ],
            // ...
        ],
        'networkConfiguration' => [
            'awsvpcConfiguration' => [
                'assignPublicIp' => 'ENABLED|DISABLED',
                'securityGroups' => ['<string>', ...],
                'subnets' => ['<string>', ...],
            ],
        ],
        'pendingCount' => <integer>,
        'placementConstraints' => [
            [
                'expression' => '<string>',
                'type' => 'distinctInstance|memberOf',
            ],
            // ...
        ],
        'placementStrategy' => [
            [
                'field' => '<string>',
                'type' => 'random|spread|binpack',
            ],
            // ...
        ],
        'platformFamily' => '<string>',
        'platformVersion' => '<string>',
        'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
        'roleArn' => '<string>',
        'runningCount' => <integer>,
        'schedulingStrategy' => 'REPLICA|DAEMON',
        'serviceArn' => '<string>',
        'serviceName' => '<string>',
        'serviceRegistries' => [
            [
                'containerName' => '<string>',
                'containerPort' => <integer>,
                'port' => <integer>,
                'registryArn' => '<string>',
            ],
            // ...
        ],
        'status' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'taskDefinition' => '<string>',
        'taskSets' => [
            [
                'capacityProviderStrategy' => [
                    [
                        'base' => <integer>,
                        'capacityProvider' => '<string>',
                        'weight' => <integer>,
                    ],
                    // ...
                ],
                'clusterArn' => '<string>',
                'computedDesiredCount' => <integer>,
                'createdAt' => <DateTime>,
                'externalId' => '<string>',
                'fargateEphemeralStorage' => [
                    'kmsKeyId' => '<string>',
                ],
                'id' => '<string>',
                'launchType' => 'EC2|FARGATE|EXTERNAL',
                'loadBalancers' => [
                    [
                        'containerName' => '<string>',
                        'containerPort' => <integer>,
                        'loadBalancerName' => '<string>',
                        'targetGroupArn' => '<string>',
                    ],
                    // ...
                ],
                'networkConfiguration' => [
                    'awsvpcConfiguration' => [
                        'assignPublicIp' => 'ENABLED|DISABLED',
                        'securityGroups' => ['<string>', ...],
                        'subnets' => ['<string>', ...],
                    ],
                ],
                'pendingCount' => <integer>,
                'platformFamily' => '<string>',
                'platformVersion' => '<string>',
                'runningCount' => <integer>,
                'scale' => [
                    'unit' => 'PERCENT',
                    'value' => <float>,
                ],
                'serviceArn' => '<string>',
                'serviceRegistries' => [
                    [
                        'containerName' => '<string>',
                        'containerPort' => <integer>,
                        'port' => <integer>,
                        'registryArn' => '<string>',
                    ],
                    // ...
                ],
                'stabilityStatus' => 'STEADY_STATE|STABILIZING',
                'stabilityStatusAt' => <DateTime>,
                'startedBy' => '<string>',
                'status' => '<string>',
                'tags' => [
                    [
                        'key' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'taskDefinition' => '<string>',
                'taskSetArn' => '<string>',
                'updatedAt' => <DateTime>,
            ],
            // ...
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

ServiceNotFoundException:

The specified service wasn't found. You can view your available services with ListServices. Amazon ECS services are cluster specific and Region specific.

Examples

Example 1: To delete a service

This example deletes the my-http-service service. The service must have a desired count and running count of 0 before you can delete it.

$result = $client->deleteService([
    'service' => 'my-http-service',
]);

Result syntax:

[
]

DeleteTaskDefinitions

$result = $client->deleteTaskDefinitions([/* ... */]);
$promise = $client->deleteTaskDefinitionsAsync([/* ... */]);

Deletes one or more task definitions.

You must deregister a task definition revision before you delete it. For more information, see DeregisterTaskDefinition.

When you delete a task definition revision, it is immediately transitions from the INACTIVE to DELETE_IN_PROGRESS. Existing tasks and services that reference a DELETE_IN_PROGRESS task definition revision continue to run without disruption. Existing services that reference a DELETE_IN_PROGRESS task definition revision can still scale up or down by modifying the service's desired count.

You can't use a DELETE_IN_PROGRESS task definition revision to run new tasks or create new services. You also can't update an existing service to reference a DELETE_IN_PROGRESS task definition revision.

A task definition revision will stay in DELETE_IN_PROGRESS status until all the associated tasks and services have been terminated.

When you delete all INACTIVE task definition revisions, the task definition name is not displayed in the console and not returned in the API. If a task definition revisions are in the DELETE_IN_PROGRESS state, the task definition name is displayed in the console and returned in the API. The task definition name is retained by Amazon ECS and the revision is incremented the next time you create a task definition with that name.

Parameter Syntax

$result = $client->deleteTaskDefinitions([
    'taskDefinitions' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Result Syntax

[
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'taskDefinitions' => [
        [
            'compatibilities' => ['<string>', ...],
            'containerDefinitions' => [
                [
                    'command' => ['<string>', ...],
                    'cpu' => <integer>,
                    'credentialSpecs' => ['<string>', ...],
                    'dependsOn' => [
                        [
                            'condition' => 'START|COMPLETE|SUCCESS|HEALTHY',
                            'containerName' => '<string>',
                        ],
                        // ...
                    ],
                    'disableNetworking' => true || false,
                    'dnsSearchDomains' => ['<string>', ...],
                    'dnsServers' => ['<string>', ...],
                    'dockerLabels' => ['<string>', ...],
                    'dockerSecurityOptions' => ['<string>', ...],
                    'entryPoint' => ['<string>', ...],
                    'environment' => [
                        [
                            'name' => '<string>',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'environmentFiles' => [
                        [
                            'type' => 's3',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'essential' => true || false,
                    'extraHosts' => [
                        [
                            'hostname' => '<string>',
                            'ipAddress' => '<string>',
                        ],
                        // ...
                    ],
                    'firelensConfiguration' => [
                        'options' => ['<string>', ...],
                        'type' => 'fluentd|fluentbit',
                    ],
                    'healthCheck' => [
                        'command' => ['<string>', ...],
                        'interval' => <integer>,
                        'retries' => <integer>,
                        'startPeriod' => <integer>,
                        'timeout' => <integer>,
                    ],
                    'hostname' => '<string>',
                    'image' => '<string>',
                    'interactive' => true || false,
                    'links' => ['<string>', ...],
                    'linuxParameters' => [
                        'capabilities' => [
                            'add' => ['<string>', ...],
                            'drop' => ['<string>', ...],
                        ],
                        'devices' => [
                            [
                                'containerPath' => '<string>',
                                'hostPath' => '<string>',
                                'permissions' => ['<string>', ...],
                            ],
                            // ...
                        ],
                        'initProcessEnabled' => true || false,
                        'maxSwap' => <integer>,
                        'sharedMemorySize' => <integer>,
                        'swappiness' => <integer>,
                        'tmpfs' => [
                            [
                                'containerPath' => '<string>',
                                'mountOptions' => ['<string>', ...],
                                'size' => <integer>,
                            ],
                            // ...
                        ],
                    ],
                    'logConfiguration' => [
                        'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens',
                        'options' => ['<string>', ...],
                        'secretOptions' => [
                            [
                                'name' => '<string>',
                                'valueFrom' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    'memory' => <integer>,
                    'memoryReservation' => <integer>,
                    'mountPoints' => [
                        [
                            'containerPath' => '<string>',
                            'readOnly' => true || false,
                            'sourceVolume' => '<string>',
                        ],
                        // ...
                    ],
                    'name' => '<string>',
                    'portMappings' => [
                        [
                            'appProtocol' => 'http|http2|grpc',
                            'containerPort' => <integer>,
                            'containerPortRange' => '<string>',
                            'hostPort' => <integer>,
                            'name' => '<string>',
                            'protocol' => 'tcp|udp',
                        ],
                        // ...
                    ],
                    'privileged' => true || false,
                    'pseudoTerminal' => true || false,
                    'readonlyRootFilesystem' => true || false,
                    'repositoryCredentials' => [
                        'credentialsParameter' => '<string>',
                    ],
                    'resourceRequirements' => [
                        [
                            'type' => 'GPU|InferenceAccelerator',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'restartPolicy' => [
                        'enabled' => true || false,
                        'ignoredExitCodes' => [<integer>, ...],
                        'restartAttemptPeriod' => <integer>,
                    ],
                    'secrets' => [
                        [
                            'name' => '<string>',
                            'valueFrom' => '<string>',
                        ],
                        // ...
                    ],
                    'startTimeout' => <integer>,
                    'stopTimeout' => <integer>,
                    'systemControls' => [
                        [
                            'namespace' => '<string>',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'ulimits' => [
                        [
                            'hardLimit' => <integer>,
                            'name' => 'core|cpu|data|fsize|locks|memlock|msgqueue|nice|nofile|nproc|rss|rtprio|rttime|sigpending|stack',
                            'softLimit' => <integer>,
                        ],
                        // ...
                    ],
                    'user' => '<string>',
                    'versionConsistency' => 'enabled|disabled',
                    'volumesFrom' => [
                        [
                            'readOnly' => true || false,
                            'sourceContainer' => '<string>',
                        ],
                        // ...
                    ],
                    'workingDirectory' => '<string>',
                ],
                // ...
            ],
            'cpu' => '<string>',
            'deregisteredAt' => <DateTime>,
            'enableFaultInjection' => true || false,
            'ephemeralStorage' => [
                'sizeInGiB' => <integer>,
            ],
            'executionRoleArn' => '<string>',
            'family' => '<string>',
            'inferenceAccelerators' => [
                [
                    'deviceName' => '<string>',
                    'deviceType' => '<string>',
                ],
                // ...
            ],
            'ipcMode' => 'host|task|none',
            'memory' => '<string>',
            'networkMode' => 'bridge|host|awsvpc|none',
            'pidMode' => 'host|task',
            'placementConstraints' => [
                [
                    'expression' => '<string>',
                    'type' => 'memberOf',
                ],
                // ...
            ],
            'proxyConfiguration' => [
                'containerName' => '<string>',
                'properties' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'type' => 'APPMESH',
            ],
            'registeredAt' => <DateTime>,
            'registeredBy' => '<string>',
            'requiresAttributes' => [
                [
                    'name' => '<string>',
                    'targetId' => '<string>',
                    'targetType' => 'container-instance',
                    'value' => '<string>',
                ],
                // ...
            ],
            'requiresCompatibilities' => ['<string>', ...],
            'revision' => <integer>,
            'runtimePlatform' => [
                'cpuArchitecture' => 'X86_64|ARM64',
                'operatingSystemFamily' => 'WINDOWS_SERVER_2019_FULL|WINDOWS_SERVER_2019_CORE|WINDOWS_SERVER_2016_FULL|WINDOWS_SERVER_2004_CORE|WINDOWS_SERVER_2022_CORE|WINDOWS_SERVER_2022_FULL|WINDOWS_SERVER_2025_CORE|WINDOWS_SERVER_2025_FULL|WINDOWS_SERVER_20H2_CORE|LINUX',
            ],
            'status' => 'ACTIVE|INACTIVE|DELETE_IN_PROGRESS',
            'taskDefinitionArn' => '<string>',
            'taskRoleArn' => '<string>',
            'volumes' => [
                [
                    'configuredAtLaunch' => true || false,
                    'dockerVolumeConfiguration' => [
                        'autoprovision' => true || false,
                        'driver' => '<string>',
                        'driverOpts' => ['<string>', ...],
                        'labels' => ['<string>', ...],
                        'scope' => 'task|shared',
                    ],
                    'efsVolumeConfiguration' => [
                        'authorizationConfig' => [
                            'accessPointId' => '<string>',
                            'iam' => 'ENABLED|DISABLED',
                        ],
                        'fileSystemId' => '<string>',
                        'rootDirectory' => '<string>',
                        'transitEncryption' => 'ENABLED|DISABLED',
                        'transitEncryptionPort' => <integer>,
                    ],
                    'fsxWindowsFileServerVolumeConfiguration' => [
                        'authorizationConfig' => [
                            'credentialsParameter' => '<string>',
                            'domain' => '<string>',
                        ],
                        'fileSystemId' => '<string>',
                        'rootDirectory' => '<string>',
                    ],
                    'host' => [
                        'sourcePath' => '<string>',
                    ],
                    'name' => '<string>',
                ],
                // ...
            ],
        ],
        // ...
    ],
]

Result Details

Errors

AccessDeniedException:

You don't have authorization to perform the requested action.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ServerException:

These errors are usually caused by a server issue.

Examples

Example 1: To delete a task definition that has been deregistered

This example deletes a specified deregistered task definition.

$result = $client->deleteTaskDefinitions([
    'taskDefinitions' => [
        'Example-task-definition:1',
    ],
]);

Result syntax:

[
    'failures' => [
    ],
    'taskDefinitions' => [
        [
            'containerDefinitions' => [
                [
                    'name' => 'wave',
                    'command' => [
                        'apt-get update; apt-get install stress; while true; do stress --cpu $(( RANDOM % 4 )) -t $(( RANDOM % 10 )); done',
                    ],
                    'cpu' => 50,
                    'entryPoint' => [
                        'bash',
                        '-c',
                    ],
                    'environment' => [
                    ],
                    'essential' => 1,
                    'image' => 'public.ecr.aws/docker/library/ubuntu:latest',
                    'memory' => 100,
                    'mountPoints' => [
                    ],
                    'portMappings' => [
                    ],
                    'volumesFrom' => [
                    ],
                ],
            ],
            'family' => 'cpu-wave',
            'revision' => 1,
            'status' => 'DELETE_IN_PROGRESS',
            'taskDefinitionArn' => 'arn:aws:ecs:us-east-1:012345678910:task-definition/Example-task-definition:1',
            'volumes' => [
            ],
        ],
    ],
]

DeleteTaskSet

$result = $client->deleteTaskSet([/* ... */]);
$promise = $client->deleteTaskSetAsync([/* ... */]);

Deletes a specified task set within a service. This is used when a service uses the EXTERNAL deployment controller type. For more information, see Amazon ECS deployment types in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->deleteTaskSet([
    'cluster' => '<string>', // REQUIRED
    'force' => true || false,
    'service' => '<string>', // REQUIRED
    'taskSet' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'taskSet' => [
        'capacityProviderStrategy' => [
            [
                'base' => <integer>,
                'capacityProvider' => '<string>',
                'weight' => <integer>,
            ],
            // ...
        ],
        'clusterArn' => '<string>',
        'computedDesiredCount' => <integer>,
        'createdAt' => <DateTime>,
        'externalId' => '<string>',
        'fargateEphemeralStorage' => [
            'kmsKeyId' => '<string>',
        ],
        'id' => '<string>',
        'launchType' => 'EC2|FARGATE|EXTERNAL',
        'loadBalancers' => [
            [
                'containerName' => '<string>',
                'containerPort' => <integer>,
                'loadBalancerName' => '<string>',
                'targetGroupArn' => '<string>',
            ],
            // ...
        ],
        'networkConfiguration' => [
            'awsvpcConfiguration' => [
                'assignPublicIp' => 'ENABLED|DISABLED',
                'securityGroups' => ['<string>', ...],
                'subnets' => ['<string>', ...],
            ],
        ],
        'pendingCount' => <integer>,
        'platformFamily' => '<string>',
        'platformVersion' => '<string>',
        'runningCount' => <integer>,
        'scale' => [
            'unit' => 'PERCENT',
            'value' => <float>,
        ],
        'serviceArn' => '<string>',
        'serviceRegistries' => [
            [
                'containerName' => '<string>',
                'containerPort' => <integer>,
                'port' => <integer>,
                'registryArn' => '<string>',
            ],
            // ...
        ],
        'stabilityStatus' => 'STEADY_STATE|STABILIZING',
        'stabilityStatusAt' => <DateTime>,
        'startedBy' => '<string>',
        'status' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'taskDefinition' => '<string>',
        'taskSetArn' => '<string>',
        'updatedAt' => <DateTime>,
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

AccessDeniedException:

You don't have authorization to perform the requested action.

ServiceNotFoundException:

The specified service wasn't found. You can view your available services with ListServices. Amazon ECS services are cluster specific and Region specific.

ServiceNotActiveException:

The specified service isn't active. You can't update a service that's inactive. If you have previously deleted a service, you can re-create it with CreateService.

TaskSetNotFoundException:

The specified task set wasn't found. You can view your available task sets with DescribeTaskSets. Task sets are specific to each cluster, service and Region.

Examples

Example 1: To delete a task set within a service that uses the EXTERNAL deployment controller type

This example deletes a task set and uses the force flag to force deletion if it hasn't scaled to zero.

$result = $client->deleteTaskSet([
    'cluster' => 'MyCluster',
    'force' => 1,
    'service' => 'MyService',
    'taskSet' => 'arn:aws:ecs:us-west-2:123456789012:task-set/MyCluster/MyService/ecs-svc/1234567890123456789',
]);

Result syntax:

[
    'taskSet' => [
        'computedDesiredCount' => 0,
        'createdAt' => ,
        'id' => 'ecs-svc/1234567890123456789',
        'launchType' => 'EC2',
        'loadBalancers' => [
        ],
        'networkConfiguration' => [
            'awsvpcConfiguration' => [
                'assignPublicIp' => 'DISABLED',
                'securityGroups' => [
                    'sg-12345678',
                ],
                'subnets' => [
                    'subnet-12345678',
                ],
            ],
        ],
        'pendingCount' => 0,
        'runningCount' => 0,
        'scale' => [
            'value' => 0,
            'unit' => 'PERCENT',
        ],
        'serviceRegistries' => [
        ],
        'stabilityStatus' => 'STABILIZING',
        'stabilityStatusAt' => ,
        'status' => 'DRAINING',
        'taskDefinition' => 'arn:aws:ecs:us-west-2:123456789012:task-definition/sample-fargate:2',
        'taskSetArn' => 'arn:aws:ecs:us-west-2:123456789012:task-set/MyCluster/MyService/ecs-svc/1234567890123456789',
        'updatedAt' => ,
    ],
]

DeregisterContainerInstance

$result = $client->deregisterContainerInstance([/* ... */]);
$promise = $client->deregisterContainerInstanceAsync([/* ... */]);

Deregisters an Amazon ECS container instance from the specified cluster. This instance is no longer available to run tasks.

If you intend to use the container instance for some other purpose after deregistration, we recommend that you stop all of the tasks running on the container instance before deregistration. That prevents any orphaned tasks from consuming resources.

Deregistering a container instance removes the instance from a cluster, but it doesn't terminate the EC2 instance. If you are finished using the instance, be sure to terminate it in the Amazon EC2 console to stop billing.

Parameter Syntax

$result = $client->deregisterContainerInstance([
    'cluster' => '<string>',
    'containerInstance' => '<string>', // REQUIRED
    'force' => true || false,
]);

Parameter Details

Result Syntax

[
    'containerInstance' => [
        'agentConnected' => true || false,
        'agentUpdateStatus' => 'PENDING|STAGING|STAGED|UPDATING|UPDATED|FAILED',
        'attachments' => [
            [
                'details' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'id' => '<string>',
                'status' => '<string>',
                'type' => '<string>',
            ],
            // ...
        ],
        'attributes' => [
            [
                'name' => '<string>',
                'targetId' => '<string>',
                'targetType' => 'container-instance',
                'value' => '<string>',
            ],
            // ...
        ],
        'capacityProviderName' => '<string>',
        'containerInstanceArn' => '<string>',
        'ec2InstanceId' => '<string>',
        'healthStatus' => [
            'details' => [
                [
                    'lastStatusChange' => <DateTime>,
                    'lastUpdated' => <DateTime>,
                    'status' => 'OK|IMPAIRED|INSUFFICIENT_DATA|INITIALIZING',
                    'type' => 'CONTAINER_RUNTIME',
                ],
                // ...
            ],
            'overallStatus' => 'OK|IMPAIRED|INSUFFICIENT_DATA|INITIALIZING',
        ],
        'pendingTasksCount' => <integer>,
        'registeredAt' => <DateTime>,
        'registeredResources' => [
            [
                'doubleValue' => <float>,
                'integerValue' => <integer>,
                'longValue' => <integer>,
                'name' => '<string>',
                'stringSetValue' => ['<string>', ...],
                'type' => '<string>',
            ],
            // ...
        ],
        'remainingResources' => [
            [
                'doubleValue' => <float>,
                'integerValue' => <integer>,
                'longValue' => <integer>,
                'name' => '<string>',
                'stringSetValue' => ['<string>', ...],
                'type' => '<string>',
            ],
            // ...
        ],
        'runningTasksCount' => <integer>,
        'status' => '<string>',
        'statusReason' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'version' => <integer>,
        'versionInfo' => [
            'agentHash' => '<string>',
            'agentVersion' => '<string>',
            'dockerVersion' => '<string>',
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

Examples

Example 1: To deregister a container instance from a cluster

This example deregisters a container instance from the specified cluster in your default region. If there are still tasks running on the container instance, you must either stop those tasks before deregistering, or use the force option.

$result = $client->deregisterContainerInstance([
    'cluster' => 'default',
    'containerInstance' => 'container_instance_UUID',
    'force' => 1,
]);

Result syntax:

[
]

DeregisterTaskDefinition

$result = $client->deregisterTaskDefinition([/* ... */]);
$promise = $client->deregisterTaskDefinitionAsync([/* ... */]);

Deregisters the specified task definition by family and revision. Upon deregistration, the task definition is marked as INACTIVE. Existing tasks and services that reference an INACTIVE task definition continue to run without disruption. Existing services that reference an INACTIVE task definition can still scale up or down by modifying the service's desired count. If you want to delete a task definition revision, you must first deregister the task definition revision.

You can't use an INACTIVE task definition to run new tasks or create new services, and you can't update an existing service to reference an INACTIVE task definition. However, there may be up to a 10-minute window following deregistration where these restrictions have not yet taken effect.

You must deregister a task definition revision before you delete it. For more information, see DeleteTaskDefinitions.

Parameter Syntax

$result = $client->deregisterTaskDefinition([
    'taskDefinition' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'taskDefinition' => [
        'compatibilities' => ['<string>', ...],
        'containerDefinitions' => [
            [
                'command' => ['<string>', ...],
                'cpu' => <integer>,
                'credentialSpecs' => ['<string>', ...],
                'dependsOn' => [
                    [
                        'condition' => 'START|COMPLETE|SUCCESS|HEALTHY',
                        'containerName' => '<string>',
                    ],
                    // ...
                ],
                'disableNetworking' => true || false,
                'dnsSearchDomains' => ['<string>', ...],
                'dnsServers' => ['<string>', ...],
                'dockerLabels' => ['<string>', ...],
                'dockerSecurityOptions' => ['<string>', ...],
                'entryPoint' => ['<string>', ...],
                'environment' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'environmentFiles' => [
                    [
                        'type' => 's3',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'essential' => true || false,
                'extraHosts' => [
                    [
                        'hostname' => '<string>',
                        'ipAddress' => '<string>',
                    ],
                    // ...
                ],
                'firelensConfiguration' => [
                    'options' => ['<string>', ...],
                    'type' => 'fluentd|fluentbit',
                ],
                'healthCheck' => [
                    'command' => ['<string>', ...],
                    'interval' => <integer>,
                    'retries' => <integer>,
                    'startPeriod' => <integer>,
                    'timeout' => <integer>,
                ],
                'hostname' => '<string>',
                'image' => '<string>',
                'interactive' => true || false,
                'links' => ['<string>', ...],
                'linuxParameters' => [
                    'capabilities' => [
                        'add' => ['<string>', ...],
                        'drop' => ['<string>', ...],
                    ],
                    'devices' => [
                        [
                            'containerPath' => '<string>',
                            'hostPath' => '<string>',
                            'permissions' => ['<string>', ...],
                        ],
                        // ...
                    ],
                    'initProcessEnabled' => true || false,
                    'maxSwap' => <integer>,
                    'sharedMemorySize' => <integer>,
                    'swappiness' => <integer>,
                    'tmpfs' => [
                        [
                            'containerPath' => '<string>',
                            'mountOptions' => ['<string>', ...],
                            'size' => <integer>,
                        ],
                        // ...
                    ],
                ],
                'logConfiguration' => [
                    'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens',
                    'options' => ['<string>', ...],
                    'secretOptions' => [
                        [
                            'name' => '<string>',
                            'valueFrom' => '<string>',
                        ],
                        // ...
                    ],
                ],
                'memory' => <integer>,
                'memoryReservation' => <integer>,
                'mountPoints' => [
                    [
                        'containerPath' => '<string>',
                        'readOnly' => true || false,
                        'sourceVolume' => '<string>',
                    ],
                    // ...
                ],
                'name' => '<string>',
                'portMappings' => [
                    [
                        'appProtocol' => 'http|http2|grpc',
                        'containerPort' => <integer>,
                        'containerPortRange' => '<string>',
                        'hostPort' => <integer>,
                        'name' => '<string>',
                        'protocol' => 'tcp|udp',
                    ],
                    // ...
                ],
                'privileged' => true || false,
                'pseudoTerminal' => true || false,
                'readonlyRootFilesystem' => true || false,
                'repositoryCredentials' => [
                    'credentialsParameter' => '<string>',
                ],
                'resourceRequirements' => [
                    [
                        'type' => 'GPU|InferenceAccelerator',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'restartPolicy' => [
                    'enabled' => true || false,
                    'ignoredExitCodes' => [<integer>, ...],
                    'restartAttemptPeriod' => <integer>,
                ],
                'secrets' => [
                    [
                        'name' => '<string>',
                        'valueFrom' => '<string>',
                    ],
                    // ...
                ],
                'startTimeout' => <integer>,
                'stopTimeout' => <integer>,
                'systemControls' => [
                    [
                        'namespace' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'ulimits' => [
                    [
                        'hardLimit' => <integer>,
                        'name' => 'core|cpu|data|fsize|locks|memlock|msgqueue|nice|nofile|nproc|rss|rtprio|rttime|sigpending|stack',
                        'softLimit' => <integer>,
                    ],
                    // ...
                ],
                'user' => '<string>',
                'versionConsistency' => 'enabled|disabled',
                'volumesFrom' => [
                    [
                        'readOnly' => true || false,
                        'sourceContainer' => '<string>',
                    ],
                    // ...
                ],
                'workingDirectory' => '<string>',
            ],
            // ...
        ],
        'cpu' => '<string>',
        'deregisteredAt' => <DateTime>,
        'enableFaultInjection' => true || false,
        'ephemeralStorage' => [
            'sizeInGiB' => <integer>,
        ],
        'executionRoleArn' => '<string>',
        'family' => '<string>',
        'inferenceAccelerators' => [
            [
                'deviceName' => '<string>',
                'deviceType' => '<string>',
            ],
            // ...
        ],
        'ipcMode' => 'host|task|none',
        'memory' => '<string>',
        'networkMode' => 'bridge|host|awsvpc|none',
        'pidMode' => 'host|task',
        'placementConstraints' => [
            [
                'expression' => '<string>',
                'type' => 'memberOf',
            ],
            // ...
        ],
        'proxyConfiguration' => [
            'containerName' => '<string>',
            'properties' => [
                [
                    'name' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'type' => 'APPMESH',
        ],
        'registeredAt' => <DateTime>,
        'registeredBy' => '<string>',
        'requiresAttributes' => [
            [
                'name' => '<string>',
                'targetId' => '<string>',
                'targetType' => 'container-instance',
                'value' => '<string>',
            ],
            // ...
        ],
        'requiresCompatibilities' => ['<string>', ...],
        'revision' => <integer>,
        'runtimePlatform' => [
            'cpuArchitecture' => 'X86_64|ARM64',
            'operatingSystemFamily' => 'WINDOWS_SERVER_2019_FULL|WINDOWS_SERVER_2019_CORE|WINDOWS_SERVER_2016_FULL|WINDOWS_SERVER_2004_CORE|WINDOWS_SERVER_2022_CORE|WINDOWS_SERVER_2022_FULL|WINDOWS_SERVER_2025_CORE|WINDOWS_SERVER_2025_FULL|WINDOWS_SERVER_20H2_CORE|LINUX',
        ],
        'status' => 'ACTIVE|INACTIVE|DELETE_IN_PROGRESS',
        'taskDefinitionArn' => '<string>',
        'taskRoleArn' => '<string>',
        'volumes' => [
            [
                'configuredAtLaunch' => true || false,
                'dockerVolumeConfiguration' => [
                    'autoprovision' => true || false,
                    'driver' => '<string>',
                    'driverOpts' => ['<string>', ...],
                    'labels' => ['<string>', ...],
                    'scope' => 'task|shared',
                ],
                'efsVolumeConfiguration' => [
                    'authorizationConfig' => [
                        'accessPointId' => '<string>',
                        'iam' => 'ENABLED|DISABLED',
                    ],
                    'fileSystemId' => '<string>',
                    'rootDirectory' => '<string>',
                    'transitEncryption' => 'ENABLED|DISABLED',
                    'transitEncryptionPort' => <integer>,
                ],
                'fsxWindowsFileServerVolumeConfiguration' => [
                    'authorizationConfig' => [
                        'credentialsParameter' => '<string>',
                        'domain' => '<string>',
                    ],
                    'fileSystemId' => '<string>',
                    'rootDirectory' => '<string>',
                ],
                'host' => [
                    'sourcePath' => '<string>',
                ],
                'name' => '<string>',
            ],
            // ...
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To deregister a revision of a task definition

This example deregisters the first revision of the fargate-task task definition

$result = $client->deregisterTaskDefinition([
    'taskDefinition' => 'fargate-task:1',
]);

Result syntax:

[
    'taskDefinition' => [
        'containerDefinitions' => [
            [
                'name' => 'nginx',
                'cpu' => 256,
                'essential' => 1,
                'image' => 'public.ecr.aws/docker/library/nginx:latest',
                'memory' => 128,
                'portMappings' => [
                    [
                        'containerPort' => 80,
                        'hostPort' => 80,
                        'protocol' => 'tcp',
                    ],
                ],
            ],
        ],
        'family' => 'fargate-task',
        'status' => 'INACTIVE',
        'taskDefinitionArn' => 'arn:aws:ecs:us-west-2:123456789012:task-definition/fargate-task:1',
        'volumes' => [
        ],
    ],
]

DescribeCapacityProviders

$result = $client->describeCapacityProviders([/* ... */]);
$promise = $client->describeCapacityProvidersAsync([/* ... */]);

Describes one or more of your capacity providers.

Parameter Syntax

$result = $client->describeCapacityProviders([
    'capacityProviders' => ['<string>', ...],
    'include' => ['<string>', ...],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Result Syntax

[
    'capacityProviders' => [
        [
            'autoScalingGroupProvider' => [
                'autoScalingGroupArn' => '<string>',
                'managedDraining' => 'ENABLED|DISABLED',
                'managedScaling' => [
                    'instanceWarmupPeriod' => <integer>,
                    'maximumScalingStepSize' => <integer>,
                    'minimumScalingStepSize' => <integer>,
                    'status' => 'ENABLED|DISABLED',
                    'targetCapacity' => <integer>,
                ],
                'managedTerminationProtection' => 'ENABLED|DISABLED',
            ],
            'capacityProviderArn' => '<string>',
            'name' => '<string>',
            'status' => 'ACTIVE|INACTIVE',
            'tags' => [
                [
                    'key' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'updateStatus' => 'DELETE_IN_PROGRESS|DELETE_COMPLETE|DELETE_FAILED|UPDATE_IN_PROGRESS|UPDATE_COMPLETE|UPDATE_FAILED',
            'updateStatusReason' => '<string>',
        ],
        // ...
    ],
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To describe all capacity providers

This example retrieves details about all capacity providers.

$result = $client->describeCapacityProviders([
]);

Result syntax:

[
    'capacityProviders' => [
        [
            'name' => 'MyCapacityProvider',
            'autoScalingGroupProvider' => [
                'autoScalingGroupArn' => 'arn:aws:autoscaling:us-west-2:123456789012:autoScalingGroup:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111:autoScalingGroupName/MyAutoScalingGroup',
                'managedScaling' => [
                    'maximumScalingStepSize' => 1000,
                    'minimumScalingStepSize' => 1,
                    'status' => 'ENABLED',
                    'targetCapacity' => 100,
                ],
                'managedTerminationProtection' => 'ENABLED',
            ],
            'capacityProviderArn' => 'arn:aws:ecs:us-west-2:123456789012:capacity-provider/MyCapacityProvider',
            'status' => 'ACTIVE',
            'tags' => [
            ],
        ],
        [
            'name' => 'FARGATE',
            'capacityProviderArn' => 'arn:aws:ecs:us-west-2:123456789012:capacity-provider/FARGATE',
            'status' => 'ACTIVE',
            'tags' => [
            ],
        ],
        [
            'name' => 'FARGATE_SPOT',
            'capacityProviderArn' => 'arn:aws:ecs:us-west-2:123456789012:capacity-provider/FARGATE_SPOT',
            'status' => 'ACTIVE',
            'tags' => [
            ],
        ],
    ],
]

Example 2: To describe a specific capacity provider

This example retrieves details about the capacity provider MyCapacityProvider

$result = $client->describeCapacityProviders([
    'capacityProviders' => [
        'MyCapacityProvider',
    ],
    'include' => [
        'TAGS',
    ],
]);

Result syntax:

[
    'capacityProviders' => [
        [
            'name' => 'MyCapacityProvider',
            'autoScalingGroupProvider' => [
                'autoScalingGroupArn' => 'arn:aws:autoscaling:us-west-2:123456789012:autoScalingGroup:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111:autoScalingGroupName/MyAutoScalingGroup',
                'managedScaling' => [
                    'maximumScalingStepSize' => 1000,
                    'minimumScalingStepSize' => 1,
                    'status' => 'ENABLED',
                    'targetCapacity' => 100,
                ],
                'managedTerminationProtection' => 'ENABLED',
            ],
            'capacityProviderArn' => 'arn:aws:ecs:us-west-2:123456789012:capacity-provider/MyCapacityProvider',
            'status' => 'ACTIVE',
            'tags' => [
                [
                    'key' => 'environment',
                    'value' => 'production',
                ],
            ],
        ],
    ],
]

DescribeClusters

$result = $client->describeClusters([/* ... */]);
$promise = $client->describeClustersAsync([/* ... */]);

Describes one or more of your clusters.

For CLI examples, see describe-clusters.rst on GitHub.

Parameter Syntax

$result = $client->describeClusters([
    'clusters' => ['<string>', ...],
    'include' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'clusters' => [
        [
            'activeServicesCount' => <integer>,
            'attachments' => [
                [
                    'details' => [
                        [
                            'name' => '<string>',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'id' => '<string>',
                    'status' => '<string>',
                    'type' => '<string>',
                ],
                // ...
            ],
            'attachmentsStatus' => '<string>',
            'capacityProviders' => ['<string>', ...],
            'clusterArn' => '<string>',
            'clusterName' => '<string>',
            'configuration' => [
                'executeCommandConfiguration' => [
                    'kmsKeyId' => '<string>',
                    'logConfiguration' => [
                        'cloudWatchEncryptionEnabled' => true || false,
                        'cloudWatchLogGroupName' => '<string>',
                        's3BucketName' => '<string>',
                        's3EncryptionEnabled' => true || false,
                        's3KeyPrefix' => '<string>',
                    ],
                    'logging' => 'NONE|DEFAULT|OVERRIDE',
                ],
                'managedStorageConfiguration' => [
                    'fargateEphemeralStorageKmsKeyId' => '<string>',
                    'kmsKeyId' => '<string>',
                ],
            ],
            'defaultCapacityProviderStrategy' => [
                [
                    'base' => <integer>,
                    'capacityProvider' => '<string>',
                    'weight' => <integer>,
                ],
                // ...
            ],
            'pendingTasksCount' => <integer>,
            'registeredContainerInstancesCount' => <integer>,
            'runningTasksCount' => <integer>,
            'serviceConnectDefaults' => [
                'namespace' => '<string>',
            ],
            'settings' => [
                [
                    'name' => 'containerInsights',
                    'value' => '<string>',
                ],
                // ...
            ],
            'statistics' => [
                [
                    'name' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'status' => '<string>',
            'tags' => [
                [
                    'key' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
        ],
        // ...
    ],
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To describe a cluster

This example provides a description of the specified cluster in your default region.

$result = $client->describeClusters([
    'clusters' => [
        'default',
    ],
]);

Result syntax:

[
    'clusters' => [
        [
            'clusterArn' => 'arn:aws:ecs:us-east-1:aws_account_id:cluster/default',
            'clusterName' => 'default',
            'status' => 'ACTIVE',
        ],
    ],
    'failures' => [
    ],
]

DescribeContainerInstances

$result = $client->describeContainerInstances([/* ... */]);
$promise = $client->describeContainerInstancesAsync([/* ... */]);

Describes one or more container instances. Returns metadata about each container instance requested.

Parameter Syntax

$result = $client->describeContainerInstances([
    'cluster' => '<string>',
    'containerInstances' => ['<string>', ...], // REQUIRED
    'include' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'containerInstances' => [
        [
            'agentConnected' => true || false,
            'agentUpdateStatus' => 'PENDING|STAGING|STAGED|UPDATING|UPDATED|FAILED',
            'attachments' => [
                [
                    'details' => [
                        [
                            'name' => '<string>',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'id' => '<string>',
                    'status' => '<string>',
                    'type' => '<string>',
                ],
                // ...
            ],
            'attributes' => [
                [
                    'name' => '<string>',
                    'targetId' => '<string>',
                    'targetType' => 'container-instance',
                    'value' => '<string>',
                ],
                // ...
            ],
            'capacityProviderName' => '<string>',
            'containerInstanceArn' => '<string>',
            'ec2InstanceId' => '<string>',
            'healthStatus' => [
                'details' => [
                    [
                        'lastStatusChange' => <DateTime>,
                        'lastUpdated' => <DateTime>,
                        'status' => 'OK|IMPAIRED|INSUFFICIENT_DATA|INITIALIZING',
                        'type' => 'CONTAINER_RUNTIME',
                    ],
                    // ...
                ],
                'overallStatus' => 'OK|IMPAIRED|INSUFFICIENT_DATA|INITIALIZING',
            ],
            'pendingTasksCount' => <integer>,
            'registeredAt' => <DateTime>,
            'registeredResources' => [
                [
                    'doubleValue' => <float>,
                    'integerValue' => <integer>,
                    'longValue' => <integer>,
                    'name' => '<string>',
                    'stringSetValue' => ['<string>', ...],
                    'type' => '<string>',
                ],
                // ...
            ],
            'remainingResources' => [
                [
                    'doubleValue' => <float>,
                    'integerValue' => <integer>,
                    'longValue' => <integer>,
                    'name' => '<string>',
                    'stringSetValue' => ['<string>', ...],
                    'type' => '<string>',
                ],
                // ...
            ],
            'runningTasksCount' => <integer>,
            'status' => '<string>',
            'statusReason' => '<string>',
            'tags' => [
                [
                    'key' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'version' => <integer>,
            'versionInfo' => [
                'agentHash' => '<string>',
                'agentVersion' => '<string>',
                'dockerVersion' => '<string>',
            ],
        ],
        // ...
    ],
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

Examples

Example 1: To describe container instance

This example provides a description of the specified container instance in your default region, using the container instance UUID as an identifier.

$result = $client->describeContainerInstances([
    'cluster' => 'default',
    'containerInstances' => [
        'f2756532-8f13-4d53-87c9-aed50dc94cd7',
    ],
]);

Result syntax:

[
    'containerInstances' => [
        [
            'agentConnected' => 1,
            'containerInstanceArn' => 'arn:aws:ecs:us-east-1:012345678910:container-instance/default/f2756532-8f13-4d53-87c9-aed50dc94cd7',
            'ec2InstanceId' => 'i-807f3249',
            'pendingTasksCount' => 0,
            'registeredResources' => [
                [
                    'name' => 'CPU',
                    'type' => 'INTEGER',
                    'doubleValue' => 0,
                    'integerValue' => 2048,
                    'longValue' => 0,
                ],
                [
                    'name' => 'MEMORY',
                    'type' => 'INTEGER',
                    'doubleValue' => 0,
                    'integerValue' => 3768,
                    'longValue' => 0,
                ],
                [
                    'name' => 'PORTS',
                    'type' => 'STRINGSET',
                    'doubleValue' => 0,
                    'integerValue' => 0,
                    'longValue' => 0,
                    'stringSetValue' => [
                        '2376',
                        '22',
                        '51678',
                        '2375',
                    ],
                ],
            ],
            'remainingResources' => [
                [
                    'name' => 'CPU',
                    'type' => 'INTEGER',
                    'doubleValue' => 0,
                    'integerValue' => 1948,
                    'longValue' => 0,
                ],
                [
                    'name' => 'MEMORY',
                    'type' => 'INTEGER',
                    'doubleValue' => 0,
                    'integerValue' => 3668,
                    'longValue' => 0,
                ],
                [
                    'name' => 'PORTS',
                    'type' => 'STRINGSET',
                    'doubleValue' => 0,
                    'integerValue' => 0,
                    'longValue' => 0,
                    'stringSetValue' => [
                        '2376',
                        '22',
                        '80',
                        '51678',
                        '2375',
                    ],
                ],
            ],
            'runningTasksCount' => 1,
            'status' => 'ACTIVE',
        ],
    ],
    'failures' => [
    ],
]

DescribeServiceDeployments

$result = $client->describeServiceDeployments([/* ... */]);
$promise = $client->describeServiceDeploymentsAsync([/* ... */]);

Describes one or more of your service deployments.

A service deployment happens when you release a software update for the service. For more information, see View service history using Amazon ECS service deployments.

Parameter Syntax

$result = $client->describeServiceDeployments([
    'serviceDeploymentArns' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Result Syntax

[
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'serviceDeployments' => [
        [
            'alarms' => [
                'alarmNames' => ['<string>', ...],
                'status' => 'TRIGGERED|MONITORING|MONITORING_COMPLETE|DISABLED',
                'triggeredAlarmNames' => ['<string>', ...],
            ],
            'clusterArn' => '<string>',
            'createdAt' => <DateTime>,
            'deploymentCircuitBreaker' => [
                'failureCount' => <integer>,
                'status' => 'TRIGGERED|MONITORING|MONITORING_COMPLETE|DISABLED',
                'threshold' => <integer>,
            ],
            'deploymentConfiguration' => [
                'alarms' => [
                    'alarmNames' => ['<string>', ...],
                    'enable' => true || false,
                    'rollback' => true || false,
                ],
                'deploymentCircuitBreaker' => [
                    'enable' => true || false,
                    'rollback' => true || false,
                ],
                'maximumPercent' => <integer>,
                'minimumHealthyPercent' => <integer>,
            ],
            'finishedAt' => <DateTime>,
            'rollback' => [
                'reason' => '<string>',
                'serviceRevisionArn' => '<string>',
                'startedAt' => <DateTime>,
            ],
            'serviceArn' => '<string>',
            'serviceDeploymentArn' => '<string>',
            'sourceServiceRevisions' => [
                [
                    'arn' => '<string>',
                    'pendingTaskCount' => <integer>,
                    'requestedTaskCount' => <integer>,
                    'runningTaskCount' => <integer>,
                ],
                // ...
            ],
            'startedAt' => <DateTime>,
            'status' => 'PENDING|SUCCESSFUL|STOPPED|STOP_REQUESTED|IN_PROGRESS|ROLLBACK_REQUESTED|ROLLBACK_IN_PROGRESS|ROLLBACK_SUCCESSFUL|ROLLBACK_FAILED',
            'statusReason' => '<string>',
            'stoppedAt' => <DateTime>,
            'targetServiceRevision' => [
                'arn' => '<string>',
                'pendingTaskCount' => <integer>,
                'requestedTaskCount' => <integer>,
                'runningTaskCount' => <integer>,
            ],
            'updatedAt' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Errors

AccessDeniedException:

You don't have authorization to perform the requested action.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ServerException:

These errors are usually caused by a server issue.

ServiceNotFoundException:

The specified service wasn't found. You can view your available services with ListServices. Amazon ECS services are cluster specific and Region specific.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

Examples

Example 1: To describe a service deployment

This example describes a service deployment for the service sd-example in the example cluster.

$result = $client->describeServiceDeployments([
    'serviceDeploymentArns' => [
        'arn:aws:ecs:us-west-2:123456789012:service-deployment/example/sd-example/NCWGC2ZR-taawPAYrIaU5',
    ],
]);

Result syntax:

[
    'failures' => [
    ],
    'serviceDeployments' => [
        [
            'clusterArn' => 'arn:aws:ecs:us-west-2:123456789012:cluster/example',
            'deploymentConfiguration' => [
                'deploymentCircuitBreaker' => [
                    'enable' => ,
                    'rollback' => ,
                ],
                'maximumPercent' => 200,
                'minimumHealthyPercent' => 100,
            ],
            'serviceArn' => 'arn:aws:ecs:us-west-2:123456789012:service/example/sd-example',
            'serviceDeploymentArn' => 'arn:aws:ecs:us-west-2:123456789012:service-deployment/example/sd-example/NCWGC2ZR-taawPAYrIaU5',
            'status' => 'PENDING',
            'targetServiceRevision' => [
                'arn' => 'arn:aws:ecs:us-west-2:123456789012:service-revision/example/sd-example/4980306466373577095',
                'pendingTaskCount' => 0,
                'requestedTaskCount' => 0,
                'runningTaskCount' => 0,
            ],
            'updatedAt' => ,
        ],
    ],
]

DescribeServiceRevisions

$result = $client->describeServiceRevisions([/* ... */]);
$promise = $client->describeServiceRevisionsAsync([/* ... */]);

Describes one or more service revisions.

A service revision is a version of the service that includes the values for the Amazon ECS resources (for example, task definition) and the environment resources (for example, load balancers, subnets, and security groups). For more information, see Amazon ECS service revisions.

You can't describe a service revision that was created before October 25, 2024.

Parameter Syntax

$result = $client->describeServiceRevisions([
    'serviceRevisionArns' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Result Syntax

[
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'serviceRevisions' => [
        [
            'capacityProviderStrategy' => [
                [
                    'base' => <integer>,
                    'capacityProvider' => '<string>',
                    'weight' => <integer>,
                ],
                // ...
            ],
            'clusterArn' => '<string>',
            'containerImages' => [
                [
                    'containerName' => '<string>',
                    'image' => '<string>',
                    'imageDigest' => '<string>',
                ],
                // ...
            ],
            'createdAt' => <DateTime>,
            'fargateEphemeralStorage' => [
                'kmsKeyId' => '<string>',
            ],
            'guardDutyEnabled' => true || false,
            'launchType' => 'EC2|FARGATE|EXTERNAL',
            'loadBalancers' => [
                [
                    'containerName' => '<string>',
                    'containerPort' => <integer>,
                    'loadBalancerName' => '<string>',
                    'targetGroupArn' => '<string>',
                ],
                // ...
            ],
            'networkConfiguration' => [
                'awsvpcConfiguration' => [
                    'assignPublicIp' => 'ENABLED|DISABLED',
                    'securityGroups' => ['<string>', ...],
                    'subnets' => ['<string>', ...],
                ],
            ],
            'platformFamily' => '<string>',
            'platformVersion' => '<string>',
            'serviceArn' => '<string>',
            'serviceConnectConfiguration' => [
                'enabled' => true || false,
                'logConfiguration' => [
                    'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens',
                    'options' => ['<string>', ...],
                    'secretOptions' => [
                        [
                            'name' => '<string>',
                            'valueFrom' => '<string>',
                        ],
                        // ...
                    ],
                ],
                'namespace' => '<string>',
                'services' => [
                    [
                        'clientAliases' => [
                            [
                                'dnsName' => '<string>',
                                'port' => <integer>,
                            ],
                            // ...
                        ],
                        'discoveryName' => '<string>',
                        'ingressPortOverride' => <integer>,
                        'portName' => '<string>',
                        'timeout' => [
                            'idleTimeoutSeconds' => <integer>,
                            'perRequestTimeoutSeconds' => <integer>,
                        ],
                        'tls' => [
                            'issuerCertificateAuthority' => [
                                'awsPcaAuthorityArn' => '<string>',
                            ],
                            'kmsKey' => '<string>',
                            'roleArn' => '<string>',
                        ],
                    ],
                    // ...
                ],
            ],
            'serviceRegistries' => [
                [
                    'containerName' => '<string>',
                    'containerPort' => <integer>,
                    'port' => <integer>,
                    'registryArn' => '<string>',
                ],
                // ...
            ],
            'serviceRevisionArn' => '<string>',
            'taskDefinition' => '<string>',
            'volumeConfigurations' => [
                [
                    'managedEBSVolume' => [
                        'encrypted' => true || false,
                        'filesystemType' => 'ext3|ext4|xfs|ntfs',
                        'iops' => <integer>,
                        'kmsKeyId' => '<string>',
                        'roleArn' => '<string>',
                        'sizeInGiB' => <integer>,
                        'snapshotId' => '<string>',
                        'tagSpecifications' => [
                            [
                                'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
                                'resourceType' => 'volume',
                                'tags' => [
                                    [
                                        'key' => '<string>',
                                        'value' => '<string>',
                                    ],
                                    // ...
                                ],
                            ],
                            // ...
                        ],
                        'throughput' => <integer>,
                        'volumeInitializationRate' => <integer>,
                        'volumeType' => '<string>',
                    ],
                    'name' => '<string>',
                ],
                // ...
            ],
            'vpcLatticeConfigurations' => [
                [
                    'portName' => '<string>',
                    'roleArn' => '<string>',
                    'targetGroupArn' => '<string>',
                ],
                // ...
            ],
        ],
        // ...
    ],
]

Result Details

Errors

AccessDeniedException:

You don't have authorization to perform the requested action.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ServerException:

These errors are usually caused by a server issue.

ServiceNotFoundException:

The specified service wasn't found. You can view your available services with ListServices. Amazon ECS services are cluster specific and Region specific.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

Examples

Example 1: To describe a service revision

This example describes a service revision with the specified ARN

$result = $client->describeServiceRevisions([
    'serviceRevisionArns' => [
        'arn:aws:ecs:us-west-2:123456789012:service-revision/testc/sd1/4980306466373577095',
    ],
]);

Result syntax:

[
    'failures' => [
    ],
    'serviceRevisions' => [
        [
            'clusterArn' => 'arn:aws:ecs:us-west-2:123456789012:cluster/example',
            'createdAt' => ,
            'launchType' => 'FARGATE',
            'networkConfiguration' => [
                'awsvpcConfiguration' => [
                    'assignPublicIp' => 'ENABLED',
                    'securityGroups' => [
                        'sg-09605d60a6bc1b296',
                    ],
                    'subnets' => [
                        'subnet-0a4040e73895f04e1',
                    ],
                ],
            ],
            'platformFamily' => 'DockerLinux',
            'platformVersion' => '1.4.0',
            'serviceArn' => 'arn:aws:ecs:us-west-2:123456789012:service/example/sd-example',
            'serviceRevisionArn' => 'arn:aws:ecs:us-west-2:123456789012:service-revision/example/sd-example/4980306466373577095',
            'taskDefinition' => 'arn:aws:ecs:us-west-2:123456789012:task-definition/large-ngingx:1',
        ],
    ],
]

DescribeServices

$result = $client->describeServices([/* ... */]);
$promise = $client->describeServicesAsync([/* ... */]);

Describes the specified services running in your cluster.

Parameter Syntax

$result = $client->describeServices([
    'cluster' => '<string>',
    'include' => ['<string>', ...],
    'services' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Result Syntax

[
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'services' => [
        [
            'availabilityZoneRebalancing' => 'ENABLED|DISABLED',
            'capacityProviderStrategy' => [
                [
                    'base' => <integer>,
                    'capacityProvider' => '<string>',
                    'weight' => <integer>,
                ],
                // ...
            ],
            'clusterArn' => '<string>',
            'createdAt' => <DateTime>,
            'createdBy' => '<string>',
            'deploymentConfiguration' => [
                'alarms' => [
                    'alarmNames' => ['<string>', ...],
                    'enable' => true || false,
                    'rollback' => true || false,
                ],
                'deploymentCircuitBreaker' => [
                    'enable' => true || false,
                    'rollback' => true || false,
                ],
                'maximumPercent' => <integer>,
                'minimumHealthyPercent' => <integer>,
            ],
            'deploymentController' => [
                'type' => 'ECS|CODE_DEPLOY|EXTERNAL',
            ],
            'deployments' => [
                [
                    'capacityProviderStrategy' => [
                        [
                            'base' => <integer>,
                            'capacityProvider' => '<string>',
                            'weight' => <integer>,
                        ],
                        // ...
                    ],
                    'createdAt' => <DateTime>,
                    'desiredCount' => <integer>,
                    'failedTasks' => <integer>,
                    'fargateEphemeralStorage' => [
                        'kmsKeyId' => '<string>',
                    ],
                    'id' => '<string>',
                    'launchType' => 'EC2|FARGATE|EXTERNAL',
                    'networkConfiguration' => [
                        'awsvpcConfiguration' => [
                            'assignPublicIp' => 'ENABLED|DISABLED',
                            'securityGroups' => ['<string>', ...],
                            'subnets' => ['<string>', ...],
                        ],
                    ],
                    'pendingCount' => <integer>,
                    'platformFamily' => '<string>',
                    'platformVersion' => '<string>',
                    'rolloutState' => 'COMPLETED|FAILED|IN_PROGRESS',
                    'rolloutStateReason' => '<string>',
                    'runningCount' => <integer>,
                    'serviceConnectConfiguration' => [
                        'enabled' => true || false,
                        'logConfiguration' => [
                            'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens',
                            'options' => ['<string>', ...],
                            'secretOptions' => [
                                [
                                    'name' => '<string>',
                                    'valueFrom' => '<string>',
                                ],
                                // ...
                            ],
                        ],
                        'namespace' => '<string>',
                        'services' => [
                            [
                                'clientAliases' => [
                                    [
                                        'dnsName' => '<string>',
                                        'port' => <integer>,
                                    ],
                                    // ...
                                ],
                                'discoveryName' => '<string>',
                                'ingressPortOverride' => <integer>,
                                'portName' => '<string>',
                                'timeout' => [
                                    'idleTimeoutSeconds' => <integer>,
                                    'perRequestTimeoutSeconds' => <integer>,
                                ],
                                'tls' => [
                                    'issuerCertificateAuthority' => [
                                        'awsPcaAuthorityArn' => '<string>',
                                    ],
                                    'kmsKey' => '<string>',
                                    'roleArn' => '<string>',
                                ],
                            ],
                            // ...
                        ],
                    ],
                    'serviceConnectResources' => [
                        [
                            'discoveryArn' => '<string>',
                            'discoveryName' => '<string>',
                        ],
                        // ...
                    ],
                    'status' => '<string>',
                    'taskDefinition' => '<string>',
                    'updatedAt' => <DateTime>,
                    'volumeConfigurations' => [
                        [
                            'managedEBSVolume' => [
                                'encrypted' => true || false,
                                'filesystemType' => 'ext3|ext4|xfs|ntfs',
                                'iops' => <integer>,
                                'kmsKeyId' => '<string>',
                                'roleArn' => '<string>',
                                'sizeInGiB' => <integer>,
                                'snapshotId' => '<string>',
                                'tagSpecifications' => [
                                    [
                                        'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
                                        'resourceType' => 'volume',
                                        'tags' => [
                                            [
                                                'key' => '<string>',
                                                'value' => '<string>',
                                            ],
                                            // ...
                                        ],
                                    ],
                                    // ...
                                ],
                                'throughput' => <integer>,
                                'volumeInitializationRate' => <integer>,
                                'volumeType' => '<string>',
                            ],
                            'name' => '<string>',
                        ],
                        // ...
                    ],
                    'vpcLatticeConfigurations' => [
                        [
                            'portName' => '<string>',
                            'roleArn' => '<string>',
                            'targetGroupArn' => '<string>',
                        ],
                        // ...
                    ],
                ],
                // ...
            ],
            'desiredCount' => <integer>,
            'enableECSManagedTags' => true || false,
            'enableExecuteCommand' => true || false,
            'events' => [
                [
                    'createdAt' => <DateTime>,
                    'id' => '<string>',
                    'message' => '<string>',
                ],
                // ...
            ],
            'healthCheckGracePeriodSeconds' => <integer>,
            'launchType' => 'EC2|FARGATE|EXTERNAL',
            'loadBalancers' => [
                [
                    'containerName' => '<string>',
                    'containerPort' => <integer>,
                    'loadBalancerName' => '<string>',
                    'targetGroupArn' => '<string>',
                ],
                // ...
            ],
            'networkConfiguration' => [
                'awsvpcConfiguration' => [
                    'assignPublicIp' => 'ENABLED|DISABLED',
                    'securityGroups' => ['<string>', ...],
                    'subnets' => ['<string>', ...],
                ],
            ],
            'pendingCount' => <integer>,
            'placementConstraints' => [
                [
                    'expression' => '<string>',
                    'type' => 'distinctInstance|memberOf',
                ],
                // ...
            ],
            'placementStrategy' => [
                [
                    'field' => '<string>',
                    'type' => 'random|spread|binpack',
                ],
                // ...
            ],
            'platformFamily' => '<string>',
            'platformVersion' => '<string>',
            'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
            'roleArn' => '<string>',
            'runningCount' => <integer>,
            'schedulingStrategy' => 'REPLICA|DAEMON',
            'serviceArn' => '<string>',
            'serviceName' => '<string>',
            'serviceRegistries' => [
                [
                    'containerName' => '<string>',
                    'containerPort' => <integer>,
                    'port' => <integer>,
                    'registryArn' => '<string>',
                ],
                // ...
            ],
            'status' => '<string>',
            'tags' => [
                [
                    'key' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'taskDefinition' => '<string>',
            'taskSets' => [
                [
                    'capacityProviderStrategy' => [
                        [
                            'base' => <integer>,
                            'capacityProvider' => '<string>',
                            'weight' => <integer>,
                        ],
                        // ...
                    ],
                    'clusterArn' => '<string>',
                    'computedDesiredCount' => <integer>,
                    'createdAt' => <DateTime>,
                    'externalId' => '<string>',
                    'fargateEphemeralStorage' => [
                        'kmsKeyId' => '<string>',
                    ],
                    'id' => '<string>',
                    'launchType' => 'EC2|FARGATE|EXTERNAL',
                    'loadBalancers' => [
                        [
                            'containerName' => '<string>',
                            'containerPort' => <integer>,
                            'loadBalancerName' => '<string>',
                            'targetGroupArn' => '<string>',
                        ],
                        // ...
                    ],
                    'networkConfiguration' => [
                        'awsvpcConfiguration' => [
                            'assignPublicIp' => 'ENABLED|DISABLED',
                            'securityGroups' => ['<string>', ...],
                            'subnets' => ['<string>', ...],
                        ],
                    ],
                    'pendingCount' => <integer>,
                    'platformFamily' => '<string>',
                    'platformVersion' => '<string>',
                    'runningCount' => <integer>,
                    'scale' => [
                        'unit' => 'PERCENT',
                        'value' => <float>,
                    ],
                    'serviceArn' => '<string>',
                    'serviceRegistries' => [
                        [
                            'containerName' => '<string>',
                            'containerPort' => <integer>,
                            'port' => <integer>,
                            'registryArn' => '<string>',
                        ],
                        // ...
                    ],
                    'stabilityStatus' => 'STEADY_STATE|STABILIZING',
                    'stabilityStatusAt' => <DateTime>,
                    'startedBy' => '<string>',
                    'status' => '<string>',
                    'tags' => [
                        [
                            'key' => '<string>',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'taskDefinition' => '<string>',
                    'taskSetArn' => '<string>',
                    'updatedAt' => <DateTime>,
                ],
                // ...
            ],
        ],
        // ...
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

Examples

Example 1: To describe a service

This example provides descriptive information about the service named ``ecs-simple-service``.

$result = $client->describeServices([
    'services' => [
        'ecs-simple-service',
    ],
]);

Result syntax:

[
    'failures' => [
    ],
    'services' => [
        [
            'clusterArn' => 'arn:aws:ecs:us-east-1:012345678910:cluster/default',
            'createdAt' => ,
            'deploymentConfiguration' => [
                'maximumPercent' => 200,
                'minimumHealthyPercent' => 100,
            ],
            'deployments' => [
                [
                    'createdAt' => ,
                    'desiredCount' => 1,
                    'id' => 'ecs-svc/9223370564341623665',
                    'pendingCount' => 0,
                    'runningCount' => 0,
                    'status' => 'PRIMARY',
                    'taskDefinition' => 'arn:aws:ecs:us-east-1:012345678910:task-definition/hello_world:6',
                    'updatedAt' => ,
                ],
            ],
            'desiredCount' => 1,
            'events' => [
                [
                    'createdAt' => ,
                    'id' => '38c285e5-d335-4b68-8b15-e46dedc8e88d',
                    'message' => '(service ecs-simple-service) was unable to place a task because no container instance met all of its requirements. The closest matching (container-instance 3f4de1c5-ffdd-4954-af7e-75b4be0c8841) is already using a port required by your task. For more information, see the Troubleshooting section of the Amazon ECS Developer Guide.',
                ],
            ],
            'loadBalancers' => [
            ],
            'pendingCount' => 0,
            'runningCount' => 0,
            'serviceArn' => 'arn:aws:ecs:us-east-1:012345678910:service/default/ecs-simple-service',
            'serviceName' => 'ecs-simple-service',
            'status' => 'ACTIVE',
            'taskDefinition' => 'arn:aws:ecs:us-east-1:012345678910:task-definition/default/hello_world:6',
        ],
    ],
]

DescribeTaskDefinition

$result = $client->describeTaskDefinition([/* ... */]);
$promise = $client->describeTaskDefinitionAsync([/* ... */]);

Describes a task definition. You can specify a family and revision to find information about a specific task definition, or you can simply specify the family to find the latest ACTIVE revision in that family.

Parameter Syntax

$result = $client->describeTaskDefinition([
    'include' => ['<string>', ...],
    'taskDefinition' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'taskDefinition' => [
        'compatibilities' => ['<string>', ...],
        'containerDefinitions' => [
            [
                'command' => ['<string>', ...],
                'cpu' => <integer>,
                'credentialSpecs' => ['<string>', ...],
                'dependsOn' => [
                    [
                        'condition' => 'START|COMPLETE|SUCCESS|HEALTHY',
                        'containerName' => '<string>',
                    ],
                    // ...
                ],
                'disableNetworking' => true || false,
                'dnsSearchDomains' => ['<string>', ...],
                'dnsServers' => ['<string>', ...],
                'dockerLabels' => ['<string>', ...],
                'dockerSecurityOptions' => ['<string>', ...],
                'entryPoint' => ['<string>', ...],
                'environment' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'environmentFiles' => [
                    [
                        'type' => 's3',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'essential' => true || false,
                'extraHosts' => [
                    [
                        'hostname' => '<string>',
                        'ipAddress' => '<string>',
                    ],
                    // ...
                ],
                'firelensConfiguration' => [
                    'options' => ['<string>', ...],
                    'type' => 'fluentd|fluentbit',
                ],
                'healthCheck' => [
                    'command' => ['<string>', ...],
                    'interval' => <integer>,
                    'retries' => <integer>,
                    'startPeriod' => <integer>,
                    'timeout' => <integer>,
                ],
                'hostname' => '<string>',
                'image' => '<string>',
                'interactive' => true || false,
                'links' => ['<string>', ...],
                'linuxParameters' => [
                    'capabilities' => [
                        'add' => ['<string>', ...],
                        'drop' => ['<string>', ...],
                    ],
                    'devices' => [
                        [
                            'containerPath' => '<string>',
                            'hostPath' => '<string>',
                            'permissions' => ['<string>', ...],
                        ],
                        // ...
                    ],
                    'initProcessEnabled' => true || false,
                    'maxSwap' => <integer>,
                    'sharedMemorySize' => <integer>,
                    'swappiness' => <integer>,
                    'tmpfs' => [
                        [
                            'containerPath' => '<string>',
                            'mountOptions' => ['<string>', ...],
                            'size' => <integer>,
                        ],
                        // ...
                    ],
                ],
                'logConfiguration' => [
                    'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens',
                    'options' => ['<string>', ...],
                    'secretOptions' => [
                        [
                            'name' => '<string>',
                            'valueFrom' => '<string>',
                        ],
                        // ...
                    ],
                ],
                'memory' => <integer>,
                'memoryReservation' => <integer>,
                'mountPoints' => [
                    [
                        'containerPath' => '<string>',
                        'readOnly' => true || false,
                        'sourceVolume' => '<string>',
                    ],
                    // ...
                ],
                'name' => '<string>',
                'portMappings' => [
                    [
                        'appProtocol' => 'http|http2|grpc',
                        'containerPort' => <integer>,
                        'containerPortRange' => '<string>',
                        'hostPort' => <integer>,
                        'name' => '<string>',
                        'protocol' => 'tcp|udp',
                    ],
                    // ...
                ],
                'privileged' => true || false,
                'pseudoTerminal' => true || false,
                'readonlyRootFilesystem' => true || false,
                'repositoryCredentials' => [
                    'credentialsParameter' => '<string>',
                ],
                'resourceRequirements' => [
                    [
                        'type' => 'GPU|InferenceAccelerator',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'restartPolicy' => [
                    'enabled' => true || false,
                    'ignoredExitCodes' => [<integer>, ...],
                    'restartAttemptPeriod' => <integer>,
                ],
                'secrets' => [
                    [
                        'name' => '<string>',
                        'valueFrom' => '<string>',
                    ],
                    // ...
                ],
                'startTimeout' => <integer>,
                'stopTimeout' => <integer>,
                'systemControls' => [
                    [
                        'namespace' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'ulimits' => [
                    [
                        'hardLimit' => <integer>,
                        'name' => 'core|cpu|data|fsize|locks|memlock|msgqueue|nice|nofile|nproc|rss|rtprio|rttime|sigpending|stack',
                        'softLimit' => <integer>,
                    ],
                    // ...
                ],
                'user' => '<string>',
                'versionConsistency' => 'enabled|disabled',
                'volumesFrom' => [
                    [
                        'readOnly' => true || false,
                        'sourceContainer' => '<string>',
                    ],
                    // ...
                ],
                'workingDirectory' => '<string>',
            ],
            // ...
        ],
        'cpu' => '<string>',
        'deregisteredAt' => <DateTime>,
        'enableFaultInjection' => true || false,
        'ephemeralStorage' => [
            'sizeInGiB' => <integer>,
        ],
        'executionRoleArn' => '<string>',
        'family' => '<string>',
        'inferenceAccelerators' => [
            [
                'deviceName' => '<string>',
                'deviceType' => '<string>',
            ],
            // ...
        ],
        'ipcMode' => 'host|task|none',
        'memory' => '<string>',
        'networkMode' => 'bridge|host|awsvpc|none',
        'pidMode' => 'host|task',
        'placementConstraints' => [
            [
                'expression' => '<string>',
                'type' => 'memberOf',
            ],
            // ...
        ],
        'proxyConfiguration' => [
            'containerName' => '<string>',
            'properties' => [
                [
                    'name' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'type' => 'APPMESH',
        ],
        'registeredAt' => <DateTime>,
        'registeredBy' => '<string>',
        'requiresAttributes' => [
            [
                'name' => '<string>',
                'targetId' => '<string>',
                'targetType' => 'container-instance',
                'value' => '<string>',
            ],
            // ...
        ],
        'requiresCompatibilities' => ['<string>', ...],
        'revision' => <integer>,
        'runtimePlatform' => [
            'cpuArchitecture' => 'X86_64|ARM64',
            'operatingSystemFamily' => 'WINDOWS_SERVER_2019_FULL|WINDOWS_SERVER_2019_CORE|WINDOWS_SERVER_2016_FULL|WINDOWS_SERVER_2004_CORE|WINDOWS_SERVER_2022_CORE|WINDOWS_SERVER_2022_FULL|WINDOWS_SERVER_2025_CORE|WINDOWS_SERVER_2025_FULL|WINDOWS_SERVER_20H2_CORE|LINUX',
        ],
        'status' => 'ACTIVE|INACTIVE|DELETE_IN_PROGRESS',
        'taskDefinitionArn' => '<string>',
        'taskRoleArn' => '<string>',
        'volumes' => [
            [
                'configuredAtLaunch' => true || false,
                'dockerVolumeConfiguration' => [
                    'autoprovision' => true || false,
                    'driver' => '<string>',
                    'driverOpts' => ['<string>', ...],
                    'labels' => ['<string>', ...],
                    'scope' => 'task|shared',
                ],
                'efsVolumeConfiguration' => [
                    'authorizationConfig' => [
                        'accessPointId' => '<string>',
                        'iam' => 'ENABLED|DISABLED',
                    ],
                    'fileSystemId' => '<string>',
                    'rootDirectory' => '<string>',
                    'transitEncryption' => 'ENABLED|DISABLED',
                    'transitEncryptionPort' => <integer>,
                ],
                'fsxWindowsFileServerVolumeConfiguration' => [
                    'authorizationConfig' => [
                        'credentialsParameter' => '<string>',
                        'domain' => '<string>',
                    ],
                    'fileSystemId' => '<string>',
                    'rootDirectory' => '<string>',
                ],
                'host' => [
                    'sourcePath' => '<string>',
                ],
                'name' => '<string>',
            ],
            // ...
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To describe a task definition

This example provides a description of the specified task definition.

$result = $client->describeTaskDefinition([
    'taskDefinition' => 'hello_world:8',
]);

Result syntax:

[
    'taskDefinition' => [
        'containerDefinitions' => [
            [
                'name' => 'wordpress',
                'cpu' => 10,
                'environment' => [
                ],
                'essential' => 1,
                'image' => 'wordpress',
                'links' => [
                    'mysql',
                ],
                'memory' => 500,
                'mountPoints' => [
                ],
                'portMappings' => [
                    [
                        'containerPort' => 80,
                        'hostPort' => 80,
                    ],
                ],
                'volumesFrom' => [
                ],
            ],
            [
                'name' => 'mysql',
                'cpu' => 10,
                'environment' => [
                    [
                        'name' => 'MYSQL_ROOT_PASSWORD',
                        'value' => 'password',
                    ],
                ],
                'essential' => 1,
                'image' => 'mysql',
                'memory' => 500,
                'mountPoints' => [
                ],
                'portMappings' => [
                ],
                'volumesFrom' => [
                ],
            ],
        ],
        'family' => 'hello_world',
        'revision' => 8,
        'taskDefinitionArn' => 'arn:aws:ecs:us-east-1::task-definition/hello_world:8',
        'volumes' => [
        ],
    ],
]

DescribeTaskSets

$result = $client->describeTaskSets([/* ... */]);
$promise = $client->describeTaskSetsAsync([/* ... */]);

Describes the task sets in the specified cluster and service. This is used when a service uses the EXTERNAL deployment controller type. For more information, see Amazon ECS Deployment Types in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->describeTaskSets([
    'cluster' => '<string>', // REQUIRED
    'include' => ['<string>', ...],
    'service' => '<string>', // REQUIRED
    'taskSets' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'taskSets' => [
        [
            'capacityProviderStrategy' => [
                [
                    'base' => <integer>,
                    'capacityProvider' => '<string>',
                    'weight' => <integer>,
                ],
                // ...
            ],
            'clusterArn' => '<string>',
            'computedDesiredCount' => <integer>,
            'createdAt' => <DateTime>,
            'externalId' => '<string>',
            'fargateEphemeralStorage' => [
                'kmsKeyId' => '<string>',
            ],
            'id' => '<string>',
            'launchType' => 'EC2|FARGATE|EXTERNAL',
            'loadBalancers' => [
                [
                    'containerName' => '<string>',
                    'containerPort' => <integer>,
                    'loadBalancerName' => '<string>',
                    'targetGroupArn' => '<string>',
                ],
                // ...
            ],
            'networkConfiguration' => [
                'awsvpcConfiguration' => [
                    'assignPublicIp' => 'ENABLED|DISABLED',
                    'securityGroups' => ['<string>', ...],
                    'subnets' => ['<string>', ...],
                ],
            ],
            'pendingCount' => <integer>,
            'platformFamily' => '<string>',
            'platformVersion' => '<string>',
            'runningCount' => <integer>,
            'scale' => [
                'unit' => 'PERCENT',
                'value' => <float>,
            ],
            'serviceArn' => '<string>',
            'serviceRegistries' => [
                [
                    'containerName' => '<string>',
                    'containerPort' => <integer>,
                    'port' => <integer>,
                    'registryArn' => '<string>',
                ],
                // ...
            ],
            'stabilityStatus' => 'STEADY_STATE|STABILIZING',
            'stabilityStatusAt' => <DateTime>,
            'startedBy' => '<string>',
            'status' => '<string>',
            'tags' => [
                [
                    'key' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'taskDefinition' => '<string>',
            'taskSetArn' => '<string>',
            'updatedAt' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

AccessDeniedException:

You don't have authorization to perform the requested action.

ServiceNotFoundException:

The specified service wasn't found. You can view your available services with ListServices. Amazon ECS services are cluster specific and Region specific.

ServiceNotActiveException:

The specified service isn't active. You can't update a service that's inactive. If you have previously deleted a service, you can re-create it with CreateService.

Examples

Example 1: To describe a task set

This example describes a task set in service MyService that uses an EXTERNAL deployment controller.

$result = $client->describeTaskSets([
    'cluster' => 'MyCluster',
    'service' => 'MyService',
    'taskSets' => [
        'arn:aws:ecs:us-west-2:123456789012:task-set/MyCluster/MyService/ecs-svc/1234567890123456789',
    ],
]);

Result syntax:

[
    'failures' => [
    ],
    'taskSets' => [
        [
            'computedDesiredCount' => 0,
            'createdAt' => ,
            'id' => 'ecs-svc/1234567890123456789',
            'launchType' => 'EC2',
            'loadBalancers' => [
            ],
            'networkConfiguration' => [
                'awsvpcConfiguration' => [
                    'assignPublicIp' => 'DISABLED',
                    'securityGroups' => [
                        'sg-1234431',
                    ],
                    'subnets' => [
                        'subnet-12344321',
                    ],
                ],
            ],
            'pendingCount' => 0,
            'runningCount' => 0,
            'scale' => [
                'value' => 0,
                'unit' => 'PERCENT',
            ],
            'serviceRegistries' => [
            ],
            'stabilityStatus' => 'STEADY_STATE',
            'stabilityStatusAt' => ,
            'status' => 'ACTIVE',
            'taskDefinition' => 'arn:aws:ecs:us-west-2:123456789012:task-definition/sample-fargate:2',
            'taskSetArn' => 'arn:aws:ecs:us-west-2:123456789012:task-set/MyCluster/MyService/ecs-svc/1234567890123456789',
            'updatedAt' => ,
        ],
    ],
]

DescribeTasks

$result = $client->describeTasks([/* ... */]);
$promise = $client->describeTasksAsync([/* ... */]);

Describes a specified task or tasks.

Currently, stopped tasks appear in the returned results for at least one hour.

If you have tasks with tags, and then delete the cluster, the tagged tasks are returned in the response. If you create a new cluster with the same name as the deleted cluster, the tagged tasks are not included in the response.

Parameter Syntax

$result = $client->describeTasks([
    'cluster' => '<string>',
    'include' => ['<string>', ...],
    'tasks' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Result Syntax

[
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'tasks' => [
        [
            'attachments' => [
                [
                    'details' => [
                        [
                            'name' => '<string>',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'id' => '<string>',
                    'status' => '<string>',
                    'type' => '<string>',
                ],
                // ...
            ],
            'attributes' => [
                [
                    'name' => '<string>',
                    'targetId' => '<string>',
                    'targetType' => 'container-instance',
                    'value' => '<string>',
                ],
                // ...
            ],
            'availabilityZone' => '<string>',
            'capacityProviderName' => '<string>',
            'clusterArn' => '<string>',
            'connectivity' => 'CONNECTED|DISCONNECTED',
            'connectivityAt' => <DateTime>,
            'containerInstanceArn' => '<string>',
            'containers' => [
                [
                    'containerArn' => '<string>',
                    'cpu' => '<string>',
                    'exitCode' => <integer>,
                    'gpuIds' => ['<string>', ...],
                    'healthStatus' => 'HEALTHY|UNHEALTHY|UNKNOWN',
                    'image' => '<string>',
                    'imageDigest' => '<string>',
                    'lastStatus' => '<string>',
                    'managedAgents' => [
                        [
                            'lastStartedAt' => <DateTime>,
                            'lastStatus' => '<string>',
                            'name' => 'ExecuteCommandAgent',
                            'reason' => '<string>',
                        ],
                        // ...
                    ],
                    'memory' => '<string>',
                    'memoryReservation' => '<string>',
                    'name' => '<string>',
                    'networkBindings' => [
                        [
                            'bindIP' => '<string>',
                            'containerPort' => <integer>,
                            'containerPortRange' => '<string>',
                            'hostPort' => <integer>,
                            'hostPortRange' => '<string>',
                            'protocol' => 'tcp|udp',
                        ],
                        // ...
                    ],
                    'networkInterfaces' => [
                        [
                            'attachmentId' => '<string>',
                            'ipv6Address' => '<string>',
                            'privateIpv4Address' => '<string>',
                        ],
                        // ...
                    ],
                    'reason' => '<string>',
                    'runtimeId' => '<string>',
                    'taskArn' => '<string>',
                ],
                // ...
            ],
            'cpu' => '<string>',
            'createdAt' => <DateTime>,
            'desiredStatus' => '<string>',
            'enableExecuteCommand' => true || false,
            'ephemeralStorage' => [
                'sizeInGiB' => <integer>,
            ],
            'executionStoppedAt' => <DateTime>,
            'fargateEphemeralStorage' => [
                'kmsKeyId' => '<string>',
                'sizeInGiB' => <integer>,
            ],
            'group' => '<string>',
            'healthStatus' => 'HEALTHY|UNHEALTHY|UNKNOWN',
            'inferenceAccelerators' => [
                [
                    'deviceName' => '<string>',
                    'deviceType' => '<string>',
                ],
                // ...
            ],
            'lastStatus' => '<string>',
            'launchType' => 'EC2|FARGATE|EXTERNAL',
            'memory' => '<string>',
            'overrides' => [
                'containerOverrides' => [
                    [
                        'command' => ['<string>', ...],
                        'cpu' => <integer>,
                        'environment' => [
                            [
                                'name' => '<string>',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                        'environmentFiles' => [
                            [
                                'type' => 's3',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                        'memory' => <integer>,
                        'memoryReservation' => <integer>,
                        'name' => '<string>',
                        'resourceRequirements' => [
                            [
                                'type' => 'GPU|InferenceAccelerator',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    // ...
                ],
                'cpu' => '<string>',
                'ephemeralStorage' => [
                    'sizeInGiB' => <integer>,
                ],
                'executionRoleArn' => '<string>',
                'inferenceAcceleratorOverrides' => [
                    [
                        'deviceName' => '<string>',
                        'deviceType' => '<string>',
                    ],
                    // ...
                ],
                'memory' => '<string>',
                'taskRoleArn' => '<string>',
            ],
            'platformFamily' => '<string>',
            'platformVersion' => '<string>',
            'pullStartedAt' => <DateTime>,
            'pullStoppedAt' => <DateTime>,
            'startedAt' => <DateTime>,
            'startedBy' => '<string>',
            'stopCode' => 'TaskFailedToStart|EssentialContainerExited|UserInitiated|ServiceSchedulerInitiated|SpotInterruption|TerminationNotice',
            'stoppedAt' => <DateTime>,
            'stoppedReason' => '<string>',
            'stoppingAt' => <DateTime>,
            'tags' => [
                [
                    'key' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'taskArn' => '<string>',
            'taskDefinitionArn' => '<string>',
            'version' => <integer>,
        ],
        // ...
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

Examples

Example 1: To describe a task

This example provides a description of the specified task, using the task UUID as an identifier.

$result = $client->describeTasks([
    'tasks' => [
        'c5cba4eb-5dad-405e-96db-71ef8eefe6a8',
    ],
]);

Result syntax:

[
    'failures' => [
    ],
    'tasks' => [
        [
            'clusterArn' => 'arn:aws:ecs:::cluster/default',
            'containerInstanceArn' => 'arn:aws:ecs:::container-instance/default/18f9eda5-27d7-4c19-b133-45adc516e8fb',
            'containers' => [
                [
                    'name' => 'ecs-demo',
                    'containerArn' => 'arn:aws:ecs:::container/7c01765b-c588-45b3-8290-4ba38bd6c5a6',
                    'lastStatus' => 'RUNNING',
                    'networkBindings' => [
                        [
                            'bindIP' => '0.0.0.0',
                            'containerPort' => 80,
                            'hostPort' => 80,
                        ],
                    ],
                    'taskArn' => 'arn:aws:ecs:::task/default/c5cba4eb-5dad-405e-96db-71ef8eefe6a8',
                ],
            ],
            'desiredStatus' => 'RUNNING',
            'lastStatus' => 'RUNNING',
            'overrides' => [
                'containerOverrides' => [
                    [
                        'name' => 'ecs-demo',
                    ],
                ],
            ],
            'startedBy' => 'ecs-svc/9223370608528463088',
            'taskArn' => 'arn:aws:ecs:::task/default/c5cba4eb-5dad-405e-96db-71ef8eefe6a8',
            'taskDefinitionArn' => 'arn:aws:ecs:::task-definition/amazon-ecs-sample:1',
        ],
    ],
]

DiscoverPollEndpoint

$result = $client->discoverPollEndpoint([/* ... */]);
$promise = $client->discoverPollEndpointAsync([/* ... */]);

This action is only used by the Amazon ECS agent, and it is not intended for use outside of the agent.

Returns an endpoint for the Amazon ECS agent to poll for updates.

Parameter Syntax

$result = $client->discoverPollEndpoint([
    'cluster' => '<string>',
    'containerInstance' => '<string>',
]);

Parameter Details

Result Syntax

[
    'endpoint' => '<string>',
    'serviceConnectEndpoint' => '<string>',
    'telemetryEndpoint' => '<string>',
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

ExecuteCommand

$result = $client->executeCommand([/* ... */]);
$promise = $client->executeCommandAsync([/* ... */]);

Runs a command remotely on a container within a task.

If you use a condition key in your IAM policy to refine the conditions for the policy statement, for example limit the actions to a specific cluster, you receive an AccessDeniedException when there is a mismatch between the condition key value and the corresponding parameter value.

For information about required permissions and considerations, see Using Amazon ECS Exec for debugging in the Amazon ECS Developer Guide.

Parameter Syntax

$result = $client->executeCommand([
    'cluster' => '<string>',
    'command' => '<string>', // REQUIRED
    'container' => '<string>',
    'interactive' => true || false, // REQUIRED
    'task' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'clusterArn' => '<string>',
    'containerArn' => '<string>',
    'containerName' => '<string>',
    'interactive' => true || false,
    'session' => [
        'sessionId' => '<string>',
        'streamUrl' => '<string>',
        'tokenValue' => '<string>',
    ],
    'taskArn' => '<string>',
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

AccessDeniedException:

You don't have authorization to perform the requested action.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

TargetNotConnectedException:

The execute command cannot run. This error can be caused by any of the following configuration issues:

• Incorrect IAM permissions

• The SSM agent is not installed or is not running

• There is an interface Amazon VPC endpoint for Amazon ECS, but there is not one for Systems Manager Session Manager

For information about how to troubleshoot the issues, see Troubleshooting issues with ECS Exec in the Amazon Elastic Container Service Developer Guide.

Examples

Example 1: To run a command remotely on a container in a task

This example runs an interactive /bin/sh command on a container MyContainer.

$result = $client->executeCommand([
    'cluster' => 'MyCluster',
    'command' => '/bin/sh',
    'container' => 'MyContainer',
    'interactive' => 1,
    'task' => 'arn:aws:ecs:us-east-1:123456789012:task/MyCluster/d789e94343414c25b9f6bd59eEXAMPLE',
]);

Result syntax:

[
    'clusterArn' => 'arn:aws:ecs:us-east-1:123456789012:cluster/MyCluster',
    'containerArn' => 'arn:aws:ecs:us-east-1:123456789012:container/MyCluster/d789e94343414c25b9f6bd59eEXAMPLE/43ba4b77-37f7-4a41-b923-69d4abEXAMPLE',
    'containerName' => 'MyContainer',
    'interactive' => 1,
    'session' => [
        'sessionId' => 'ecs-execute-command-794nnsxobsg4p2hiur6gxu9a9e',
        'streamUrl' => 'wss://ssmmessages.us-east-1.amazonaws.com/v1/data-channel/ecs-execute-command-794nnsxobsg4p2hiur6gxu9a9e?role=publish_subscribe&cell-number=AAEAAfiZG4oybxqsYj3Zhm15s4J0W1k7d9nxVRenNO8Kl5nzAAAAAGdbWGl479/y/4IrTWPadUic3eBrMu3vmB7aPvI+s12lbpDc142y1KZy',
        'tokenValue' => 'AAEAAcVb7ww10N9aNUI5Cl7K7DbHjbD2Ed4Mw6uaGYIc+UFNAAAAAGdbWGmMDaPbGfDkzrVIhyKEsc4CPT2hcToPU6yzlddPm7rRZvYQtpaAgsvQdjbCAd9OB6ohtDYfqZI9gzMqLKegXq0E+KbDcGPnQVODFNHmQxnR1BvC6vNcHqh6HAJuKnQD7RSYx/J5bfYNHj4hCYHuN0HNcueSDOOTRB/MBt5DBDY7Djv2uzs9FD0N1kcsGljZkZWLuPTVKHHyrU3zh0awfrFFC3RXvgaUCBnloIIvZeq2CjTesxn9JJS+3N4I0DVxfkHdWWBbBY/5+wH82JVTJpqN3yOAt74u/W7TvYBd7Xu2lQbvtpuAnEszl++bFG2ZoV3dfnmBkSnfD/qV1FJcEskbxUHKgmqe0Paouv4zwrQKNfWYfcv9xkWskqcExh07IeaxZz1tp/WegZ5D76sD6xYeuH+35TMNXMoY7oudLgxIXsA7b39ElM7orGi4Jy3W2tLyuNIvDoI2JI6ww4tYdEjYZnld9rhKwV9rDHk1Z8wjHMs++3BIkHrFQRsv7BFUWlZ9lyqO9GWlXeBe7dQtOeFNahBuJUE9z/xLHJn1x13VkdROKqUVHTJrT4sXAnI5roWiGPoQPVY7aHVYJnwjSxrPRWJBsgyHiVN3dAWTmeVMjp0VbOiJaLlpBI+AUWs8OeVRzuJSZ+1alETpK7Ukag7ma9K4lxq/N7IxYo2ub0cG/bvX42zQqdJAW+9St9sQ1QMaMvkSq1tdbLoOuY0QjN7JrkuKLFQA5bhs+o1YwItzIp7bNrzQ9Z9IN51qoGL5HDXQzi1kNFfYtAryhwt6BgtQU9Z0k+RpE+V5G+V68E0MMUvb313f0nRBYj1u5VKonWb708wADPbUU+s7nvbWuD5oLp1Z6A4iqI9Om0R4RrFASj/7fVY7r3raNXcIYA=',
    ],
    'taskArn' => 'arn:aws:ecs:us-east-1:123456789012:task/MyCluster/d789e94343414c25b9f6bd59eEXAMPLE',
]

GetTaskProtection

$result = $client->getTaskProtection([/* ... */]);
$promise = $client->getTaskProtectionAsync([/* ... */]);

Retrieves the protection status of tasks in an Amazon ECS service.

Parameter Syntax

$result = $client->getTaskProtection([
    'cluster' => '<string>', // REQUIRED
    'tasks' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'protectedTasks' => [
        [
            'expirationDate' => <DateTime>,
            'protectionEnabled' => true || false,
            'taskArn' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

AccessDeniedException:

You don't have authorization to perform the requested action.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ResourceNotFoundException:

The specified resource wasn't found.

ServerException:

These errors are usually caused by a server issue.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

Examples

Example 1: To get the protection status of a task

In this example, we get the protection status for a single task.

$result = $client->getTaskProtection([
    'cluster' => 'test-task-protection',
    'tasks' => [
        'b8b1cf532d0e46ba8d44a40d1de16772',
    ],
]);

Result syntax:

[
    'failures' => [
    ],
    'protectedTasks' => [
        [
            'expirationDate' => ,
            'protectionEnabled' => 1,
            'taskArn' => 'arn:aws:ecs:us-west-2:012345678910:task/default/b8b1cf532d0e46ba8d44a40d1de16772',
        ],
    ],
]

ListAccountSettings

$result = $client->listAccountSettings([/* ... */]);
$promise = $client->listAccountSettingsAsync([/* ... */]);

Lists the account settings for a specified principal.

Parameter Syntax

$result = $client->listAccountSettings([
    'effectiveSettings' => true || false,
    'maxResults' => <integer>,
    'name' => 'serviceLongArnFormat|taskLongArnFormat|containerInstanceLongArnFormat|awsvpcTrunking|containerInsights|fargateFIPSMode|tagResourceAuthorization|fargateTaskRetirementWaitPeriod|guardDutyActivate|defaultLogDriverMode',
    'nextToken' => '<string>',
    'principalArn' => '<string>',
    'value' => '<string>',
]);

Parameter Details

Result Syntax

[
    'nextToken' => '<string>',
    'settings' => [
        [
            'name' => 'serviceLongArnFormat|taskLongArnFormat|containerInstanceLongArnFormat|awsvpcTrunking|containerInsights|fargateFIPSMode|tagResourceAuthorization|fargateTaskRetirementWaitPeriod|guardDutyActivate|defaultLogDriverMode',
            'principalArn' => '<string>',
            'type' => 'user|aws_managed',
            'value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To view your effective account settings

This example displays the effective account settings for your account.

$result = $client->listAccountSettings([
    'effectiveSettings' => 1,
]);

Result syntax:

[
    'settings' => [
        [
            'name' => 'containerInstanceLongArnFormat',
            'value' => 'disabled',
            'principalArn' => 'arn:aws:iam:::user/principalName',
        ],
        [
            'name' => 'serviceLongArnFormat',
            'value' => 'enabled',
            'principalArn' => 'arn:aws:iam:::user/principalName',
        ],
        [
            'name' => 'taskLongArnFormat',
            'value' => 'disabled',
            'principalArn' => 'arn:aws:iam:::user/principalName',
        ],
    ],
]

Example 2: To view the effective account settings for a specific IAM user or IAM role

This example displays the effective account settings for the specified user or role.

$result = $client->listAccountSettings([
    'effectiveSettings' => 1,
    'principalArn' => 'arn:aws:iam:::user/principalName',
]);

Result syntax:

[
    'settings' => [
        [
            'name' => 'containerInstanceLongArnFormat',
            'value' => 'disabled',
            'principalArn' => 'arn:aws:iam:::user/principalName',
        ],
        [
            'name' => 'serviceLongArnFormat',
            'value' => 'enabled',
            'principalArn' => 'arn:aws:iam:::user/principalName',
        ],
        [
            'name' => 'taskLongArnFormat',
            'value' => 'disabled',
            'principalArn' => 'arn:aws:iam:::user/principalName',
        ],
    ],
]

ListAttributes

$result = $client->listAttributes([/* ... */]);
$promise = $client->listAttributesAsync([/* ... */]);

Lists the attributes for Amazon ECS resources within a specified target type and cluster. When you specify a target type and cluster, ListAttributes returns a list of attribute objects, one for each attribute on each resource. You can filter the list of results to a single attribute name to only return results that have that name. You can also filter the results by attribute name and value. You can do this, for example, to see which container instances in a cluster are running a Linux AMI (ecs.os-type=linux).

Parameter Syntax

$result = $client->listAttributes([
    'attributeName' => '<string>',
    'attributeValue' => '<string>',
    'cluster' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'targetType' => 'container-instance', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'attributes' => [
        [
            'name' => '<string>',
            'targetId' => '<string>',
            'targetType' => 'container-instance',
            'value' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Errors

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To list container instances that have a specific attribute

This example lists attributes for a container instance with the attribute "stack" equal to the value "production".

$result = $client->listAttributes([
    'attributeName' => 'stack',
    'attributeValue' => 'production',
    'cluster' => 'MyCluster',
    'targetType' => 'container-instance',
]);

Result syntax:

[
    'attributes' => [
        [
            'name' => 'stack',
            'value' => 'production',
            'targetId' => 'arn:aws:ecs:us-west-2:123456789012:container-instance/1c3be8ed-df30-47b4-8f1e-6e68ebd01f34',
        ],
    ],
]

ListClusters

$result = $client->listClusters([/* ... */]);
$promise = $client->listClustersAsync([/* ... */]);

Returns a list of existing clusters.

Parameter Syntax

$result = $client->listClusters([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Result Syntax

[
    'clusterArns' => ['<string>', ...],
    'nextToken' => '<string>',
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To list your available clusters

This example lists all of your available clusters in your default region.

$result = $client->listClusters([
]);

Result syntax:

[
    'clusterArns' => [
        'arn:aws:ecs:us-east-1::cluster/test',
        'arn:aws:ecs:us-east-1::cluster/default',
    ],
]

ListContainerInstances

$result = $client->listContainerInstances([/* ... */]);
$promise = $client->listContainerInstancesAsync([/* ... */]);

Returns a list of container instances in a specified cluster. You can filter the results of a ListContainerInstances operation with cluster query language statements inside the filter parameter. For more information, see Cluster Query Language in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->listContainerInstances([
    'cluster' => '<string>',
    'filter' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'status' => 'ACTIVE|DRAINING|REGISTERING|DEREGISTERING|REGISTRATION_FAILED',
]);

Parameter Details

Result Syntax

[
    'containerInstanceArns' => ['<string>', ...],
    'nextToken' => '<string>',
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

Examples

Example 1: To list your available container instances in a cluster

This example lists all of your available container instances in the specified cluster in your default region.

$result = $client->listContainerInstances([
    'cluster' => 'default',
]);

Result syntax:

[
    'containerInstanceArns' => [
        'arn:aws:ecs:us-east-1::container-instance/default/f6bbb147-5370-4ace-8c73-c7181ded911f',
        'arn:aws:ecs:us-east-1::container-instance/default/ffe3d344-77e2-476c-a4d0-bf560ad50acb',
    ],
]

ListServiceDeployments

$result = $client->listServiceDeployments([/* ... */]);
$promise = $client->listServiceDeploymentsAsync([/* ... */]);

This operation lists all the service deployments that meet the specified filter criteria.

A service deployment happens when you release a software update for the service. You route traffic from the running service revisions to the new service revison and control the number of running tasks.

This API returns the values that you use for the request parameters in DescribeServiceRevisions.

Parameter Syntax

$result = $client->listServiceDeployments([
    'cluster' => '<string>',
    'createdAt' => [
        'after' => <integer || string || DateTime>,
        'before' => <integer || string || DateTime>,
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'service' => '<string>', // REQUIRED
    'status' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'nextToken' => '<string>',
    'serviceDeployments' => [
        [
            'clusterArn' => '<string>',
            'createdAt' => <DateTime>,
            'finishedAt' => <DateTime>,
            'serviceArn' => '<string>',
            'serviceDeploymentArn' => '<string>',
            'startedAt' => <DateTime>,
            'status' => 'PENDING|SUCCESSFUL|STOPPED|STOP_REQUESTED|IN_PROGRESS|ROLLBACK_REQUESTED|ROLLBACK_IN_PROGRESS|ROLLBACK_SUCCESSFUL|ROLLBACK_FAILED',
            'statusReason' => '<string>',
            'targetServiceRevisionArn' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

AccessDeniedException:

You don't have authorization to perform the requested action.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ServerException:

These errors are usually caused by a server issue.

ServiceNotFoundException:

The specified service wasn't found. You can view your available services with ListServices. Amazon ECS services are cluster specific and Region specific.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

Examples

Example 1: To list service deployments that meet the specified criteria

This example lists all successful service deployments for the service "sd-example" in the cluster "example".

$result = $client->listServiceDeployments([
    'cluster' => 'example',
    'service' => 'sd-example',
    'status' => [
        'SUCCESSFUL',
    ],
]);

Result syntax:

[
    'serviceDeployments' => [
        [
            'clusterArn' => 'arn:aws:ecs:us-west-2:123456789012:cluster/example',
            'serviceArn' => 'arn:aws:ecs:us-west-2:123456789012:service/example/sd-example',
            'serviceDeploymentArn' => 'arn:aws:ecs:us-west-2:123456789012:service-deployment/example/sd-example/NCWGC2ZR-taawPAYrIaU5',
            'status' => 'SUCCESSFUL',
            'targetServiceRevisionArn' => 'arn:aws:ecs:us-west-2:123456789012:service-revision/example/sd-example/4980306466373577095',
        ],
    ],
]

ListServices

$result = $client->listServices([/* ... */]);
$promise = $client->listServicesAsync([/* ... */]);

Returns a list of services. You can filter the results by cluster, launch type, and scheduling strategy.

Parameter Syntax

$result = $client->listServices([
    'cluster' => '<string>',
    'launchType' => 'EC2|FARGATE|EXTERNAL',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'schedulingStrategy' => 'REPLICA|DAEMON',
]);

Parameter Details

Result Syntax

[
    'nextToken' => '<string>',
    'serviceArns' => ['<string>', ...],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

Examples

Example 1: To list the services in a cluster

This example lists the services running in the default cluster for an account.

$result = $client->listServices([
]);

Result syntax:

[
    'serviceArns' => [
        'arn:aws:ecs:us-east-1:012345678910:service/default/my-http-service',
    ],
]

ListServicesByNamespace

$result = $client->listServicesByNamespace([/* ... */]);
$promise = $client->listServicesByNamespaceAsync([/* ... */]);

This operation lists all of the services that are associated with a Cloud Map namespace. This list might include services in different clusters. In contrast, ListServices can only list services in one cluster at a time. If you need to filter the list of services in a single cluster by various parameters, use ListServices. For more information, see Service Connect in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->listServicesByNamespace([
    'maxResults' => <integer>,
    'namespace' => '<string>', // REQUIRED
    'nextToken' => '<string>',
]);

Parameter Details

Result Syntax

[
    'nextToken' => '<string>',
    'serviceArns' => ['<string>', ...],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

NamespaceNotFoundException:

The specified namespace wasn't found.

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

List the tags for an Amazon ECS resource.

Parameter Syntax

$result = $client->listTagsForResource([
    'resourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To list the tags for a cluster.

This example lists the tags for the 'dev' cluster.

$result = $client->listTagsForResource([
    'resourceArn' => 'arn:aws:ecs:region:aws_account_id:cluster/dev',
]);

Result syntax:

[
    'tags' => [
        [
            'key' => 'team',
            'value' => 'dev',
        ],
    ],
]

ListTaskDefinitionFamilies

$result = $client->listTaskDefinitionFamilies([/* ... */]);
$promise = $client->listTaskDefinitionFamiliesAsync([/* ... */]);

Returns a list of task definition families that are registered to your account. This list includes task definition families that no longer have any ACTIVE task definition revisions.

You can filter out task definition families that don't contain any ACTIVE task definition revisions by setting the status parameter to ACTIVE. You can also filter the results with the familyPrefix parameter.

Parameter Syntax

$result = $client->listTaskDefinitionFamilies([
    'familyPrefix' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'status' => 'ACTIVE|INACTIVE|ALL',
]);

Parameter Details

Result Syntax

[
    'families' => ['<string>', ...],
    'nextToken' => '<string>',
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To list your registered task definition families

This example lists all of your registered task definition families.

$result = $client->listTaskDefinitionFamilies([
]);

Result syntax:

[
    'families' => [
        'node-js-app',
        'web-timer',
        'hpcc',
        'hpcc-c4-8xlarge',
    ],
]

Example 2: To filter your registered task definition families

This example lists the task definition revisions that start with "hpcc".

$result = $client->listTaskDefinitionFamilies([
    'familyPrefix' => 'hpcc',
]);

Result syntax:

[
    'families' => [
        'hpcc',
        'hpcc-c4-8xlarge',
    ],
]

ListTaskDefinitions

$result = $client->listTaskDefinitions([/* ... */]);
$promise = $client->listTaskDefinitionsAsync([/* ... */]);

Returns a list of task definitions that are registered to your account. You can filter the results by family name with the familyPrefix parameter or by status with the status parameter.

Parameter Syntax

$result = $client->listTaskDefinitions([
    'familyPrefix' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'sort' => 'ASC|DESC',
    'status' => 'ACTIVE|INACTIVE|DELETE_IN_PROGRESS',
]);

Parameter Details

Result Syntax

[
    'nextToken' => '<string>',
    'taskDefinitionArns' => ['<string>', ...],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To list your registered task definitions

This example lists all of your registered task definitions.

$result = $client->listTaskDefinitions([
]);

Result syntax:

[
    'taskDefinitionArns' => [
        'arn:aws:ecs:us-east-1::task-definition/sleep300:2',
        'arn:aws:ecs:us-east-1::task-definition/sleep360:1',
        'arn:aws:ecs:us-east-1::task-definition/wordpress:3',
        'arn:aws:ecs:us-east-1::task-definition/wordpress:4',
        'arn:aws:ecs:us-east-1::task-definition/wordpress:5',
        'arn:aws:ecs:us-east-1::task-definition/wordpress:6',
    ],
]

Example 2: To list the registered task definitions in a family

This example lists the task definition revisions of a specified family.

$result = $client->listTaskDefinitions([
    'familyPrefix' => 'wordpress',
]);

Result syntax:

[
    'taskDefinitionArns' => [
        'arn:aws:ecs:us-east-1::task-definition/wordpress:3',
        'arn:aws:ecs:us-east-1::task-definition/wordpress:4',
        'arn:aws:ecs:us-east-1::task-definition/wordpress:5',
        'arn:aws:ecs:us-east-1::task-definition/wordpress:6',
    ],
]

ListTasks

$result = $client->listTasks([/* ... */]);
$promise = $client->listTasksAsync([/* ... */]);

Returns a list of tasks. You can filter the results by cluster, task definition family, container instance, launch type, what IAM principal started the task, or by the desired status of the task.

Recently stopped tasks might appear in the returned results.

Parameter Syntax

$result = $client->listTasks([
    'cluster' => '<string>',
    'containerInstance' => '<string>',
    'desiredStatus' => 'RUNNING|PENDING|STOPPED',
    'family' => '<string>',
    'launchType' => 'EC2|FARGATE|EXTERNAL',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'serviceName' => '<string>',
    'startedBy' => '<string>',
]);

Parameter Details

Result Syntax

[
    'nextToken' => '<string>',
    'taskArns' => ['<string>', ...],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

ServiceNotFoundException:

The specified service wasn't found. You can view your available services with ListServices. Amazon ECS services are cluster specific and Region specific.

Examples

Example 1: To list the tasks in a cluster

This example lists all of the tasks in a cluster.

$result = $client->listTasks([
    'cluster' => 'default',
]);

Result syntax:

[
    'taskArns' => [
        'arn:aws:ecs:us-east-1:012345678910:task/default/0cc43cdb-3bee-4407-9c26-c0e6ea5bee84',
        'arn:aws:ecs:us-east-1:012345678910:task/default/6b809ef6-c67e-4467-921f-ee261c15a0a1',
    ],
]

Example 2: To list the tasks on a particular container instance

This example lists the tasks of a specified container instance. Specifying a ``containerInstance`` value limits the results to tasks that belong to that container instance.

$result = $client->listTasks([
    'cluster' => 'default',
    'containerInstance' => 'f6bbb147-5370-4ace-8c73-c7181ded911f',
]);

Result syntax:

[
    'taskArns' => [
        'arn:aws:ecs:us-east-1:012345678910:task/default/0cc43cdb-3bee-4407-9c26-c0e6ea5bee84',
    ],
]

PutAccountSetting

$result = $client->putAccountSetting([/* ... */]);
$promise = $client->putAccountSettingAsync([/* ... */]);

Modifies an account setting. Account settings are set on a per-Region basis.

If you change the root user account setting, the default settings are reset for users and roles that do not have specified individual account settings. For more information, see Account Settings in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->putAccountSetting([
    'name' => 'serviceLongArnFormat|taskLongArnFormat|containerInstanceLongArnFormat|awsvpcTrunking|containerInsights|fargateFIPSMode|tagResourceAuthorization|fargateTaskRetirementWaitPeriod|guardDutyActivate|defaultLogDriverMode', // REQUIRED
    'principalArn' => '<string>',
    'value' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'setting' => [
        'name' => 'serviceLongArnFormat|taskLongArnFormat|containerInstanceLongArnFormat|awsvpcTrunking|containerInsights|fargateFIPSMode|tagResourceAuthorization|fargateTaskRetirementWaitPeriod|guardDutyActivate|defaultLogDriverMode',
        'principalArn' => '<string>',
        'type' => 'user|aws_managed',
        'value' => '<string>',
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To modify your account settings

This example modifies your account settings to opt in to the new ARN and resource ID format for Amazon ECS services. If you’re using this command as the root user, then changes apply to the entire AWS account, unless an IAM user or role explicitly overrides these settings for themselves.

$result = $client->putAccountSetting([
    'name' => 'serviceLongArnFormat',
    'value' => 'enabled',
]);

Result syntax:

[
    'setting' => [
        'name' => 'serviceLongArnFormat',
        'value' => 'enabled',
        'principalArn' => 'arn:aws:iam:::user/principalName',
    ],
]

Example 2: To modify the account settings for a specific IAM user or IAM role

This example modifies the account setting for a specific IAM user or IAM role to opt in to the new ARN and resource ID format for Amazon ECS container instances. If you’re using this command as the root user, then changes apply to the entire AWS account, unless an IAM user or role explicitly overrides these settings for themselves.

$result = $client->putAccountSetting([
    'name' => 'containerInstanceLongArnFormat',
    'value' => 'enabled',
    'principalArn' => 'arn:aws:iam:::user/principalName',
]);

Result syntax:

[
    'setting' => [
        'name' => 'containerInstanceLongArnFormat',
        'value' => 'enabled',
        'principalArn' => 'arn:aws:iam:::user/principalName',
    ],
]

PutAccountSettingDefault

$result = $client->putAccountSettingDefault([/* ... */]);
$promise = $client->putAccountSettingDefaultAsync([/* ... */]);

Modifies an account setting for all users on an account for whom no individual account setting has been specified. Account settings are set on a per-Region basis.

Parameter Syntax

$result = $client->putAccountSettingDefault([
    'name' => 'serviceLongArnFormat|taskLongArnFormat|containerInstanceLongArnFormat|awsvpcTrunking|containerInsights|fargateFIPSMode|tagResourceAuthorization|fargateTaskRetirementWaitPeriod|guardDutyActivate|defaultLogDriverMode', // REQUIRED
    'value' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'setting' => [
        'name' => 'serviceLongArnFormat|taskLongArnFormat|containerInstanceLongArnFormat|awsvpcTrunking|containerInsights|fargateFIPSMode|tagResourceAuthorization|fargateTaskRetirementWaitPeriod|guardDutyActivate|defaultLogDriverMode',
        'principalArn' => '<string>',
        'type' => 'user|aws_managed',
        'value' => '<string>',
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To modify the default account settings for all IAM users or roles on an account

This example modifies the default account setting for the specified resource for all IAM users or roles on an account. These changes apply to the entire AWS account, unless an IAM user or role explicitly overrides these settings for themselves.

$result = $client->putAccountSettingDefault([
    'name' => 'serviceLongArnFormat',
    'value' => 'enabled',
]);

Result syntax:

[
    'setting' => [
        'name' => 'serviceLongArnFormat',
        'value' => 'enabled',
        'principalArn' => 'arn:aws:iam:::root',
    ],
]

PutAttributes

$result = $client->putAttributes([/* ... */]);
$promise = $client->putAttributesAsync([/* ... */]);

Create or update an attribute on an Amazon ECS resource. If the attribute doesn't exist, it's created. If the attribute exists, its value is replaced with the specified value. To delete an attribute, use DeleteAttributes. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->putAttributes([
    'attributes' => [ // REQUIRED
        [
            'name' => '<string>', // REQUIRED
            'targetId' => '<string>',
            'targetType' => 'container-instance',
            'value' => '<string>',
        ],
        // ...
    ],
    'cluster' => '<string>',
]);

Parameter Details

Result Syntax

[
    'attributes' => [
        [
            'name' => '<string>',
            'targetId' => '<string>',
            'targetType' => 'container-instance',
            'value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

TargetNotFoundException:

The specified target wasn't found. You can view your available container instances with ListContainerInstances. Amazon ECS container instances are cluster-specific and Region-specific.

AttributeLimitExceededException:

You can apply up to 10 custom attributes for each resource. You can view the attributes of a resource with ListAttributes. You can remove existing attributes on a resource with DeleteAttributes.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To create or update an attribute on a resource

This example adds an attribute "stack" with the value "production" to a container instance.

$result = $client->putAttributes([
    'attributes' => [
        [
            'name' => 'stack',
            'value' => 'production',
            'targetId' => 'arn:aws:ecs:us-west-2:123456789012:container-instance/1c3be8ed-df30-47b4-8f1e-6e68ebd01f34',
        ],
    ],
    'cluster' => 'MyCluster',
]);

Result syntax:

[
    'attributes' => [
        [
            'name' => 'stack',
            'value' => 'production',
            'targetId' => 'arn:aws:ecs:us-west-2:123456789012:container-instance/1c3be8ed-df30-47b4-8f1e-6e68ebd01f34',
        ],
    ],
]

PutClusterCapacityProviders

$result = $client->putClusterCapacityProviders([/* ... */]);
$promise = $client->putClusterCapacityProvidersAsync([/* ... */]);

Modifies the available capacity providers and the default capacity provider strategy for a cluster.

You must specify both the available capacity providers and a default capacity provider strategy for the cluster. If the specified cluster has existing capacity providers associated with it, you must specify all existing capacity providers in addition to any new ones you want to add. Any existing capacity providers that are associated with a cluster that are omitted from a PutClusterCapacityProviders API call will be disassociated with the cluster. You can only disassociate an existing capacity provider from a cluster if it's not being used by any existing tasks.

When creating a service or running a task on a cluster, if no capacity provider or launch type is specified, then the cluster's default capacity provider strategy is used. We recommend that you define a default capacity provider strategy for your cluster. However, you must specify an empty array ([]) to bypass defining a default strategy.

Parameter Syntax

$result = $client->putClusterCapacityProviders([
    'capacityProviders' => ['<string>', ...], // REQUIRED
    'cluster' => '<string>', // REQUIRED
    'defaultCapacityProviderStrategy' => [ // REQUIRED
        [
            'base' => <integer>,
            'capacityProvider' => '<string>', // REQUIRED
            'weight' => <integer>,
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'cluster' => [
        'activeServicesCount' => <integer>,
        'attachments' => [
            [
                'details' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'id' => '<string>',
                'status' => '<string>',
                'type' => '<string>',
            ],
            // ...
        ],
        'attachmentsStatus' => '<string>',
        'capacityProviders' => ['<string>', ...],
        'clusterArn' => '<string>',
        'clusterName' => '<string>',
        'configuration' => [
            'executeCommandConfiguration' => [
                'kmsKeyId' => '<string>',
                'logConfiguration' => [
                    'cloudWatchEncryptionEnabled' => true || false,
                    'cloudWatchLogGroupName' => '<string>',
                    's3BucketName' => '<string>',
                    's3EncryptionEnabled' => true || false,
                    's3KeyPrefix' => '<string>',
                ],
                'logging' => 'NONE|DEFAULT|OVERRIDE',
            ],
            'managedStorageConfiguration' => [
                'fargateEphemeralStorageKmsKeyId' => '<string>',
                'kmsKeyId' => '<string>',
            ],
        ],
        'defaultCapacityProviderStrategy' => [
            [
                'base' => <integer>,
                'capacityProvider' => '<string>',
                'weight' => <integer>,
            ],
            // ...
        ],
        'pendingTasksCount' => <integer>,
        'registeredContainerInstancesCount' => <integer>,
        'runningTasksCount' => <integer>,
        'serviceConnectDefaults' => [
            'namespace' => '<string>',
        ],
        'settings' => [
            [
                'name' => 'containerInsights',
                'value' => '<string>',
            ],
            // ...
        ],
        'statistics' => [
            [
                'name' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'status' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

ResourceInUseException:

The specified resource is in-use and can't be removed.

UpdateInProgressException:

There's already a current Amazon ECS container agent update in progress on the container instance that's specified. If the container agent becomes disconnected while it's in a transitional stage, such as PENDING or STAGING, the update process can get stuck in that state. However, when the agent reconnects, it resumes where it stopped previously.

Examples

Example 1: To add an existing capacity provider to a cluuster

This example adds an existing capacity provider "MyCapacityProvider2" to a cluster that already has the capacity provider "MyCapacityProvider1" associated with it. Both "MyCapacityProvider2" and "MyCapacityProvider1" need to be specified.

$result = $client->putClusterCapacityProviders([
    'capacityProviders' => [
        'MyCapacityProvider1',
        'MyCapacityProvider2',
    ],
    'cluster' => 'MyCluster',
    'defaultCapacityProviderStrategy' => [
        [
            'capacityProvider' => 'MyCapacityProvider1',
            'weight' => 1,
        ],
        [
            'capacityProvider' => 'MyCapacityProvider2',
            'weight' => 1,
        ],
    ],
]);

Result syntax:

[
    'cluster' => [
        'activeServicesCount' => 0,
        'attachments' => [
            [
                'type' => 'as_policy',
                'details' => [
                    [
                        'name' => 'capacityProviderName',
                        'value' => 'MyCapacityProvider1',
                    ],
                    [
                        'name' => 'scalingPolicyName',
                        'value' => 'ECSManagedAutoScalingPolicy-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111',
                    ],
                ],
                'id' => '0fb0c8f4-6edd-4de1-9b09-17e470ee1918',
                'status' => 'ACTIVE',
            ],
            [
                'type' => 'as_policy',
                'details' => [
                    [
                        'name' => 'capacityProviderName',
                        'value' => 'MyCapacityProvider2',
                    ],
                    [
                        'name' => 'scalingPolicyName',
                        'value' => 'ECSManagedAutoScalingPolicy-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222',
                    ],
                ],
                'id' => 'ae592060-2382-4663-9476-b015c685593c',
                'status' => 'ACTIVE',
            ],
        ],
        'attachmentsStatus' => 'UPDATE_IN_PROGRESS',
        'capacityProviders' => [
            'MyCapacityProvider1',
            'MyCapacityProvider2',
        ],
        'clusterArn' => 'arn:aws:ecs:us-west-2:123456789012:cluster/MyCluster',
        'clusterName' => 'MyCluster',
        'defaultCapacityProviderStrategy' => [
            [
                'base' => 0,
                'capacityProvider' => 'MyCapacityProvider1',
                'weight' => 1,
            ],
            [
                'base' => 0,
                'capacityProvider' => 'MyCapacityProvider2',
                'weight' => 1,
            ],
        ],
        'pendingTasksCount' => 0,
        'registeredContainerInstancesCount' => 0,
        'runningTasksCount' => 0,
        'settings' => [
            [
                'name' => 'containerInsights',
                'value' => 'enabled',
            ],
        ],
        'statistics' => [
        ],
        'status' => 'ACTIVE',
        'tags' => [
        ],
    ],
]

Example 2: To remove a capacity provider from a cluster

This example removes a capacity provider "MyCapacityProvider2" from a cluster that has both "MyCapacityProvider2" and "MyCapacityProvider1" associated with it. Only "MyCapacityProvider1" needs to be specified in this scenario.

$result = $client->putClusterCapacityProviders([
    'capacityProviders' => [
        'MyCapacityProvider1',
    ],
    'cluster' => 'MyCluster',
    'defaultCapacityProviderStrategy' => [
        [
            'base' => 0,
            'capacityProvider' => 'MyCapacityProvider1',
            'weight' => 1,
        ],
    ],
]);

Result syntax:

[
    'cluster' => [
        'activeServicesCount' => 0,
        'attachments' => [
            [
                'type' => 'as_policy',
                'details' => [
                    [
                        'name' => 'capacityProviderName',
                        'value' => 'MyCapacityProvider1',
                    ],
                    [
                        'name' => 'scalingPolicyName',
                        'value' => 'ECSManagedAutoScalingPolicy-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111',
                    ],
                ],
                'id' => '0fb0c8f4-6edd-4de1-9b09-17e470ee1918',
                'status' => 'ACTIVE',
            ],
            [
                'type' => 'as_policy',
                'details' => [
                    [
                        'name' => 'capacityProviderName',
                        'value' => 'MyCapacityProvider2',
                    ],
                    [
                        'name' => 'scalingPolicyName',
                        'value' => 'ECSManagedAutoScalingPolicy-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222',
                    ],
                ],
                'id' => 'ae592060-2382-4663-9476-b015c685593c',
                'status' => 'DELETING',
            ],
        ],
        'attachmentsStatus' => 'UPDATE_IN_PROGRESS',
        'capacityProviders' => [
            'MyCapacityProvider1',
        ],
        'clusterArn' => 'arn:aws:ecs:us-west-2:123456789012:cluster/MyCluster',
        'clusterName' => 'MyCluster',
        'defaultCapacityProviderStrategy' => [
            [
                'base' => 0,
                'capacityProvider' => 'MyCapacityProvider1',
                'weight' => 1,
            ],
        ],
        'pendingTasksCount' => 0,
        'registeredContainerInstancesCount' => 0,
        'runningTasksCount' => 0,
        'settings' => [
            [
                'name' => 'containerInsights',
                'value' => 'enabled',
            ],
        ],
        'statistics' => [
        ],
        'status' => 'ACTIVE',
        'tags' => [
        ],
    ],
]

Example 3: To remove all capacity providers from a cluster

This example removes all capacity providers associated with a cluster.

$result = $client->putClusterCapacityProviders([
    'capacityProviders' => [
    ],
    'cluster' => 'MyCluster',
    'defaultCapacityProviderStrategy' => [
    ],
]);

Result syntax:

[
    'cluster' => [
        'activeServicesCount' => 0,
        'attachments' => [
            [
                'type' => 'as_policy',
                'details' => [
                    [
                        'name' => 'capacityProviderName',
                        'value' => 'MyCapacityProvider1',
                    ],
                    [
                        'name' => 'scalingPolicyName',
                        'value' => 'ECSManagedAutoScalingPolicy-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111',
                    ],
                ],
                'id' => '0fb0c8f4-6edd-4de1-9b09-17e470ee1918',
                'status' => 'DELETING',
            ],
            [
                'type' => 'as_policy',
                'details' => [
                    [
                        'name' => 'capacityProviderName',
                        'value' => 'MyCapacityProvider2',
                    ],
                    [
                        'name' => 'scalingPolicyName',
                        'value' => 'ECSManagedAutoScalingPolicy-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222',
                    ],
                ],
                'id' => 'ae592060-2382-4663-9476-b015c685593c',
                'status' => 'DELETING',
            ],
        ],
        'attachmentsStatus' => 'UPDATE_IN_PROGRESS',
        'capacityProviders' => [
        ],
        'clusterArn' => 'arn:aws:ecs:us-west-2:123456789012:cluster/MyCluster',
        'clusterName' => 'MyCluster',
        'defaultCapacityProviderStrategy' => [
        ],
        'pendingTasksCount' => 0,
        'registeredContainerInstancesCount' => 0,
        'runningTasksCount' => 0,
        'settings' => [
            [
                'name' => 'containerInsights',
                'value' => 'enabled',
            ],
        ],
        'statistics' => [
        ],
        'status' => 'ACTIVE',
        'tags' => [
        ],
    ],
]

RegisterContainerInstance

$result = $client->registerContainerInstance([/* ... */]);
$promise = $client->registerContainerInstanceAsync([/* ... */]);

This action is only used by the Amazon ECS agent, and it is not intended for use outside of the agent.

Registers an EC2 instance into the specified cluster. This instance becomes available to place containers on.

Parameter Syntax

$result = $client->registerContainerInstance([
    'attributes' => [
        [
            'name' => '<string>', // REQUIRED
            'targetId' => '<string>',
            'targetType' => 'container-instance',
            'value' => '<string>',
        ],
        // ...
    ],
    'cluster' => '<string>',
    'containerInstanceArn' => '<string>',
    'instanceIdentityDocument' => '<string>',
    'instanceIdentityDocumentSignature' => '<string>',
    'platformDevices' => [
        [
            'id' => '<string>', // REQUIRED
            'type' => 'GPU', // REQUIRED
        ],
        // ...
    ],
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'totalResources' => [
        [
            'doubleValue' => <float>,
            'integerValue' => <integer>,
            'longValue' => <integer>,
            'name' => '<string>',
            'stringSetValue' => ['<string>', ...],
            'type' => '<string>',
        ],
        // ...
    ],
    'versionInfo' => [
        'agentHash' => '<string>',
        'agentVersion' => '<string>',
        'dockerVersion' => '<string>',
    ],
]);

Parameter Details

Result Syntax

[
    'containerInstance' => [
        'agentConnected' => true || false,
        'agentUpdateStatus' => 'PENDING|STAGING|STAGED|UPDATING|UPDATED|FAILED',
        'attachments' => [
            [
                'details' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'id' => '<string>',
                'status' => '<string>',
                'type' => '<string>',
            ],
            // ...
        ],
        'attributes' => [
            [
                'name' => '<string>',
                'targetId' => '<string>',
                'targetType' => 'container-instance',
                'value' => '<string>',
            ],
            // ...
        ],
        'capacityProviderName' => '<string>',
        'containerInstanceArn' => '<string>',
        'ec2InstanceId' => '<string>',
        'healthStatus' => [
            'details' => [
                [
                    'lastStatusChange' => <DateTime>,
                    'lastUpdated' => <DateTime>,
                    'status' => 'OK|IMPAIRED|INSUFFICIENT_DATA|INITIALIZING',
                    'type' => 'CONTAINER_RUNTIME',
                ],
                // ...
            ],
            'overallStatus' => 'OK|IMPAIRED|INSUFFICIENT_DATA|INITIALIZING',
        ],
        'pendingTasksCount' => <integer>,
        'registeredAt' => <DateTime>,
        'registeredResources' => [
            [
                'doubleValue' => <float>,
                'integerValue' => <integer>,
                'longValue' => <integer>,
                'name' => '<string>',
                'stringSetValue' => ['<string>', ...],
                'type' => '<string>',
            ],
            // ...
        ],
        'remainingResources' => [
            [
                'doubleValue' => <float>,
                'integerValue' => <integer>,
                'longValue' => <integer>,
                'name' => '<string>',
                'stringSetValue' => ['<string>', ...],
                'type' => '<string>',
            ],
            // ...
        ],
        'runningTasksCount' => <integer>,
        'status' => '<string>',
        'statusReason' => '<string>',
        'tags' => [
            [
                'key' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'version' => <integer>,
        'versionInfo' => [
            'agentHash' => '<string>',
            'agentVersion' => '<string>',
            'dockerVersion' => '<string>',
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

RegisterTaskDefinition

$result = $client->registerTaskDefinition([/* ... */]);
$promise = $client->registerTaskDefinitionAsync([/* ... */]);

Registers a new task definition from the supplied family and containerDefinitions. Optionally, you can add data volumes to your containers with the volumes parameter. For more information about task definition parameters and defaults, see Amazon ECS Task Definitions in the Amazon Elastic Container Service Developer Guide.

You can specify a role for your task with the taskRoleArn parameter. When you specify a role for a task, its containers can then use the latest versions of the CLI or SDKs to make API requests to the Amazon Web Services services that are specified in the policy that's associated with the role. For more information, see IAM Roles for Tasks in the Amazon Elastic Container Service Developer Guide.

You can specify a Docker networking mode for the containers in your task definition with the networkMode parameter. If you specify the awsvpc network mode, the task is allocated an elastic network interface, and you must specify a NetworkConfiguration when you create a service or run a task with the task definition. For more information, see Task Networking in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->registerTaskDefinition([
    'containerDefinitions' => [ // REQUIRED
        [
            'command' => ['<string>', ...],
            'cpu' => <integer>,
            'credentialSpecs' => ['<string>', ...],
            'dependsOn' => [
                [
                    'condition' => 'START|COMPLETE|SUCCESS|HEALTHY', // REQUIRED
                    'containerName' => '<string>', // REQUIRED
                ],
                // ...
            ],
            'disableNetworking' => true || false,
            'dnsSearchDomains' => ['<string>', ...],
            'dnsServers' => ['<string>', ...],
            'dockerLabels' => ['<string>', ...],
            'dockerSecurityOptions' => ['<string>', ...],
            'entryPoint' => ['<string>', ...],
            'environment' => [
                [
                    'name' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'environmentFiles' => [
                [
                    'type' => 's3', // REQUIRED
                    'value' => '<string>', // REQUIRED
                ],
                // ...
            ],
            'essential' => true || false,
            'extraHosts' => [
                [
                    'hostname' => '<string>', // REQUIRED
                    'ipAddress' => '<string>', // REQUIRED
                ],
                // ...
            ],
            'firelensConfiguration' => [
                'options' => ['<string>', ...],
                'type' => 'fluentd|fluentbit', // REQUIRED
            ],
            'healthCheck' => [
                'command' => ['<string>', ...], // REQUIRED
                'interval' => <integer>,
                'retries' => <integer>,
                'startPeriod' => <integer>,
                'timeout' => <integer>,
            ],
            'hostname' => '<string>',
            'image' => '<string>',
            'interactive' => true || false,
            'links' => ['<string>', ...],
            'linuxParameters' => [
                'capabilities' => [
                    'add' => ['<string>', ...],
                    'drop' => ['<string>', ...],
                ],
                'devices' => [
                    [
                        'containerPath' => '<string>',
                        'hostPath' => '<string>', // REQUIRED
                        'permissions' => ['<string>', ...],
                    ],
                    // ...
                ],
                'initProcessEnabled' => true || false,
                'maxSwap' => <integer>,
                'sharedMemorySize' => <integer>,
                'swappiness' => <integer>,
                'tmpfs' => [
                    [
                        'containerPath' => '<string>', // REQUIRED
                        'mountOptions' => ['<string>', ...],
                        'size' => <integer>, // REQUIRED
                    ],
                    // ...
                ],
            ],
            'logConfiguration' => [
                'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens', // REQUIRED
                'options' => ['<string>', ...],
                'secretOptions' => [
                    [
                        'name' => '<string>', // REQUIRED
                        'valueFrom' => '<string>', // REQUIRED
                    ],
                    // ...
                ],
            ],
            'memory' => <integer>,
            'memoryReservation' => <integer>,
            'mountPoints' => [
                [
                    'containerPath' => '<string>',
                    'readOnly' => true || false,
                    'sourceVolume' => '<string>',
                ],
                // ...
            ],
            'name' => '<string>',
            'portMappings' => [
                [
                    'appProtocol' => 'http|http2|grpc',
                    'containerPort' => <integer>,
                    'containerPortRange' => '<string>',
                    'hostPort' => <integer>,
                    'name' => '<string>',
                    'protocol' => 'tcp|udp',
                ],
                // ...
            ],
            'privileged' => true || false,
            'pseudoTerminal' => true || false,
            'readonlyRootFilesystem' => true || false,
            'repositoryCredentials' => [
                'credentialsParameter' => '<string>', // REQUIRED
            ],
            'resourceRequirements' => [
                [
                    'type' => 'GPU|InferenceAccelerator', // REQUIRED
                    'value' => '<string>', // REQUIRED
                ],
                // ...
            ],
            'restartPolicy' => [
                'enabled' => true || false, // REQUIRED
                'ignoredExitCodes' => [<integer>, ...],
                'restartAttemptPeriod' => <integer>,
            ],
            'secrets' => [
                [
                    'name' => '<string>', // REQUIRED
                    'valueFrom' => '<string>', // REQUIRED
                ],
                // ...
            ],
            'startTimeout' => <integer>,
            'stopTimeout' => <integer>,
            'systemControls' => [
                [
                    'namespace' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'ulimits' => [
                [
                    'hardLimit' => <integer>, // REQUIRED
                    'name' => 'core|cpu|data|fsize|locks|memlock|msgqueue|nice|nofile|nproc|rss|rtprio|rttime|sigpending|stack', // REQUIRED
                    'softLimit' => <integer>, // REQUIRED
                ],
                // ...
            ],
            'user' => '<string>',
            'versionConsistency' => 'enabled|disabled',
            'volumesFrom' => [
                [
                    'readOnly' => true || false,
                    'sourceContainer' => '<string>',
                ],
                // ...
            ],
            'workingDirectory' => '<string>',
        ],
        // ...
    ],
    'cpu' => '<string>',
    'enableFaultInjection' => true || false,
    'ephemeralStorage' => [
        'sizeInGiB' => <integer>, // REQUIRED
    ],
    'executionRoleArn' => '<string>',
    'family' => '<string>', // REQUIRED
    'inferenceAccelerators' => [
        [
            'deviceName' => '<string>', // REQUIRED
            'deviceType' => '<string>', // REQUIRED
        ],
        // ...
    ],
    'ipcMode' => 'host|task|none',
    'memory' => '<string>',
    'networkMode' => 'bridge|host|awsvpc|none',
    'pidMode' => 'host|task',
    'placementConstraints' => [
        [
            'expression' => '<string>',
            'type' => 'memberOf',
        ],
        // ...
    ],
    'proxyConfiguration' => [
        'containerName' => '<string>', // REQUIRED
        'properties' => [
            [
                'name' => '<string>',
                'value' => '<string>',
            ],
            // ...
        ],
        'type' => 'APPMESH',
    ],
    'requiresCompatibilities' => ['<string>', ...],
    'runtimePlatform' => [
        'cpuArchitecture' => 'X86_64|ARM64',
        'operatingSystemFamily' => 'WINDOWS_SERVER_2019_FULL|WINDOWS_SERVER_2019_CORE|WINDOWS_SERVER_2016_FULL|WINDOWS_SERVER_2004_CORE|WINDOWS_SERVER_2022_CORE|WINDOWS_SERVER_2022_FULL|WINDOWS_SERVER_2025_CORE|WINDOWS_SERVER_2025_FULL|WINDOWS_SERVER_20H2_CORE|LINUX',
    ],
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'taskRoleArn' => '<string>',
    'volumes' => [
        [
            'configuredAtLaunch' => true || false,
            'dockerVolumeConfiguration' => [
                'autoprovision' => true || false,
                'driver' => '<string>',
                'driverOpts' => ['<string>', ...],
                'labels' => ['<string>', ...],
                'scope' => 'task|shared',
            ],
            'efsVolumeConfiguration' => [
                'authorizationConfig' => [
                    'accessPointId' => '<string>',
                    'iam' => 'ENABLED|DISABLED',
                ],
                'fileSystemId' => '<string>', // REQUIRED
                'rootDirectory' => '<string>',
                'transitEncryption' => 'ENABLED|DISABLED',
                'transitEncryptionPort' => <integer>,
            ],
            'fsxWindowsFileServerVolumeConfiguration' => [
                'authorizationConfig' => [ // REQUIRED
                    'credentialsParameter' => '<string>', // REQUIRED
                    'domain' => '<string>', // REQUIRED
                ],
                'fileSystemId' => '<string>', // REQUIRED
                'rootDirectory' => '<string>', // REQUIRED
            ],
            'host' => [
                'sourcePath' => '<string>',
            ],
            'name' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'taskDefinition' => [
        'compatibilities' => ['<string>', ...],
        'containerDefinitions' => [
            [
                'command' => ['<string>', ...],
                'cpu' => <integer>,
                'credentialSpecs' => ['<string>', ...],
                'dependsOn' => [
                    [
                        'condition' => 'START|COMPLETE|SUCCESS|HEALTHY',
                        'containerName' => '<string>',
                    ],
                    // ...
                ],
                'disableNetworking' => true || false,
                'dnsSearchDomains' => ['<string>', ...],
                'dnsServers' => ['<string>', ...],
                'dockerLabels' => ['<string>', ...],
                'dockerSecurityOptions' => ['<string>', ...],
                'entryPoint' => ['<string>', ...],
                'environment' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'environmentFiles' => [
                    [
                        'type' => 's3',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'essential' => true || false,
                'extraHosts' => [
                    [
                        'hostname' => '<string>',
                        'ipAddress' => '<string>',
                    ],
                    // ...
                ],
                'firelensConfiguration' => [
                    'options' => ['<string>', ...],
                    'type' => 'fluentd|fluentbit',
                ],
                'healthCheck' => [
                    'command' => ['<string>', ...],
                    'interval' => <integer>,
                    'retries' => <integer>,
                    'startPeriod' => <integer>,
                    'timeout' => <integer>,
                ],
                'hostname' => '<string>',
                'image' => '<string>',
                'interactive' => true || false,
                'links' => ['<string>', ...],
                'linuxParameters' => [
                    'capabilities' => [
                        'add' => ['<string>', ...],
                        'drop' => ['<string>', ...],
                    ],
                    'devices' => [
                        [
                            'containerPath' => '<string>',
                            'hostPath' => '<string>',
                            'permissions' => ['<string>', ...],
                        ],
                        // ...
                    ],
                    'initProcessEnabled' => true || false,
                    'maxSwap' => <integer>,
                    'sharedMemorySize' => <integer>,
                    'swappiness' => <integer>,
                    'tmpfs' => [
                        [
                            'containerPath' => '<string>',
                            'mountOptions' => ['<string>', ...],
                            'size' => <integer>,
                        ],
                        // ...
                    ],
                ],
                'logConfiguration' => [
                    'logDriver' => 'json-file|syslog|journald|gelf|fluentd|awslogs|splunk|awsfirelens',
                    'options' => ['<string>', ...],
                    'secretOptions' => [
                        [
                            'name' => '<string>',
                            'valueFrom' => '<string>',
                        ],
                        // ...
                    ],
                ],
                'memory' => <integer>,
                'memoryReservation' => <integer>,
                'mountPoints' => [
                    [
                        'containerPath' => '<string>',
                        'readOnly' => true || false,
                        'sourceVolume' => '<string>',
                    ],
                    // ...
                ],
                'name' => '<string>',
                'portMappings' => [
                    [
                        'appProtocol' => 'http|http2|grpc',
                        'containerPort' => <integer>,
                        'containerPortRange' => '<string>',
                        'hostPort' => <integer>,
                        'name' => '<string>',
                        'protocol' => 'tcp|udp',
                    ],
                    // ...
                ],
                'privileged' => true || false,
                'pseudoTerminal' => true || false,
                'readonlyRootFilesystem' => true || false,
                'repositoryCredentials' => [
                    'credentialsParameter' => '<string>',
                ],
                'resourceRequirements' => [
                    [
                        'type' => 'GPU|InferenceAccelerator',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'restartPolicy' => [
                    'enabled' => true || false,
                    'ignoredExitCodes' => [<integer>, ...],
                    'restartAttemptPeriod' => <integer>,
                ],
                'secrets' => [
                    [
                        'name' => '<string>',
                        'valueFrom' => '<string>',
                    ],
                    // ...
                ],
                'startTimeout' => <integer>,
                'stopTimeout' => <integer>,
                'systemControls' => [
                    [
                        'namespace' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'ulimits' => [
                    [
                        'hardLimit' => <integer>,
                        'name' => 'core|cpu|data|fsize|locks|memlock|msgqueue|nice|nofile|nproc|rss|rtprio|rttime|sigpending|stack',
                        'softLimit' => <integer>,
                    ],
                    // ...
                ],
                'user' => '<string>',
                'versionConsistency' => 'enabled|disabled',
                'volumesFrom' => [
                    [
                        'readOnly' => true || false,
                        'sourceContainer' => '<string>',
                    ],
                    // ...
                ],
                'workingDirectory' => '<string>',
            ],
            // ...
        ],
        'cpu' => '<string>',
        'deregisteredAt' => <DateTime>,
        'enableFaultInjection' => true || false,
        'ephemeralStorage' => [
            'sizeInGiB' => <integer>,
        ],
        'executionRoleArn' => '<string>',
        'family' => '<string>',
        'inferenceAccelerators' => [
            [
                'deviceName' => '<string>',
                'deviceType' => '<string>',
            ],
            // ...
        ],
        'ipcMode' => 'host|task|none',
        'memory' => '<string>',
        'networkMode' => 'bridge|host|awsvpc|none',
        'pidMode' => 'host|task',
        'placementConstraints' => [
            [
                'expression' => '<string>',
                'type' => 'memberOf',
            ],
            // ...
        ],
        'proxyConfiguration' => [
            'containerName' => '<string>',
            'properties' => [
                [
                    'name' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'type' => 'APPMESH',
        ],
        'registeredAt' => <DateTime>,
        'registeredBy' => '<string>',
        'requiresAttributes' => [
            [
                'name' => '<string>',
                'targetId' => '<string>',
                'targetType' => 'container-instance',
                'value' => '<string>',
            ],
            // ...
        ],
        'requiresCompatibilities' => ['<string>', ...],
        'revision' => <integer>,
        'runtimePlatform' => [
            'cpuArchitecture' => 'X86_64|ARM64',
            'operatingSystemFamily' => 'WINDOWS_SERVER_2019_FULL|WINDOWS_SERVER_2019_CORE|WINDOWS_SERVER_2016_FULL|WINDOWS_SERVER_2004_CORE|WINDOWS_SERVER_2022_CORE|WINDOWS_SERVER_2022_FULL|WINDOWS_SERVER_2025_CORE|WINDOWS_SERVER_2025_FULL|WINDOWS_SERVER_20H2_CORE|LINUX',
        ],
        'status' => 'ACTIVE|INACTIVE|DELETE_IN_PROGRESS',
        'taskDefinitionArn' => '<string>',
        'taskRoleArn' => '<string>',
        'volumes' => [
            [
                'configuredAtLaunch' => true || false,
                'dockerVolumeConfiguration' => [
                    'autoprovision' => true || false,
                    'driver' => '<string>',
                    'driverOpts' => ['<string>', ...],
                    'labels' => ['<string>', ...],
                    'scope' => 'task|shared',
                ],
                'efsVolumeConfiguration' => [
                    'authorizationConfig' => [
                        'accessPointId' => '<string>',
                        'iam' => 'ENABLED|DISABLED',
                    ],
                    'fileSystemId' => '<string>',
                    'rootDirectory' => '<string>',
                    'transitEncryption' => 'ENABLED|DISABLED',
                    'transitEncryptionPort' => <integer>,
                ],
                'fsxWindowsFileServerVolumeConfiguration' => [
                    'authorizationConfig' => [
                        'credentialsParameter' => '<string>',
                        'domain' => '<string>',
                    ],
                    'fileSystemId' => '<string>',
                    'rootDirectory' => '<string>',
                ],
                'host' => [
                    'sourcePath' => '<string>',
                ],
                'name' => '<string>',
            ],
            // ...
        ],
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

Examples

Example 1: To register a task definition

This example registers a task definition to the specified family.

$result = $client->registerTaskDefinition([
    'containerDefinitions' => [
        [
            'name' => 'sleep',
            'command' => [
                'sleep',
                '360',
            ],
            'cpu' => 10,
            'essential' => 1,
            'image' => 'public.ecr.aws/docker/library/busybox:latest',
            'memory' => 10,
        ],
    ],
    'family' => 'sleep360',
    'taskRoleArn' => '',
    'volumes' => [
    ],
]);

Result syntax:

[
    'taskDefinition' => [
        'containerDefinitions' => [
            [
                'name' => 'sleep',
                'command' => [
                    'sleep',
                    '360',
                ],
                'cpu' => 10,
                'environment' => [
                ],
                'essential' => 1,
                'image' => 'public.ecr.aws/docker/library/busybox:latest',
                'memory' => 10,
                'mountPoints' => [
                ],
                'portMappings' => [
                ],
                'volumesFrom' => [
                ],
            ],
        ],
        'family' => 'sleep360',
        'revision' => 1,
        'taskDefinitionArn' => 'arn:aws:ecs:us-east-1::task-definition/sleep360:19',
        'volumes' => [
        ],
    ],
]

RunTask

$result = $client->runTask([/* ... */]);
$promise = $client->runTaskAsync([/* ... */]);

Starts a new task using the specified task definition.

You can allow Amazon ECS to place tasks for you, or you can customize how Amazon ECS places tasks using placement constraints and placement strategies. For more information, see Scheduling Tasks in the Amazon Elastic Container Service Developer Guide.

Alternatively, you can use StartTask to use your own scheduler or place tasks manually on specific container instances.

You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when creating or updating a service. For more information, see Amazon EBS volumes in the Amazon Elastic Container Service Developer Guide.

The Amazon ECS API follows an eventual consistency model. This is because of the distributed nature of the system supporting the API. This means that the result of an API command you run that affects your Amazon ECS resources might not be immediately visible to all subsequent commands you run. Keep this in mind when you carry out an API command that immediately follows a previous API command.

To manage eventual consistency, you can do the following:

• Confirm the state of the resource before you run a command to modify it. Run the DescribeTasks command using an exponential backoff algorithm to ensure that you allow enough time for the previous command to propagate through the system. To do this, run the DescribeTasks command repeatedly, starting with a couple of seconds of wait time and increasing gradually up to five minutes of wait time.

• Add wait time between subsequent commands, even if the DescribeTasks command returns an accurate response. Apply an exponential backoff algorithm starting with a couple of seconds of wait time, and increase gradually up to about five minutes of wait time.

If you get a ConflictException error, the RunTask request could not be processed due to conflicts. The provided clientToken is already in use with a different RunTask request. The resourceIds are the existing task ARNs which are already associated with the clientToken.

To fix this issue:

• Run RunTask with a unique clientToken.

• Run RunTask with the clientToken and the original set of parameters

If you get a ClientExceptionerror, the RunTask could not be processed because you use managed scaling and there is a capacity error because the quota of tasks in the PROVISIONING per cluster has been reached. For information about the service quotas, see Amazon ECS service quotas.

Parameter Syntax

$result = $client->runTask([
    'capacityProviderStrategy' => [
        [
            'base' => <integer>,
            'capacityProvider' => '<string>', // REQUIRED
            'weight' => <integer>,
        ],
        // ...
    ],
    'clientToken' => '<string>',
    'cluster' => '<string>',
    'count' => <integer>,
    'enableECSManagedTags' => true || false,
    'enableExecuteCommand' => true || false,
    'group' => '<string>',
    'launchType' => 'EC2|FARGATE|EXTERNAL',
    'networkConfiguration' => [
        'awsvpcConfiguration' => [
            'assignPublicIp' => 'ENABLED|DISABLED',
            'securityGroups' => ['<string>', ...],
            'subnets' => ['<string>', ...], // REQUIRED
        ],
    ],
    'overrides' => [
        'containerOverrides' => [
            [
                'command' => ['<string>', ...],
                'cpu' => <integer>,
                'environment' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'environmentFiles' => [
                    [
                        'type' => 's3', // REQUIRED
                        'value' => '<string>', // REQUIRED
                    ],
                    // ...
                ],
                'memory' => <integer>,
                'memoryReservation' => <integer>,
                'name' => '<string>',
                'resourceRequirements' => [
                    [
                        'type' => 'GPU|InferenceAccelerator', // REQUIRED
                        'value' => '<string>', // REQUIRED
                    ],
                    // ...
                ],
            ],
            // ...
        ],
        'cpu' => '<string>',
        'ephemeralStorage' => [
            'sizeInGiB' => <integer>, // REQUIRED
        ],
        'executionRoleArn' => '<string>',
        'inferenceAcceleratorOverrides' => [
            [
                'deviceName' => '<string>',
                'deviceType' => '<string>',
            ],
            // ...
        ],
        'memory' => '<string>',
        'taskRoleArn' => '<string>',
    ],
    'placementConstraints' => [
        [
            'expression' => '<string>',
            'type' => 'distinctInstance|memberOf',
        ],
        // ...
    ],
    'placementStrategy' => [
        [
            'field' => '<string>',
            'type' => 'random|spread|binpack',
        ],
        // ...
    ],
    'platformVersion' => '<string>',
    'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
    'referenceId' => '<string>',
    'startedBy' => '<string>',
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'taskDefinition' => '<string>', // REQUIRED
    'volumeConfigurations' => [
        [
            'managedEBSVolume' => [
                'encrypted' => true || false,
                'filesystemType' => 'ext3|ext4|xfs|ntfs',
                'iops' => <integer>,
                'kmsKeyId' => '<string>',
                'roleArn' => '<string>', // REQUIRED
                'sizeInGiB' => <integer>,
                'snapshotId' => '<string>',
                'tagSpecifications' => [
                    [
                        'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
                        'resourceType' => 'volume', // REQUIRED
                        'tags' => [
                            [
                                'key' => '<string>',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    // ...
                ],
                'terminationPolicy' => [
                    'deleteOnTermination' => true || false, // REQUIRED
                ],
                'throughput' => <integer>,
                'volumeInitializationRate' => <integer>,
                'volumeType' => '<string>',
            ],
            'name' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'failures' => [
        [
            'arn' => '<string>',
            'detail' => '<string>',
            'reason' => '<string>',
        ],
        // ...
    ],
    'tasks' => [
        [
            'attachments' => [
                [
                    'details' => [
                        [
                            'name' => '<string>',
                            'value' => '<string>',
                        ],
                        // ...
                    ],
                    'id' => '<string>',
                    'status' => '<string>',
                    'type' => '<string>',
                ],
                // ...
            ],
            'attributes' => [
                [
                    'name' => '<string>',
                    'targetId' => '<string>',
                    'targetType' => 'container-instance',
                    'value' => '<string>',
                ],
                // ...
            ],
            'availabilityZone' => '<string>',
            'capacityProviderName' => '<string>',
            'clusterArn' => '<string>',
            'connectivity' => 'CONNECTED|DISCONNECTED',
            'connectivityAt' => <DateTime>,
            'containerInstanceArn' => '<string>',
            'containers' => [
                [
                    'containerArn' => '<string>',
                    'cpu' => '<string>',
                    'exitCode' => <integer>,
                    'gpuIds' => ['<string>', ...],
                    'healthStatus' => 'HEALTHY|UNHEALTHY|UNKNOWN',
                    'image' => '<string>',
                    'imageDigest' => '<string>',
                    'lastStatus' => '<string>',
                    'managedAgents' => [
                        [
                            'lastStartedAt' => <DateTime>,
                            'lastStatus' => '<string>',
                            'name' => 'ExecuteCommandAgent',
                            'reason' => '<string>',
                        ],
                        // ...
                    ],
                    'memory' => '<string>',
                    'memoryReservation' => '<string>',
                    'name' => '<string>',
                    'networkBindings' => [
                        [
                            'bindIP' => '<string>',
                            'containerPort' => <integer>,
                            'containerPortRange' => '<string>',
                            'hostPort' => <integer>,
                            'hostPortRange' => '<string>',
                            'protocol' => 'tcp|udp',
                        ],
                        // ...
                    ],
                    'networkInterfaces' => [
                        [
                            'attachmentId' => '<string>',
                            'ipv6Address' => '<string>',
                            'privateIpv4Address' => '<string>',
                        ],
                        // ...
                    ],
                    'reason' => '<string>',
                    'runtimeId' => '<string>',
                    'taskArn' => '<string>',
                ],
                // ...
            ],
            'cpu' => '<string>',
            'createdAt' => <DateTime>,
            'desiredStatus' => '<string>',
            'enableExecuteCommand' => true || false,
            'ephemeralStorage' => [
                'sizeInGiB' => <integer>,
            ],
            'executionStoppedAt' => <DateTime>,
            'fargateEphemeralStorage' => [
                'kmsKeyId' => '<string>',
                'sizeInGiB' => <integer>,
            ],
            'group' => '<string>',
            'healthStatus' => 'HEALTHY|UNHEALTHY|UNKNOWN',
            'inferenceAccelerators' => [
                [
                    'deviceName' => '<string>',
                    'deviceType' => '<string>',
                ],
                // ...
            ],
            'lastStatus' => '<string>',
            'launchType' => 'EC2|FARGATE|EXTERNAL',
            'memory' => '<string>',
            'overrides' => [
                'containerOverrides' => [
                    [
                        'command' => ['<string>', ...],
                        'cpu' => <integer>,
                        'environment' => [
                            [
                                'name' => '<string>',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                        'environmentFiles' => [
                            [
                                'type' => 's3',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                        'memory' => <integer>,
                        'memoryReservation' => <integer>,
                        'name' => '<string>',
                        'resourceRequirements' => [
                            [
                                'type' => 'GPU|InferenceAccelerator',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    // ...
                ],
                'cpu' => '<string>',
                'ephemeralStorage' => [
                    'sizeInGiB' => <integer>,
                ],
                'executionRoleArn' => '<string>',
                'inferenceAcceleratorOverrides' => [
                    [
                        'deviceName' => '<string>',
                        'deviceType' => '<string>',
                    ],
                    // ...
                ],
                'memory' => '<string>',
                'taskRoleArn' => '<string>',
            ],
            'platformFamily' => '<string>',
            'platformVersion' => '<string>',
            'pullStartedAt' => <DateTime>,
            'pullStoppedAt' => <DateTime>,
            'startedAt' => <DateTime>,
            'startedBy' => '<string>',
            'stopCode' => 'TaskFailedToStart|EssentialContainerExited|UserInitiated|ServiceSchedulerInitiated|SpotInterruption|TerminationNotice',
            'stoppedAt' => <DateTime>,
            'stoppedReason' => '<string>',
            'stoppingAt' => <DateTime>,
            'tags' => [
                [
                    'key' => '<string>',
                    'value' => '<string>',
                ],
                // ...
            ],
            'taskArn' => '<string>',
            'taskDefinitionArn' => '<string>',
            'version' => <integer>,
        ],
        // ...
    ],
]

Result Details

Errors

ServerException:

These errors are usually caused by a server issue.

ClientException:

These errors are usually caused by a client action. This client action might be using an action or resource on behalf of a user that doesn't have permissions to use the action or resource. Or, it might be specifying an identifier that isn't valid.

InvalidParameterException:

The specified parameter isn't valid. Review the available parameters for the API request.

For more information about service event errors, see Amazon ECS service event messages.

ClusterNotFoundException:

The specified cluster wasn't found. You can view your available clusters with ListClusters. Amazon ECS clusters are Region specific.

UnsupportedFeatureException:

The specified task isn't supported in this Region.

PlatformUnknownException:

The specified platform version doesn't exist.

PlatformTaskDefinitionIncompatibilityException:

The specified platform version doesn't satisfy the required capabilities of the task definition.

AccessDeniedException:

You don't have authorization to perform the requested action.

BlockedException:

Your Amazon Web Services account was blocked. For more information, contact Amazon Web ServicesSupport.

ConflictException:

The request could not be processed because of conflict in the current state of the resource.

Examples

Example 1: To run a task on your default cluster

This example runs the specified task definition on your default cluster.

$result = $client->runTask([
    'cluster' => 'default',
    'taskDefinition' => 'sleep360:1',
]);

Result syntax:

[
    'tasks' => [
        [
            'containerInstanceArn' => 'arn:aws:ecs:us-east-1::container-instance/default/ffe3d344-77e2-476c-a4d0-bf560ad50acb',
            'containers' => [
                [
                    'name' => 'sleep',
                    'containerArn' => 'arn:aws:ecs:us-east-1::container/default/58591c8e-be29-4ddf-95aa-ee459d4c59fd',
                    'lastStatus' => 'PENDING',
                    'taskArn' => 'arn:aws:ecs:us-east-1::task/default/a9f21ea7-c9f5-44b1-b8e6-b31f50ed33c0',
                ],
            ],
            'desiredStatus' => 'RUNNING',
            'lastStatus' => 'PENDING',
            'overrides' => [
                'containerOverrides' => [
                    [
                        'name' => 'sleep',
                    ],
                ],
            ],
            'taskArn' => 'arn:aws:ecs:us-east-1::task/default/a9f21ea7-c9f5-44b1-b8e6-b31f50ed33c0',
            'taskDefinitionArn' => 'arn:aws:ecs:us-east-1::task-definition/sleep360:1',
        ],
    ],
]

StartTask

$result = $client->startTask([/* ... */]);
$promise = $client->startTaskAsync([/* ... */]);

Starts a new task from the specified task definition on the specified container instance or instances.

Alternatively, you can useRunTask to place tasks for you. For more information, see Scheduling Tasks in the Amazon Elastic Container Service Developer Guide.

You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when creating or updating a service. For more information, see Amazon EBS volumes in the Amazon Elastic Container Service Developer Guide.

Parameter Syntax

$result = $client->startTask([
    'cluster' => '<string>',
    'containerInstances' => ['<string>', ...], // REQUIRED
    'enableECSManagedTags' => true || false,
    'enableExecuteCommand' => true || false,
    'group' => '<string>',
    'networkConfiguration' => [
        'awsvpcConfiguration' => [
            'assignPublicIp' => 'ENABLED|DISABLED',
            'securityGroups' => ['<string>', ...],
            'subnets' => ['<string>', ...], // REQUIRED
        ],
    ],
    'overrides' => [
        'containerOverrides' => [
            [
                'command' => ['<string>', ...],
                'cpu' => <integer>,
                'environment' => [
                    [
                        'name' => '<string>',
                        'value' => '<string>',
                    ],
                    // ...
                ],
                'environmentFiles' => [
                    [
                        'type' => 's3', // REQUIRED
                        'value' => '<string>', // REQUIRED
                    ],
                    // ...
                ],
                'memory' => <integer>,
                'memoryReservation' => <integer>,
                'name' => '<string>',
                'resourceRequirements' => [
                    [
                        'type' => 'GPU|InferenceAccelerator', // REQUIRED
                        'value' => '<string>', // REQUIRED
                    ],
                    // ...
                ],
            ],
            // ...
        ],
        'cpu' => '<string>',
        'ephemeralStorage' => [
            'sizeInGiB' => <integer>, // REQUIRED
        ],
        'executionRoleArn' => '<string>',
        'inferenceAcceleratorOverrides' => [
            [
                'deviceName' => '<string>',
                'deviceType' => '<string>',
            ],
            // ...
        ],
        'memory' => '<string>',
        'taskRoleArn' => '<string>',
    ],
    'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
    'referenceId' => '<string>',
    'startedBy' => '<string>',
    'tags' => [
        [
            'key' => '<string>',
            'value' => '<string>',
        ],
        // ...
    ],
    'taskDefinition' => '<string>', // REQUIRED
    'volumeConfigurations' => [
        [
            'managedEBSVolume' => [
                'encrypted' => true || false,
                'filesystemType' => 'ext3|ext4|xfs|ntfs',
                'iops' => <integer>,
                'kmsKeyId' => '<string>',
                'roleArn' => '<string>', // REQUIRED
                'sizeInGiB' => <integer>,
                'snapshotId' => '<string>',
                'tagSpecifications' => [
                    [
                        'propagateTags' => 'TASK_DEFINITION|SERVICE|NONE',
                        'resourceType' => 'volume', // REQUIRED
                        'tags' => [
                            [
                                'key' => '<string>',
                                'value' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    // ...
                ],
                'terminationPolicy' => [
                    'deleteOnTermination' => true || false, // REQUIRED
                ],
                'throughput' => <integer>,
                'volumeInitializationRate' => <integer>,
                'volumeType' => '<string>',
            ],
            'name' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details