The AWS SDK for JavaScript v2 has reached end-of-support.
We recommend that you migrate to AWS SDK for JavaScript v3. For additional details and information on how to migrate, please refer to the announcement.

Class: AWS.ECS

Inherits:
AWS.Service show all
Identifier:
ecs
API Version:
2014-11-13
Defined in:
(unknown)

Overview

Constructs a service interface object. Each API operation is exposed as a function on service.

Service Description

Amazon Elastic Container Service (Amazon ECS) is a highly scalable, fast, container management service. It makes it easy to run, stop, and manage Docker containers. You can host your cluster on a serverless infrastructure that's managed by Amazon ECS by launching your services or tasks on Fargate. For more control, you can host your tasks on a cluster of Amazon Elastic Compute Cloud (Amazon EC2) or External (on-premises) instances that you manage.

Amazon ECS makes it easy to launch and stop container-based applications with simple API calls. This makes it easy to get the state of your cluster from a centralized service, and gives you access to many familiar Amazon EC2 features.

You can use Amazon ECS to schedule the placement of containers across your cluster based on your resource needs, isolation policies, and availability requirements. With Amazon ECS, you don't need to operate your own cluster management and configuration management systems. You also don't need to worry about scaling your management infrastructure.

Sending a Request Using ECS

var ecs = new AWS.ECS();
ecs.createCapacityProvider(params, function (err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Locking the API Version

In order to ensure that the ECS object uses this specific API, you can construct the object by passing the apiVersion option to the constructor:

var ecs = new AWS.ECS({apiVersion: '2014-11-13'});

You can also set the API version globally in AWS.config.apiVersions using the ecs service identifier:

AWS.config.apiVersions = {
  ecs: '2014-11-13',
  // other service API versions
};

var ecs = new AWS.ECS();

Version:

  • 2014-11-13

Waiter Resource States

This service supports a list of resource states that can be polled using the waitFor() method. The resource states are:

tasksRunning, tasksStopped, servicesStable, servicesInactive

Constructor Summary collapse

Property Summary collapse

Properties inherited from AWS.Service

apiVersions

Method Summary collapse

Methods inherited from AWS.Service

makeRequest, makeUnauthenticatedRequest, setupRequestListeners, defineService

Constructor Details

new AWS.ECS(options = {}) ⇒ Object

Constructs a service object. This object has one method for each API operation.

Examples:

Constructing a ECS object

var ecs = new AWS.ECS({apiVersion: '2014-11-13'});

Options Hash (options):

  • params (map) —

    An optional map of parameters to bind to every request sent by this service object. For more information on bound parameters, see "Working with Services" in the Getting Started Guide.

  • endpoint (String|AWS.Endpoint) —

    The endpoint URI to send requests to. The default endpoint is built from the configured region. The endpoint should be a string like 'https://{service}.{region}.amazonaws.com' or an Endpoint object.

  • accessKeyId (String) —

    your AWS access key ID.

  • secretAccessKey (String) —

    your AWS secret access key.

  • sessionToken (AWS.Credentials) —

    the optional AWS session token to sign requests with.

  • credentials (AWS.Credentials) —

    the AWS credentials to sign requests with. You can either specify this object, or specify the accessKeyId and secretAccessKey options directly.

  • credentialProvider (AWS.CredentialProviderChain) —

    the provider chain used to resolve credentials if no static credentials property is set.

  • region (String) —

    the region to send service requests to. See AWS.ECS.region for more information.

  • maxRetries (Integer) —

    the maximum amount of retries to attempt with a request. See AWS.ECS.maxRetries for more information.

  • maxRedirects (Integer) —

    the maximum amount of redirects to follow with a request. See AWS.ECS.maxRedirects for more information.

  • sslEnabled (Boolean) —

    whether to enable SSL for requests.

  • paramValidation (Boolean|map) —

    whether input parameters should be validated against the operation description before sending the request. Defaults to true. Pass a map to enable any of the following specific validation features:

    • min [Boolean] — Validates that a value meets the min constraint. This is enabled by default when paramValidation is set to true.
    • max [Boolean] — Validates that a value meets the max constraint.
    • pattern [Boolean] — Validates that a string value matches a regular expression.
    • enum [Boolean] — Validates that a string value matches one of the allowable enum values.
  • computeChecksums (Boolean) —

    whether to compute checksums for payload bodies when the service accepts it (currently supported in S3 only)

  • convertResponseTypes (Boolean) —

    whether types are converted when parsing response data. Currently only supported for JSON based services. Turning this off may improve performance on large response payloads. Defaults to true.

  • correctClockSkew (Boolean) —

    whether to apply a clock skew correction and retry requests that fail because of an skewed client clock. Defaults to false.

  • s3ForcePathStyle (Boolean) —

    whether to force path style URLs for S3 objects.

  • s3BucketEndpoint (Boolean) —

    whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint). Note that setting this configuration option requires an endpoint to be provided explicitly to the service constructor.

  • s3DisableBodySigning (Boolean) —

    whether S3 body signing should be disabled when using signature version v4. Body signing can only be disabled when using https. Defaults to true.

  • s3UsEast1RegionalEndpoint ('legacy'|'regional') —

    when region is set to 'us-east-1', whether to send s3 request to global endpoints or 'us-east-1' regional endpoints. This config is only applicable to S3 client. Defaults to legacy

  • s3UseArnRegion (Boolean) —

    whether to override the request region with the region inferred from requested resource's ARN. Only available for S3 buckets Defaults to true

  • retryDelayOptions (map) —

    A set of options to configure the retry delay on retryable errors. Currently supported options are:

    • base [Integer] — The base number of milliseconds to use in the exponential backoff for operation retries. Defaults to 100 ms for all services except DynamoDB, where it defaults to 50ms.
    • customBackoff [function] — A custom function that accepts a retry count and error and returns the amount of time to delay in milliseconds. If the result is a non-zero negative value, no further retry attempts will be made. The base option will be ignored if this option is supplied. The function is only called for retryable errors.
  • httpOptions (map) —

    A set of options to pass to the low-level HTTP request. Currently supported options are:

    • proxy [String] — the URL to proxy requests through
    • agent [http.Agent, https.Agent] — the Agent object to perform HTTP requests with. Used for connection pooling. Defaults to the global agent (http.globalAgent) for non-SSL connections. Note that for SSL connections, a special Agent object is used in order to enable peer certificate verification. This feature is only available in the Node.js environment.
    • connectTimeout [Integer] — Sets the socket to timeout after failing to establish a connection with the server after connectTimeout milliseconds. This timeout has no effect once a socket connection has been established.
    • timeout [Integer] — Sets the socket to timeout after timeout milliseconds of inactivity on the socket. Defaults to two minutes (120000).
    • xhrAsync [Boolean] — Whether the SDK will send asynchronous HTTP requests. Used in the browser environment only. Set to false to send requests synchronously. Defaults to true (async on).
    • xhrWithCredentials [Boolean] — Sets the "withCredentials" property of an XMLHttpRequest object. Used in the browser environment only. Defaults to false.
  • apiVersion (String, Date) —

    a String in YYYY-MM-DD format (or a date) that represents the latest possible API version that can be used in all services (unless overridden by apiVersions). Specify 'latest' to use the latest possible version.

  • apiVersions (map<String, String|Date>) —

    a map of service identifiers (the lowercase service class name) with the API version to use when instantiating a service. Specify 'latest' for each individual that can use the latest available version.

  • logger (#write, #log) —

    an object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests

  • systemClockOffset (Number) —

    an offset value in milliseconds to apply to all signing times. Use this to compensate for clock skew when your system may be out of sync with the service time. Note that this configuration option can only be applied to the global AWS.config object and cannot be overridden in service-specific configuration. Defaults to 0 milliseconds.

  • signatureVersion (String) —

    the signature version to sign requests with (overriding the API configuration). Possible values are: 'v2', 'v3', 'v4'.

  • signatureCache (Boolean) —

    whether the signature to sign requests with (overriding the API configuration) is cached. Only applies to the signature version 'v4'. Defaults to true.

  • dynamoDbCrc32 (Boolean) —

    whether to validate the CRC32 checksum of HTTP response bodies returned by DynamoDB. Default: true.

  • useAccelerateEndpoint (Boolean) —

    Whether to use the S3 Transfer Acceleration endpoint with the S3 service. Default: false.

  • clientSideMonitoring (Boolean) —

    whether to collect and publish this client's performance metrics of all its API requests.

  • endpointDiscoveryEnabled (Boolean|undefined) —

    whether to call operations with endpoints given by service dynamically. Setting this

  • endpointCacheSize (Number) —

    the size of the global cache storing endpoints from endpoint discovery operations. Once endpoint cache is created, updating this setting cannot change existing cache size. Defaults to 1000

  • hostPrefixEnabled (Boolean) —

    whether to marshal request parameters to the prefix of hostname. Defaults to true.

  • stsRegionalEndpoints ('legacy'|'regional') —

    whether to send sts request to global endpoints or regional endpoints. Defaults to 'legacy'.

  • useFipsEndpoint (Boolean) —

    Enables FIPS compatible endpoints. Defaults to false.

  • useDualstackEndpoint (Boolean) —

    Enables IPv6 dualstack endpoint. Defaults to false.

Property Details

endpoint ⇒ AWS.Endpoint (readwrite)

Returns an Endpoint object representing the endpoint URL for service requests.

Returns:

  • (AWS.Endpoint) —

    an Endpoint object representing the endpoint URL for service requests.

Method Details

createCapacityProvider(params = {}, callback) ⇒ AWS.Request

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.

Service Reference:

Examples:

Calling the createCapacityProvider operation

var params = {
  autoScalingGroupProvider: { /* required */
    autoScalingGroupArn: 'STRING_VALUE', /* required */
    managedDraining: ENABLED | DISABLED,
    managedScaling: {
      instanceWarmupPeriod: 'NUMBER_VALUE',
      maximumScalingStepSize: 'NUMBER_VALUE',
      minimumScalingStepSize: 'NUMBER_VALUE',
      status: ENABLED | DISABLED,
      targetCapacity: 'NUMBER_VALUE'
    },
    managedTerminationProtection: ENABLED | DISABLED
  },
  name: 'STRING_VALUE', /* required */
  tags: [
    {
      key: 'STRING_VALUE',
      value: 'STRING_VALUE'
    },
    /* more items */
  ]
};
ecs.createCapacityProvider(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {}) —
    • name — (String)

      The name of the capacity provider. Up to 255 characters are allowed. They include letters (both upper and lowercase letters), numbers, underscores (_), and hyphens (-). The name can't be prefixed with "aws", "ecs", or "fargate".

    • autoScalingGroupProvider — (map)

      The details of the Auto Scaling group for the capacity provider.

      • autoScalingGroupArn — required — (String)

        The Amazon Resource Name (ARN) that identifies the Auto Scaling group, or the Auto Scaling group name.

      • managedScaling — (map)

        The managed scaling settings for the Auto Scaling group capacity provider.

        • status — (String)

          Determines whether to use managed scaling for the capacity provider.

          Possible values include:
          • "ENABLED"
          • "DISABLED"
        • targetCapacity — (Integer)

          The target capacity utilization as a percentage for the capacity provider. The specified value must be greater than 0 and less than or equal to 100. For example, if you want the capacity provider to maintain 10% spare capacity, then that means the utilization is 90%, so use a targetCapacity of 90. The default value of 100 percent results in the Amazon EC2 instances in your Auto Scaling group being completely used.

        • minimumScalingStepSize — (Integer)

          The minimum number of Amazon EC2 instances that Amazon ECS will scale out at one time. The scale in process is not affected by this parameter If this parameter is omitted, the default value of 1 is used.

          When additional capacity is required, Amazon ECS will scale up the minimum scaling step size even if the actual demand is less than the minimum scaling step size.

          If you use a capacity provider with an Auto Scaling group configured with more than one Amazon EC2 instance type or Availability Zone, Amazon ECS will scale up by the exact minimum scaling step size value and will ignore both the maximum scaling step size as well as the capacity demand.

        • maximumScalingStepSize — (Integer)

          The maximum number of Amazon EC2 instances that Amazon ECS will scale out at one time. If this parameter is omitted, the default value of 10000 is used.

        • instanceWarmupPeriod — (Integer)

          The period of time, in seconds, after a newly launched Amazon EC2 instance can contribute to CloudWatch metrics for Auto Scaling group. If this parameter is omitted, the default value of 300 seconds is used.

      • managedTerminationProtection — (String)

        The managed termination protection setting to use for the Auto Scaling group capacity provider. This determines whether the Auto Scaling group has managed termination protection. The default is off.

        When using managed termination protection, managed scaling must also be used otherwise managed termination protection doesn't work.

        When managed termination protection is on, Amazon ECS prevents the Amazon EC2 instances in an Auto Scaling group that contain tasks from being terminated during a scale-in action. The Auto Scaling group and each instance in the Auto Scaling group must have instance protection from scale-in actions on as well. For more information, see Instance Protection in the Auto Scaling User Guide.

        When managed termination protection is off, your Amazon EC2 instances aren't protected from termination when the Auto Scaling group scales in.

        Possible values include:
        • "ENABLED"
        • "DISABLED"
      • managedDraining — (String)

        The managed draining option for the Auto Scaling group capacity provider. When you enable this, Amazon ECS manages and gracefully drains the EC2 container instances that are in the Auto Scaling group capacity provider.

        Possible values include:
        • "ENABLED"
        • "DISABLED"
    • tags — (Array<map>)

      The metadata that you apply to the capacity provider to categorize and organize them more conveniently. Each tag consists of a key and an optional value. You define both of them.

      The following basic restrictions apply to tags:

      • Maximum number of tags per resource - 50

      • For each resource, each tag key must be unique, and each tag key can have only one value.

      • Maximum key length - 128 Unicode characters in UTF-8

      • Maximum value length - 256 Unicode characters in UTF-8

      • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

      • Tag keys and values are case-sensitive.

      • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.

      • key — (String)

        One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.

      • value — (String)

        The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • capacityProvider — (map)

        The full description of the new capacity provider.

        • capacityProviderArn — (String)

          The Amazon Resource Name (ARN) that identifies the capacity provider.

        • name — (String)

          The name of the capacity provider.

        • status — (String)

          The current status of the capacity provider. Only capacity providers in an ACTIVE state can be used in a cluster. When a capacity provider is successfully deleted, it has an INACTIVE status.

          Possible values include:
          • "ACTIVE"
          • "INACTIVE"
        • autoScalingGroupProvider — (map)

          The Auto Scaling group settings for the capacity provider.

          • autoScalingGroupArn — required — (String)

            The Amazon Resource Name (ARN) that identifies the Auto Scaling group, or the Auto Scaling group name.

          • managedScaling — (map)

            The managed scaling settings for the Auto Scaling group capacity provider.

            • status — (String)

              Determines whether to use managed scaling for the capacity provider.

              Possible values include:
              • "ENABLED"
              • "DISABLED"
            • targetCapacity — (Integer)

              The target capacity utilization as a percentage for the capacity provider. The specified value must be greater than 0 and less than or equal to 100. For example, if you want the capacity provider to maintain 10% spare capacity, then that means the utilization is 90%, so use a targetCapacity of 90. The default value of 100 percent results in the Amazon EC2 instances in your Auto Scaling group being completely used.

            • minimumScalingStepSize — (Integer)

              The minimum number of Amazon EC2 instances that Amazon ECS will scale out at one time. The scale in process is not affected by this parameter If this parameter is omitted, the default value of 1 is used.

              When additional capacity is required, Amazon ECS will scale up the minimum scaling step size even if the actual demand is less than the minimum scaling step size.

              If you use a capacity provider with an Auto Scaling group configured with more than one Amazon EC2 instance type or Availability Zone, Amazon ECS will scale up by the exact minimum scaling step size value and will ignore both the maximum scaling step size as well as the capacity demand.

            • maximumScalingStepSize — (Integer)

              The maximum number of Amazon EC2 instances that Amazon ECS will scale out at one time. If this parameter is omitted, the default value of 10000 is used.

            • instanceWarmupPeriod — (Integer)

              The period of time, in seconds, after a newly launched Amazon EC2 instance can contribute to CloudWatch metrics for Auto Scaling group. If this parameter is omitted, the default value of 300 seconds is used.

          • managedTerminationProtection — (String)

            The managed termination protection setting to use for the Auto Scaling group capacity provider. This determines whether the Auto Scaling group has managed termination protection. The default is off.

            When using managed termination protection, managed scaling must also be used otherwise managed termination protection doesn't work.

            When managed termination protection is on, Amazon ECS prevents the Amazon EC2 instances in an Auto Scaling group that contain tasks from being terminated during a scale-in action. The Auto Scaling group and each instance in the Auto Scaling group must have instance protection from scale-in actions on as well. For more information, see Instance Protection in the Auto Scaling User Guide.

            When managed termination protection is off, your Amazon EC2 instances aren't protected from termination when the Auto Scaling group scales in.

            Possible values include:
            • "ENABLED"
            • "DISABLED"
          • managedDraining — (String)

            The managed draining option for the Auto Scaling group capacity provider. When you enable this, Amazon ECS manages and gracefully drains the EC2 container instances that are in the Auto Scaling group capacity provider.

            Possible values include:
            • "ENABLED"
            • "DISABLED"
        • updateStatus — (String)

          The update status of the capacity provider. The following are the possible states that is returned.

          DELETE_IN_PROGRESS

          The capacity provider is in the process of being deleted.

          DELETE_COMPLETE

          The capacity provider was successfully deleted and has an INACTIVE status.

          DELETE_FAILED

          The capacity provider can't be deleted. The update status reason provides further details about why the delete failed.

          Possible values include:
          • "DELETE_IN_PROGRESS"
          • "DELETE_COMPLETE"
          • "DELETE_FAILED"
          • "UPDATE_IN_PROGRESS"
          • "UPDATE_COMPLETE"
          • "UPDATE_FAILED"
        • updateStatusReason — (String)

          The update status reason. This provides further details about the update status for the capacity provider.

        • tags — (Array<map>)

          The metadata that you apply to the capacity provider to help you categorize and organize it. Each tag consists of a key and an optional value. You define both.

          The following basic restrictions apply to tags:

          • Maximum number of tags per resource - 50

          • For each resource, each tag key must be unique, and each tag key can have only one value.

          • Maximum key length - 128 Unicode characters in UTF-8

          • Maximum value length - 256 Unicode characters in UTF-8

          • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

          • Tag keys and values are case-sensitive.

          • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.

          • key — (String)

            One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.

          • value — (String)

            The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

createCluster(params = {}, callback) ⇒ AWS.Request

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.

Note: When you call the CreateCluster API operation, Amazon ECS attempts to create the Amazon ECS service-linked role for your account. This is so that it can manage required resources in other Amazon Web Services services on your behalf. However, if the user that makes the call doesn't have permissions to create the service-linked role, it isn't created. For more information, see Using service-linked roles for Amazon ECS in the Amazon Elastic Container Service Developer Guide.

Service Reference:

Examples:

To create a new cluster


/* This example creates a cluster in your default region. */

 var params = {
  clusterName: "my_cluster"
 };
 ecs.createCluster(params, function(err, data) {
   if (err) console.log(err, err.stack); // an error occurred
   else     console.log(data);           // successful response
   /*
   data = {
    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"
    }
   }
   */
 });

Calling the createCluster operation

var params = {
  capacityProviders: [
    'STRING_VALUE',
    /* more items */
  ],
  clusterName: 'STRING_VALUE',
  configuration: {
    executeCommandConfiguration: {
      kmsKeyId: 'STRING_VALUE',
      logConfiguration: {
        cloudWatchEncryptionEnabled: true || false,
        cloudWatchLogGroupName: 'STRING_VALUE',
        s3BucketName: 'STRING_VALUE',
        s3EncryptionEnabled: true || false,
        s3KeyPrefix: 'STRING_VALUE'
      },
      logging: NONE | DEFAULT | OVERRIDE
    },
    managedStorageConfiguration: {
      fargateEphemeralStorageKmsKeyId: 'STRING_VALUE',
      kmsKeyId: 'STRING_VALUE'
    }
  },
  defaultCapacityProviderStrategy: [
    {
      capacityProvider: 'STRING_VALUE', /* required */
      base: 'NUMBER_VALUE',
      weight: 'NUMBER_VALUE'
    },
    /* more items */
  ],
  serviceConnectDefaults: {
    namespace: 'STRING_VALUE' /* required */
  },
  settings: [
    {
      name: containerInsights,
      value: 'STRING_VALUE'
    },
    /* more items */
  ],
  tags: [
    {
      key: 'STRING_VALUE',
      value: 'STRING_VALUE'
    },
    /* more items */
  ]
};
ecs.createCluster(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {}) —
    • clusterName — (String)

      The name of your cluster. If you don't specify a name for your cluster, you create a cluster that's named default. Up to 255 letters (uppercase and lowercase), numbers, underscores, and hyphens are allowed.

    • tags — (Array<map>)

      The metadata that you apply to the cluster to help you categorize and organize them. Each tag consists of a key and an optional value. You define both.

      The following basic restrictions apply to tags:

      • Maximum number of tags per resource - 50

      • For each resource, each tag key must be unique, and each tag key can have only one value.

      • Maximum key length - 128 Unicode characters in UTF-8

      • Maximum value length - 256 Unicode characters in UTF-8

      • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

      • Tag keys and values are case-sensitive.

      • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.

      • key — (String)

        One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.

      • value — (String)

        The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).

    • settings — (Array<map>)

      The setting to use when creating a cluster. This parameter is used to turn on CloudWatch Container Insights for a cluster. If this value is specified, it overrides the containerInsights value set with PutAccountSetting or PutAccountSettingDefault.

      • name — (String)

        The name of the cluster setting. The value is containerInsights .

        Possible values include:
        • "containerInsights"
      • value — (String)

        The value to set for the cluster setting. The supported values are enabled and disabled.

        If you set name to containerInsights and value to enabled, CloudWatch Container Insights will be on for the cluster, otherwise it will be off unless the containerInsights account setting is turned on. If a cluster value is specified, it will override the containerInsights value set with PutAccountSetting or PutAccountSettingDefault.

    • configuration — (map)

      The execute command configuration for the cluster.

      • executeCommandConfiguration — (map)

        The details of the execute command configuration.

        • kmsKeyId — (String)

          Specify an Key Management Service key ID to encrypt the data between the local client and the container.

        • logging — (String)

          The log setting to use for redirecting logs for your execute command results. The following log settings are available.

          • NONE: The execute command session is not logged.

          • DEFAULT: The awslogs configuration in the task definition is used. If no logging parameter is specified, it defaults to this value. If no awslogs log driver is configured in the task definition, the output won't be logged.

          • OVERRIDE: Specify the logging details as a part of logConfiguration. If the OVERRIDE logging option is specified, the logConfiguration is required.

          Possible values include:
          • "NONE"
          • "DEFAULT"
          • "OVERRIDE"
        • logConfiguration — (map)

          The log configuration for the results of the execute command actions. The logs can be sent to CloudWatch Logs or an Amazon S3 bucket. When logging=OVERRIDE is specified, a logConfiguration must be provided.

          • cloudWatchLogGroupName — (String)

            The name of the CloudWatch log group to send logs to.

            Note: The CloudWatch log group must already be created.
          • cloudWatchEncryptionEnabled — (Boolean)

            Determines whether to use encryption on the CloudWatch logs. If not specified, encryption will be off.

          • s3BucketName — (String)

            The name of the S3 bucket to send logs to.

            Note: The S3 bucket must already be created.
          • s3EncryptionEnabled — (Boolean)

            Determines whether to use encryption on the S3 logs. If not specified, encryption is not used.

          • s3KeyPrefix — (String)

            An optional folder in the S3 bucket to place logs in.

      • managedStorageConfiguration — (map)

        The details of the managed storage configuration.

        • kmsKeyId — (String)

          Specify a Key Management Service key ID to encrypt the managed storage.

        • fargateEphemeralStorageKmsKeyId — (String)

          Specify the Key Management Service key ID for the Fargate ephemeral storage.

    • capacityProviders — (Array<String>)

      The short name of one or more capacity providers to associate with the cluster. A capacity provider must be associated with a cluster before it can be included as part of the default capacity provider strategy of the cluster or used in a capacity provider strategy when calling the CreateService or RunTask actions.

      If specifying a capacity provider that uses an Auto Scaling group, the capacity provider must be created but not associated with another cluster. New Auto Scaling group capacity providers can be created with the CreateCapacityProvider API operation.

      To use a Fargate capacity provider, specify either the FARGATE or FARGATE_SPOT capacity providers. The Fargate capacity providers are available to all accounts and only need to be associated with a cluster to be used.

      The PutCapacityProvider API operation is used to update the list of available capacity providers for a cluster after the cluster is created.

    • defaultCapacityProviderStrategy — (Array<map>)

      The capacity provider strategy to set as the default for the cluster. After a default capacity provider strategy is set for a cluster, when you call the CreateService or RunTask APIs with no capacity provider strategy or launch type specified, the default capacity provider strategy for the cluster is used.

      If a default capacity provider strategy isn't defined for a cluster when it was created, it can be defined later with the PutClusterCapacityProviders API operation.

      • capacityProvider — required — (String)

        The short name of the capacity provider.

      • weight — (Integer)

        The weight value designates the relative percentage of the total number of tasks launched that should use the specified capacity provider. The weight value is taken into consideration after the base value, if defined, is satisfied.

        If no weight value is specified, the default value of 0 is used. When multiple capacity providers are specified within a capacity provider strategy, at least one of the capacity providers must have a weight value greater than zero and any capacity providers with a weight of 0 can't be used to place tasks. If you specify multiple capacity providers in a strategy that all have a weight of 0, any RunTask or CreateService actions using the capacity provider strategy will fail.

        An example scenario for using weights is defining a strategy that contains two capacity providers and both have a weight of 1, then when the base is satisfied, the tasks will be split evenly across the two capacity providers. Using that same logic, if you specify a weight of 1 for capacityProviderA and a weight of 4 for capacityProviderB, then for every one task that's run using capacityProviderA, four tasks would use capacityProviderB.

      • base — (Integer)

        The base value designates how many tasks, at a minimum, to run on the specified capacity provider. Only one capacity provider in a capacity provider strategy can have a base defined. If no value is specified, the default value of 0 is used.

    • serviceConnectDefaults — (map)

      Use this parameter to set a default Service Connect namespace. After you set a default Service Connect namespace, any new services with Service Connect turned on that are created in the cluster are added as client services in the namespace. This setting only applies to new services that set the enabled parameter to true in the ServiceConnectConfiguration. You can set the namespace of each service individually in the ServiceConnectConfiguration to override this default parameter.

      Tasks that run in a namespace can use short names to connect to services in the namespace. Tasks can connect to services across all of the clusters in the namespace. Tasks connect through a managed proxy container that collects logs and metrics for increased visibility. Only the tasks that Amazon ECS services create are supported with Service Connect. For more information, see Service Connect in the Amazon Elastic Container Service Developer Guide.

      • namespace — required — (String)

        The namespace name or full Amazon Resource Name (ARN) of the Cloud Map namespace that's used when you create a service and don't specify a Service Connect configuration. The namespace name can include up to 1024 characters. The name is case-sensitive. The name can't include hyphens (-), tilde (~), greater than (>), less than (<), or slash (/).

        If you enter an existing namespace name or ARN, then that namespace will be used. Any namespace type is supported. The namespace must be in this account and this Amazon Web Services Region.

        If you enter a new name, a Cloud Map namespace will be created. Amazon ECS creates a Cloud Map namespace with the "API calls" method of instance discovery only. This instance discovery method is the "HTTP" namespace type in the Command Line Interface. Other types of instance discovery aren't used by Service Connect.

        If you update the cluster with an empty string "" for the namespace name, the cluster configuration for Service Connect is removed. Note that the namespace will remain in Cloud Map and must be deleted separately.

        For more information about Cloud Map, see Working with Services in the Cloud Map Developer Guide.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • cluster — (map)

        The full description of your new cluster.

        • clusterArn — (String)

          The Amazon Resource Name (ARN) that identifies the cluster. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.

        • clusterName — (String)

          A user-generated string that you use to identify your cluster.

        • configuration — (map)

          The execute command configuration for the cluster.

          • executeCommandConfiguration — (map)

            The details of the execute command configuration.

            • kmsKeyId — (String)

              Specify an Key Management Service key ID to encrypt the data between the local client and the container.

            • logging — (String)

              The log setting to use for redirecting logs for your execute command results. The following log settings are available.

              • NONE: The execute command session is not logged.

              • DEFAULT: The awslogs configuration in the task definition is used. If no logging parameter is specified, it defaults to this value. If no awslogs log driver is configured in the task definition, the output won't be logged.

              • OVERRIDE: Specify the logging details as a part of logConfiguration. If the OVERRIDE logging option is specified, the logConfiguration is required.

              Possible values include:
              • "NONE"
              • "DEFAULT"
              • "OVERRIDE"
            • logConfiguration — (map)

              The log configuration for the results of the execute command actions. The logs can be sent to CloudWatch Logs or an Amazon S3 bucket. When logging=OVERRIDE is specified, a logConfiguration must be provided.

              • cloudWatchLogGroupName — (String)

                The name of the CloudWatch log group to send logs to.

                Note: The CloudWatch log group must already be created.
              • cloudWatchEncryptionEnabled — (Boolean)

                Determines whether to use encryption on the CloudWatch logs. If not specified, encryption will be off.

              • s3BucketName — (String)

                The name of the S3 bucket to send logs to.

                Note: The S3 bucket must already be created.
              • s3EncryptionEnabled — (Boolean)

                Determines whether to use encryption on the S3 logs. If not specified, encryption is not used.

              • s3KeyPrefix — (String)

                An optional folder in the S3 bucket to place logs in.

          • managedStorageConfiguration — (map)

            The details of the managed storage configuration.

            • kmsKeyId — (String)

              Specify a Key Management Service key ID to encrypt the managed storage.

            • fargateEphemeralStorageKmsKeyId — (String)

              Specify the Key Management Service key ID for the Fargate ephemeral storage.

        • status — (String)

          The status of the cluster. The following are the possible states that are returned.

          ACTIVE

          The cluster is ready to accept tasks and if applicable you can register container instances with the cluster.

          PROVISIONING

          The cluster has capacity providers that are associated with it and the resources needed for the capacity provider are being created.

          DEPROVISIONING

          The cluster has capacity providers that are associated with it and the resources needed for the capacity provider are being deleted.

          FAILED

          The cluster has capacity providers that are associated with it and the resources needed for the capacity provider have failed to create.

          INACTIVE

          The cluster has been deleted. Clusters with an INACTIVE status may 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.

        • registeredContainerInstancesCount — (Integer)

          The number of container instances registered into the cluster. This includes container instances in both ACTIVE and DRAINING status.

        • runningTasksCount — (Integer)

          The number of tasks in the cluster that are in the RUNNING state.

        • pendingTasksCount — (Integer)

          The number of tasks in the cluster that are in the PENDING state.

        • activeServicesCount — (Integer)

          The number of services that are running on the cluster in an ACTIVE state. You can view these services with PListServices.

        • statistics — (Array<map>)

          Additional information about your clusters that are separated by launch type. They include the following:

          • runningEC2TasksCount

          • RunningFargateTasksCount

          • pendingEC2TasksCount

          • pendingFargateTasksCount

          • activeEC2ServiceCount

          • activeFargateServiceCount

          • drainingEC2ServiceCount

          • drainingFargateServiceCount

          • name — (String)

            The name of the key-value pair. For environment variables, this is the name of the environment variable.

          • value — (String)

            The value of the key-value pair. For environment variables, this is the value of the environment variable.

        • tags — (Array<map>)

          The metadata that you apply to the cluster to help you categorize and organize them. Each tag consists of a key and an optional value. You define both.

          The following basic restrictions apply to tags:

          • Maximum number of tags per resource - 50

          • For each resource, each tag key must be unique, and each tag key can have only one value.

          • Maximum key length - 128 Unicode characters in UTF-8

          • Maximum value length - 256 Unicode characters in UTF-8

          • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

          • Tag keys and values are case-sensitive.

          • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.

          • key — (String)

            One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.

          • value — (String)

            The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).

        • settings — (Array<map>)

          The settings for the cluster. This parameter indicates whether CloudWatch Container Insights is on or off for a cluster.

          • name — (String)

            The name of the cluster setting. The value is containerInsights .

            Possible values include:
            • "containerInsights"
          • value — (String)

            The value to set for the cluster setting. The supported values are enabled and disabled.

            If you set name to containerInsights and value to enabled, CloudWatch Container Insights will be on for the cluster, otherwise it will be off unless the containerInsights account setting is turned on. If a cluster value is specified, it will override the containerInsights value set with PutAccountSetting or PutAccountSettingDefault.

        • capacityProviders — (Array<String>)

          The capacity providers associated with the cluster.

        • defaultCapacityProviderStrategy — (Array<map>)

          The default capacity provider strategy for the cluster. When services or tasks are run in the cluster with no launch type or capacity provider strategy specified, the default capacity provider strategy is used.

          • capacityProvider — required — (String)

            The short name of the capacity provider.

          • weight — (Integer)

            The weight value designates the relative percentage of the total number of tasks launched that should use the specified capacity provider. The weight value is taken into consideration after the base value, if defined, is satisfied.

            If no weight value is specified, the default value of 0 is used. When multiple capacity providers are specified within a capacity provider strategy, at least one of the capacity providers must have a weight value greater than zero and any capacity providers with a weight of 0 can't be used to place tasks. If you specify multiple capacity providers in a strategy that all have a weight of 0, any RunTask or CreateService actions using the capacity provider strategy will fail.

            An example scenario for using weights is defining a strategy that contains two capacity providers and both have a weight of 1, then when the base is satisfied, the tasks will be split evenly across the two capacity providers. Using that same logic, if you specify a weight of 1 for capacityProviderA and a weight of 4 for capacityProviderB, then for every one task that's run using capacityProviderA, four tasks would use capacityProviderB.

          • base — (Integer)

            The base value designates how many tasks, at a minimum, to run on the specified capacity provider. Only one capacity provider in a capacity provider strategy can have a base defined. If no value is specified, the default value of 0 is used.

        • attachments — (Array<map>)

          The resources attached to a cluster. When using a capacity provider with a cluster, the capacity provider and associated resources are returned as cluster attachments.

          • id — (String)

            The unique identifier for the attachment.

          • type — (String)

            The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.

          • status — (String)

            The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.

          • details — (Array<map>)

            Details of the attachment.

            For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.

            For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.

            For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).

            • name — (String)

              The name of the key-value pair. For environment variables, this is the name of the environment variable.

            • value — (String)

              The value of the key-value pair. For environment variables, this is the value of the environment variable.

        • attachmentsStatus — (String)

          The status of the capacity providers associated with the cluster. The following are the states that are returned.

          UPDATE_IN_PROGRESS

          The available capacity providers for the cluster are updating.

          UPDATE_COMPLETE

          The capacity providers have successfully updated.

          UPDATE_FAILED

          The capacity provider updates failed.

        • serviceConnectDefaults — (map)

          Use this parameter to set a default Service Connect namespace. After you set a default Service Connect namespace, any new services with Service Connect turned on that are created in the cluster are added as client services in the namespace. This setting only applies to new services that set the enabled parameter to true in the ServiceConnectConfiguration. You can set the namespace of each service individually in the ServiceConnectConfiguration to override this default parameter.

          Tasks that run in a namespace can use short names to connect to services in the namespace. Tasks can connect to services across all of the clusters in the namespace. Tasks connect through a managed proxy container that collects logs and metrics for increased visibility. Only the tasks that Amazon ECS services create are supported with Service Connect. For more information, see Service Connect in the Amazon Elastic Container Service Developer Guide.

          • namespace — (String)

            The namespace name or full Amazon Resource Name (ARN) of the Cloud Map namespace. When you create a service and don't specify a Service Connect configuration, this namespace is used.

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

createService(params = {}, callback) ⇒ AWS.Request

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.

Note: On March 21, 2024, a change was made to resolve the task definition revision before authorization. When a task definition revision is not specified, authorization will occur using the latest revision of a task definition.

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.