Class: Aws::ECS::Client

Inherits:
Seahorse::Client::Base show all
Includes:
ClientStubs
Defined in:
gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb

Overview

An API client for ECS. To construct a client, you need to configure a :region and :credentials.

client = Aws::ECS::Client.new(
  region: region_name,
  credentials: credentials,
  # ...
)

For details on configuring region and credentials see the developer guide.

See #initialize for a full list of supported configuration options.

Instance Attribute Summary

Attributes inherited from Seahorse::Client::Base

#config, #handlers

API Operations collapse

Instance Method Summary collapse

Methods included from ClientStubs

#api_requests, #stub_data, #stub_responses

Methods inherited from Seahorse::Client::Base

add_plugin, api, clear_plugins, define, new, #operation_names, plugins, remove_plugin, set_api, set_plugins

Methods included from Seahorse::Client::HandlerBuilder

#handle, #handle_request, #handle_response

Constructor Details

#initialize(options) ⇒ Client

Returns a new instance of Client.

Parameters:

  • options (Hash)

Options Hash (options):

  • :credentials (required, Aws::CredentialProvider) —

    Your AWS credentials. This can be an instance of any one of the following classes:

    • Aws::Credentials - Used for configuring static, non-refreshing credentials.

    • Aws::SharedCredentials - Used for loading static credentials from a shared file, such as ~/.aws/config.

    • Aws::AssumeRoleCredentials - Used when you need to assume a role.

    • Aws::AssumeRoleWebIdentityCredentials - Used when you need to assume a role after providing credentials via the web.

    • Aws::SSOCredentials - Used for loading credentials from AWS SSO using an access token generated from aws login.

    • Aws::ProcessCredentials - Used for loading credentials from a process that outputs to stdout.

    • Aws::InstanceProfileCredentials - Used for loading credentials from an EC2 IMDS on an EC2 instance.

    • Aws::ECSCredentials - Used for loading credentials from instances running in ECS.

    • Aws::CognitoIdentityCredentials - Used for loading credentials from the Cognito Identity service.

    When :credentials are not configured directly, the following locations will be searched for credentials:

    • Aws.config[:credentials]
    • The :access_key_id, :secret_access_key, and :session_token options.
    • ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY']
    • ~/.aws/credentials
    • ~/.aws/config
    • EC2/ECS IMDS instance profile - When used by default, the timeouts are very aggressive. Construct and pass an instance of Aws::InstanceProfileCredentails or Aws::ECSCredentials to enable retries and extended timeouts. Instance profile credential fetching can be disabled by setting ENV['AWS_EC2_METADATA_DISABLED'] to true.
  • :region (required, String) —

    The AWS region to connect to. The configured :region is used to determine the service :endpoint. When not passed, a default :region is searched for in the following locations:

    • Aws.config[:region]
    • ENV['AWS_REGION']
    • ENV['AMAZON_REGION']
    • ENV['AWS_DEFAULT_REGION']
    • ~/.aws/credentials
    • ~/.aws/config
  • :access_key_id (String)
  • :active_endpoint_cache (Boolean) — default: false —

    When set to true, a thread polling for endpoints will be running in the background every 60 secs (default). Defaults to false.

  • :adaptive_retry_wait_to_fill (Boolean) — default: true —

    Used only in adaptive retry mode. When true, the request will sleep until there is sufficent client side capacity to retry the request. When false, the request will raise a RetryCapacityNotAvailableError and will not retry instead of sleeping.

  • :client_side_monitoring (Boolean) — default: false —

    When true, client-side metrics will be collected for all API requests from this client.

  • :client_side_monitoring_client_id (String) — default: "" —

    Allows you to provide an identifier for this client which will be attached to all generated client side metrics. Defaults to an empty string.

  • :client_side_monitoring_host (String) — default: "127.0.0.1" —

    Allows you to specify the DNS hostname or IPv4 or IPv6 address that the client side monitoring agent is running on, where client metrics will be published via UDP.

  • :client_side_monitoring_port (Integer) — default: 31000 —

    Required for publishing client metrics. The port that the client side monitoring agent is running on, where client metrics will be published via UDP.

  • :client_side_monitoring_publisher (Aws::ClientSideMonitoring::Publisher) — default: Aws::ClientSideMonitoring::Publisher —

    Allows you to provide a custom client-side monitoring publisher class. By default, will use the Client Side Monitoring Agent Publisher.

  • :convert_params (Boolean) — default: true —

    When true, an attempt is made to coerce request parameters into the required types.

  • :correct_clock_skew (Boolean) — default: true —

    Used only in standard and adaptive retry modes. Specifies whether to apply a clock skew correction and retry requests with skewed client clocks.

  • :defaults_mode (String) — default: "legacy" —

    See DefaultsModeConfiguration for a list of the accepted modes and the configuration defaults that are included.

  • :disable_host_prefix_injection (Boolean) — default: false —

    Set to true to disable SDK automatically adding host prefix to default service endpoint when available.

  • :endpoint (String) —

    The client endpoint is normally constructed from the :region option. You should only configure an :endpoint when connecting to test or custom endpoints. This should be a valid HTTP(S) URI.

  • :endpoint_cache_max_entries (Integer) — default: 1000 —

    Used for the maximum size limit of the LRU cache storing endpoints data for endpoint discovery enabled operations. Defaults to 1000.

  • :endpoint_cache_max_threads (Integer) — default: 10 —

    Used for the maximum threads in use for polling endpoints to be cached, defaults to 10.

  • :endpoint_cache_poll_interval (Integer) — default: 60 —

    When :endpoint_discovery and :active_endpoint_cache is enabled, Use this option to config the time interval in seconds for making requests fetching endpoints information. Defaults to 60 sec.

  • :endpoint_discovery (Boolean) — default: false —

    When set to true, endpoint discovery will be enabled for operations when available.

  • :log_formatter (Aws::Log::Formatter) — default: Aws::Log::Formatter.default —

    The log formatter.

  • :log_level (Symbol) — default: :info —

    The log level to send messages to the :logger at.

  • :logger (Logger) —

    The Logger instance to send log messages to. If this option is not set, logging will be disabled.

  • :max_attempts (Integer) — default: 3 —

    An integer representing the maximum number attempts that will be made for a single request, including the initial attempt. For example, setting this value to 5 will result in a request being retried up to 4 times. Used in standard and adaptive retry modes.

  • :profile (String) — default: "default" —

    Used when loading credentials from the shared credentials file at HOME/.aws/credentials. When not specified, 'default' is used.

  • :retry_backoff (Proc) —

    A proc or lambda used for backoff. Defaults to 2**retries * retry_base_delay. This option is only used in the legacy retry mode.

  • :retry_base_delay (Float) — default: 0.3 —

    The base delay in seconds used by the default backoff function. This option is only used in the legacy retry mode.

  • :retry_jitter (Symbol) — default: :none —

    A delay randomiser function used by the default backoff function. Some predefined functions can be referenced by name - :none, :equal, :full, otherwise a Proc that takes and returns a number. This option is only used in the legacy retry mode.

    @see https://www.awsarchitectureblog.com/2015/03/backoff.html

  • :retry_limit (Integer) — default: 3 —

    The maximum number of times to retry failed requests. Only ~ 500 level server errors and certain ~ 400 level client errors are retried. Generally, these are throttling errors, data checksum errors, networking errors, timeout errors, auth errors, endpoint discovery, and errors from expired credentials. This option is only used in the legacy retry mode.

  • :retry_max_delay (Integer) — default: 0 —

    The maximum number of seconds to delay between retries (0 for no limit) used by the default backoff function. This option is only used in the legacy retry mode.

  • :retry_mode (String) — default: "legacy" —

    Specifies which retry algorithm to use. Values are:

    • legacy - The pre-existing retry behavior. This is default value if no retry mode is provided.

    • standard - A standardized set of retry rules across the AWS SDKs. This includes support for retry quotas, which limit the number of unsuccessful retries a client can make.

    • adaptive - An experimental retry mode that includes all the functionality of standard mode along with automatic client side throttling. This is a provisional mode that may change behavior in the future.

  • :secret_access_key (String)
  • :session_token (String)
  • :simple_json (Boolean) — default: false —

    Disables request parameter conversion, validation, and formatting. Also disable response data type conversions. This option is useful when you want to ensure the highest level of performance by avoiding overhead of walking request parameters and response data structures.

    When :simple_json is enabled, the request parameters hash must be formatted exactly as the DynamoDB API expects.

  • :stub_responses (Boolean) — default: false —

    Causes the client to return stubbed responses. By default fake responses are generated and returned. You can specify the response data to return or errors to raise by calling ClientStubs#stub_responses. See ClientStubs for more information.

    Please note When response stubbing is enabled, no HTTP requests are made, and retries are disabled.

  • :use_dualstack_endpoint (Boolean) —

    When set to true, dualstack enabled endpoints (with .aws TLD) will be used if available.

  • :use_fips_endpoint (Boolean) —

    When set to true, fips compatible endpoints will be used if available. When a fips region is used, the region is normalized and this config is set to true.

  • :validate_params (Boolean) — default: true —

    When true, request parameters are validated before sending the request.

  • :http_proxy (URI::HTTP, String) —

    A proxy to send requests through. Formatted like 'http://proxy.com:123'.

  • :http_open_timeout (Float) — default: 15 —

    The number of seconds to wait when opening a HTTP session before raising a Timeout::Error.

  • :http_read_timeout (Float) — default: 60 —

    The default number of seconds to wait for response data. This value can safely be set per-request on the session.

  • :http_idle_timeout (Float) — default: 5 —

    The number of seconds a connection is allowed to sit idle before it is considered stale. Stale connections are closed and removed from the pool before making a request.

  • :http_continue_timeout (Float) — default: 1 —

    The number of seconds to wait for a 100-continue response before sending the request body. This option has no effect unless the request has "Expect" header set to "100-continue". Defaults to nil which disables this behaviour. This value can safely be set per request on the session.

  • :ssl_timeout (Float) — default: nil —

    Sets the SSL timeout in seconds.

  • :http_wire_trace (Boolean) — default: false —

    When true, HTTP debug output will be sent to the :logger.

  • :ssl_verify_peer (Boolean) — default: true —

    When true, SSL peer certificates are verified when establishing a connection.

  • :ssl_ca_bundle (String) —

    Full path to the SSL certificate authority bundle file that should be used when verifying peer certificates. If you do not pass :ssl_ca_bundle or :ssl_ca_directory the the system default will be used if available.

  • :ssl_ca_directory (String) —

    Full path of the directory that contains the unbundled SSL certificate authority files for verifying peer certificates. If you do not pass :ssl_ca_bundle or :ssl_ca_directory the the system default will be used if available.



358
359
360
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 358

def initialize(*args)
  super
end

Instance Method Details

#create_capacity_provider(params = {}) ⇒ Types::CreateCapacityProviderResponse

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.

Examples:

Request syntax with placeholder values


resp = client.create_capacity_provider({
  name: "String", # required
  auto_scaling_group_provider: { # required
    auto_scaling_group_arn: "String", # required
    managed_scaling: {
      status: "ENABLED", # accepts ENABLED, DISABLED
      target_capacity: 1,
      minimum_scaling_step_size: 1,
      maximum_scaling_step_size: 1,
      instance_warmup_period: 1,
    },
    managed_termination_protection: "ENABLED", # accepts ENABLED, DISABLED
  },
  tags: [
    {
      key: "TagKey",
      value: "TagValue",
    },
  ],
})

Response structure


resp.capacity_provider.capacity_provider_arn #=> String
resp.capacity_provider.name #=> String
resp.capacity_provider.status #=> String, one of "ACTIVE", "INACTIVE"
resp.capacity_provider.auto_scaling_group_provider.auto_scaling_group_arn #=> String
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.status #=> String, one of "ENABLED", "DISABLED"
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.target_capacity #=> Integer
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.minimum_scaling_step_size #=> Integer
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.maximum_scaling_step_size #=> Integer
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.instance_warmup_period #=> Integer
resp.capacity_provider.auto_scaling_group_provider.managed_termination_protection #=> String, one of "ENABLED", "DISABLED"
resp.capacity_provider.update_status #=> String, one of "DELETE_IN_PROGRESS", "DELETE_COMPLETE", "DELETE_FAILED", "UPDATE_IN_PROGRESS", "UPDATE_COMPLETE", "UPDATE_FAILED"
resp.capacity_provider.update_status_reason #=> String
resp.capacity_provider.tags #=> Array
resp.capacity_provider.tags[0].key #=> String
resp.capacity_provider.tags[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :name (required, 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".

  • :auto_scaling_group_provider (required, Types::AutoScalingGroupProvider) —

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

  • :tags (Array<Types::Tag>) —

    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.

Returns:

See Also:



461
462
463
464
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 461

def create_capacity_provider(params = {}, options = {})
  req = build_request(:create_capacity_provider, params)
  req.send_request(options)
end

#create_cluster(params = {}) ⇒ Types::CreateClusterResponse

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 with the CreateCluster action.

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 IAM 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.

Examples:

Example: To create a new cluster


# This example creates a cluster in your default region.

resp = client.create_cluster({
  cluster_name: "my_cluster", 
})

resp.to_h outputs the following:
{
  cluster: {
    active_services_count: 0, 
    cluster_arn: "arn:aws:ecs:us-east-1:012345678910:cluster/my_cluster", 
    cluster_name: "my_cluster", 
    pending_tasks_count: 0, 
    registered_container_instances_count: 0, 
    running_tasks_count: 0, 
    status: "ACTIVE", 
  }, 
}

Request syntax with placeholder values


resp = client.create_cluster({
  cluster_name: "String",
  tags: [
    {
      key: "TagKey",
      value: "TagValue",
    },
  ],
  settings: [
    {
      name: "containerInsights", # accepts containerInsights
      value: "String",
    },
  ],
  configuration: {
    execute_command_configuration: {
      kms_key_id: "String",
      logging: "NONE", # accepts NONE, DEFAULT, OVERRIDE
      log_configuration: {
        cloud_watch_log_group_name: "String",
        cloud_watch_encryption_enabled: false,
        s3_bucket_name: "String",
        s3_encryption_enabled: false,
        s3_key_prefix: "String",
      },
    },
  },
  capacity_providers: ["String"],
  default_capacity_provider_strategy: [
    {
      capacity_provider: "String", # required
      weight: 1,
      base: 1,
    },
  ],
})

Response structure


resp.cluster.cluster_arn #=> String
resp.cluster.cluster_name #=> String
resp.cluster.configuration.execute_command_configuration.kms_key_id #=> String
resp.cluster.configuration.execute_command_configuration.logging #=> String, one of "NONE", "DEFAULT", "OVERRIDE"
resp.cluster.configuration.execute_command_configuration.log_configuration.cloud_watch_log_group_name #=> String
resp.cluster.configuration.execute_command_configuration.log_configuration.cloud_watch_encryption_enabled #=> Boolean
resp.cluster.configuration.execute_command_configuration.log_configuration.s3_bucket_name #=> String
resp.cluster.configuration.execute_command_configuration.log_configuration.s3_encryption_enabled #=> Boolean
resp.cluster.configuration.execute_command_configuration.log_configuration.s3_key_prefix #=> String
resp.cluster.status #=> String
resp.cluster.registered_container_instances_count #=> Integer
resp.cluster.running_tasks_count #=> Integer
resp.cluster.pending_tasks_count #=> Integer
resp.cluster.active_services_count #=> Integer
resp.cluster.statistics #=> Array
resp.cluster.statistics[0].name #=> String
resp.cluster.statistics[0].value #=> String
resp.cluster.tags #=> Array
resp.cluster.tags[0].key #=> String
resp.cluster.tags[0].value #=> String
resp.cluster.settings #=> Array
resp.cluster.settings[0].name #=> String, one of "containerInsights"
resp.cluster.settings[0].value #=> String
resp.cluster.capacity_providers #=> Array
resp.cluster.capacity_providers[0] #=> String
resp.cluster.default_capacity_provider_strategy #=> Array
resp.cluster.default_capacity_provider_strategy[0].capacity_provider #=> String
resp.cluster.default_capacity_provider_strategy[0].weight #=> Integer
resp.cluster.default_capacity_provider_strategy[0].base #=> Integer
resp.cluster.attachments #=> Array
resp.cluster.attachments[0].id #=> String
resp.cluster.attachments[0].type #=> String
resp.cluster.attachments[0].status #=> String
resp.cluster.attachments[0].details #=> Array
resp.cluster.attachments[0].details[0].name #=> String
resp.cluster.attachments[0].details[0].value #=> String
resp.cluster.attachments_status #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster_name (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<Types::Tag>) —

    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.

  • :settings (Array<Types::ClusterSetting>) —

    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.

  • :configuration (Types::ClusterConfiguration) —

    The execute command configuration for the cluster.

  • :capacity_providers (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 PutClusterCapacityProviders API operation is used to update the list of available capacity providers for a cluster after the cluster is created.

  • :default_capacity_provider_strategy (Array<Types::CapacityProviderStrategyItem>) —

    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 RunTask or CreateService 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.

Returns:

See Also:



672
673
674
675
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 672

def create_cluster(params = {}, options = {})
  req = build_request(:create_cluster, params)
  req.send_request(options)
end

#create_service(params = {}) ⇒ Types::CreateServiceResponse

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, see the UpdateService action.

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.

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. This is done with an UpdateService operation. 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 operation. 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 in your cluster using the following logic:

  • Determine which of the container instances in your cluster can support the task definition of your service. For example, they have the required CPU, memory, ports, and container instance attributes.

  • By default, the service scheduler attempts to balance tasks across Availability Zones in this manner. This is the case even if you can choose a different placement strategy with the placementStrategy parameter.

    • Sort the valid container instances, giving priority to instances that have the fewest number of running tasks for this service in their respective Availability Zone. For example, if zone A has one running service task and zones B and C each have zero, valid container instances in either zone B or C are considered optimal for placement.

    • Place the new service task on a valid container instance in an optimal Availability Zone based on the previous steps, favoring container instances with the fewest number of running tasks for this service.

Examples:

Example: 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.

resp = client.create_service({
  desired_count: 10, 
  service_name: "ecs-simple-service", 
  task_definition: "hello_world", 
})

resp.to_h outputs the following:
{
  service: {
    cluster_arn: "arn:aws:ecs:us-east-1:012345678910:cluster/default", 
    created_at: Time.parse("2016-08-29T16:13:47.298Z"), 
    deployment_configuration: {
      maximum_percent: 200, 
      minimum_healthy_percent: 100, 
    }, 
    deployments: [
      {
        created_at: Time.parse("2016-08-29T16:13:47.298Z"), 
        desired_count: 10, 
        id: "ecs-svc/9223370564342348388", 
        pending_count: 0, 
        running_count: 0, 
        status: "PRIMARY", 
        task_definition: "arn:aws:ecs:us-east-1:012345678910:task-definition/hello_world:6", 
        updated_at: Time.parse("2016-08-29T16:13:47.298Z"), 
      }, 
      {
        created_at: Time.parse("2016-08-29T15:52:44.481Z"), 
        desired_count: 0, 
        id: "ecs-svc/9223370564343611322", 
        pending_count: 0, 
        running_count: 0, 
        status: "ACTIVE", 
        task_definition: "arn:aws:ecs:us-east-1:012345678910:task-definition/hello_world:6", 
        updated_at: Time.parse("2016-08-29T16:11:38.941Z"), 
      }, 
    ], 
    desired_count: 10, 
    events: [
    ], 
    load_balancers: [
    ], 
    pending_count: 0, 
    running_count: 0, 
    service_arn: "arn:aws:ecs:us-east-1:012345678910:service/ecs-simple-service", 
    service_name: "ecs-simple-service", 
    status: "ACTIVE", 
    task_definition: "arn:aws:ecs:us-east-1:012345678910:task-definition/hello_world:6", 
  }, 
}

Example: 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.

resp = client.create_service({
  desired_count: 10, 
  load_balancers: [
    {
      container_name: "simple-app", 
      container_port: 80, 
      load_balancer_name: "EC2Contai-EcsElast-15DCDAURT3ZO2", 
    }, 
  ], 
  role: "ecsServiceRole", 
  service_name: "ecs-simple-service-elb", 
  task_definition: "console-sample-app-static", 
})

resp.to_h outputs the following:
{
  service: {
    cluster_arn: "arn:aws:ecs:us-east-1:012345678910:cluster/default", 
    created_at: Time.parse("2016-08-29T16:02:54.884Z"), 
    deployment_configuration: {
      maximum_percent: 200, 
      minimum_healthy_percent: 100, 
    }, 
    deployments: [
      {
        created_at: Time.parse("2016-08-29T16:02:54.884Z"), 
        desired_count: 10, 
        id: "ecs-svc/9223370564343000923", 
        pending_count: 0, 
        running_count: 0, 
        status: "PRIMARY", 
        task_definition: "arn:aws:ecs:us-east-1:012345678910:task-definition/console-sample-app-static:6", 
        updated_at: Time.parse("2016-08-29T16:02:54.884Z"), 
      }, 
    ], 
    desired_count: 10, 
    events: [
    ], 
    load_balancers: [
      {
        container_name: "simple-app", 
        container_port: 80, 
        load_balancer_name: "EC2Contai-EcsElast-15DCDAURT3ZO2", 
      }, 
    ], 
    pending_count: 0, 
    role_arn: "arn:aws:iam::012345678910:role/ecsServiceRole", 
    running_count: 0, 
    service_arn: "arn:aws:ecs:us-east-1:012345678910:service/ecs-simple-service-elb", 
    service_name: "ecs-simple-service-elb", 
    status: "ACTIVE", 
    task_definition: "arn:aws:ecs:us-east-1:012345678910:task-definition/console-sample-app-static:6", 
  }, 
}

Request syntax with placeholder values


resp = client.create_service({
  cluster: "String",
  service_name: "String", # required
  task_definition: "String",
  load_balancers: [
    {
      target_group_arn: "String",
      load_balancer_name: "String",
      container_name: "String",
      container_port: 1,
    },
  ],
  service_registries: [
    {
      registry_arn: "String",
      port: 1,
      container_name: "String",
      container_port: 1,
    },
  ],
  desired_count: 1,
  client_token: "String",
  launch_type: "EC2", # accepts EC2, FARGATE, EXTERNAL
  capacity_provider_strategy: [
    {
      capacity_provider: "String", # required
      weight: 1,
      base: 1,
    },
  ],
  platform_version: "String",
  role: "String",
  deployment_configuration: {
    deployment_circuit_breaker: {
      enable: false, # required
      rollback: false, # required
    },
    maximum_percent: 1,
    minimum_healthy_percent: 1,
  },
  placement_constraints: [
    {
      type: "distinctInstance", # accepts distinctInstance, memberOf
      expression: "String",
    },
  ],
  placement_strategy: [
    {
      type: "random", # accepts random, spread, binpack
      field: "String",
    },
  ],
  network_configuration: {
    awsvpc_configuration: {
      subnets: ["String"], # required
      security_groups: ["String"],
      assign_public_ip: "ENABLED", # accepts ENABLED, DISABLED
    },
  },
  health_check_grace_period_seconds: 1,
  scheduling_strategy: "REPLICA", # accepts REPLICA, DAEMON
  deployment_controller: {
    type: "ECS", # required, accepts ECS, CODE_DEPLOY, EXTERNAL
  },
  tags: [
    {
      key: "TagKey",
      value: "TagValue",
    },
  ],
  enable_ecs_managed_tags: false,
  propagate_tags: "TASK_DEFINITION", # accepts TASK_DEFINITION, SERVICE, NONE
  enable_execute_command: false,
})

Response structure


resp.service.service_arn #=> String
resp.service.service_name #=> String
resp.service.cluster_arn #=> String
resp.service.load_balancers #=> Array
resp.service.load_balancers[0].target_group_arn #=> String
resp.service.load_balancers[0].load_balancer_name #=> String
resp.service.load_balancers[0].container_name #=> String
resp.service.load_balancers[0].container_port #=> Integer
resp.service.service_registries #=> Array
resp.service.service_registries[0].registry_arn #=> String
resp.service.service_registries[0].port #=> Integer
resp.service.service_registries[0].container_name #=> String
resp.service.service_registries[0].container_port #=> Integer
resp.service.status #=> String
resp.service.desired_count #=> Integer
resp.service.running_count #=> Integer
resp.service.pending_count #=> Integer
resp.service.launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.service.capacity_provider_strategy #=> Array
resp.service.capacity_provider_strategy[0].capacity_provider #=> String
resp.service.capacity_provider_strategy[0].weight #=> Integer
resp.service.capacity_provider_strategy[0].base #=> Integer
resp.service.platform_version #=> String
resp.service.platform_family #=> String
resp.service.task_definition #=> String
resp.service.deployment_configuration.deployment_circuit_breaker.enable #=> Boolean
resp.service.deployment_configuration.deployment_circuit_breaker.rollback #=> Boolean
resp.service.deployment_configuration.maximum_percent #=> Integer
resp.service.deployment_configuration.minimum_healthy_percent #=> Integer
resp.service.task_sets #=> Array
resp.service.task_sets[0].id #=> String
resp.service.task_sets[0].task_set_arn #=> String
resp.service.task_sets[0].service_arn #=> String
resp.service.task_sets[0].cluster_arn #=> String
resp.service.task_sets[0].started_by #=> String
resp.service.task_sets[0].external_id #=> String
resp.service.task_sets[0].status #=> String
resp.service.task_sets[0].task_definition #=> String
resp.service.task_sets[0].computed_desired_count #=> Integer
resp.service.task_sets[0].pending_count #=> Integer
resp.service.task_sets[0].running_count #=> Integer
resp.service.task_sets[0].created_at #=> Time
resp.service.task_sets[0].updated_at #=> Time
resp.service.task_sets[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.service.task_sets[0].capacity_provider_strategy #=> Array
resp.service.task_sets[0].capacity_provider_strategy[0].capacity_provider #=> String
resp.service.task_sets[0].capacity_provider_strategy[0].weight #=> Integer
resp.service.task_sets[0].capacity_provider_strategy[0].base #=> Integer
resp.service.task_sets[0].platform_version #=> String
resp.service.task_sets[0].platform_family #=> String
resp.service.task_sets[0].network_configuration.awsvpc_configuration.subnets #=> Array
resp.service.task_sets[0].network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.service.task_sets[0].network_configuration.awsvpc_configuration.security_groups #=> Array
resp.service.task_sets[0].network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.service.task_sets[0].network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.service.task_sets[0].load_balancers #=> Array
resp.service.task_sets[0].load_balancers[0].target_group_arn #=> String
resp.service.task_sets[0].load_balancers[0].load_balancer_name #=> String
resp.service.task_sets[0].load_balancers[0].container_name #=> String
resp.service.task_sets[0].load_balancers[0].container_port #=> Integer
resp.service.task_sets[0].service_registries #=> Array
resp.service.task_sets[0].service_registries[0].registry_arn #=> String
resp.service.task_sets[0].service_registries[0].port #=> Integer
resp.service.task_sets[0].service_registries[0].container_name #=> String
resp.service.task_sets[0].service_registries[0].container_port #=> Integer
resp.service.task_sets[0].scale.value #=> Float
resp.service.task_sets[0].scale.unit #=> String, one of "PERCENT"
resp.service.task_sets[0].stability_status #=> String, one of "STEADY_STATE", "STABILIZING"
resp.service.task_sets[0].stability_status_at #=> Time
resp.service.task_sets[0].tags #=> Array
resp.service.task_sets[0].tags[0].key #=> String
resp.service.task_sets[0].tags[0].value #=> String
resp.service.deployments #=> Array
resp.service.deployments[0].id #=> String
resp.service.deployments[0].status #=> String
resp.service.deployments[0].task_definition #=> String
resp.service.deployments[0].desired_count #=> Integer
resp.service.deployments[0].pending_count #=> Integer
resp.service.deployments[0].running_count #=> Integer
resp.service.deployments[0].failed_tasks #=> Integer
resp.service.deployments[0].created_at #=> Time
resp.service.deployments[0].updated_at #=> Time
resp.service.deployments[0].capacity_provider_strategy #=> Array
resp.service.deployments[0].capacity_provider_strategy[0].capacity_provider #=> String
resp.service.deployments[0].capacity_provider_strategy[0].weight #=> Integer
resp.service.deployments[0].capacity_provider_strategy[0].base #=> Integer
resp.service.deployments[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.service.deployments[0].platform_version #=> String
resp.service.deployments[0].platform_family #=> String
resp.service.deployments[0].network_configuration.awsvpc_configuration.subnets #=> Array
resp.service.deployments[0].network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.service.deployments[0].network_configuration.awsvpc_configuration.security_groups #=> Array
resp.service.deployments[0].network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.service.deployments[0].network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.service.deployments[0].rollout_state #=> String, one of "COMPLETED", "FAILED", "IN_PROGRESS"
resp.service.deployments[0].rollout_state_reason #=> String
resp.service.role_arn #=> String
resp.service.events #=> Array
resp.service.events[0].id #=> String
resp.service.events[0].created_at #=> Time
resp.service.events[0].message #=> String
resp.service.created_at #=> Time
resp.service.placement_constraints #=> Array
resp.service.placement_constraints[0].type #=> String, one of "distinctInstance", "memberOf"
resp.service.placement_constraints[0].expression #=> String
resp.service.placement_strategy #=> Array
resp.service.placement_strategy[0].type #=> String, one of "random", "spread", "binpack"
resp.service.placement_strategy[0].field #=> String
resp.service.network_configuration.awsvpc_configuration.subnets #=> Array
resp.service.network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.service.network_configuration.awsvpc_configuration.security_groups #=> Array
resp.service.network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.service.network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.service.health_check_grace_period_seconds #=> Integer
resp.service.scheduling_strategy #=> String, one of "REPLICA", "DAEMON"
resp.service.deployment_controller.type #=> String, one of "ECS", "CODE_DEPLOY", "EXTERNAL"
resp.service.tags #=> Array
resp.service.tags[0].key #=> String
resp.service.tags[0].value #=> String
resp.service.created_by #=> String
resp.service.enable_ecs_managed_tags #=> Boolean
resp.service.propagate_tags #=> String, one of "TASK_DEFINITION", "SERVICE", "NONE"
resp.service.enable_execute_command #=> Boolean

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that you run your service on. If you do not specify a cluster, the default cluster is assumed.

  • :service_name (required, String) —

    The name of your service. Up to 255 letters (uppercase and lowercase), numbers, underscores, and hyphens are allowed. Service names must be unique within a cluster, but you can have similarly named services in multiple clusters within a Region or across multiple Regions.

  • :task_definition (String) —

    The family and revision (family:revision) or full ARN of the task definition to run in your service. If a revision isn't specified, the latest ACTIVE revision is used.

    A task definition must be specified if the service uses either the ECS or CODE_DEPLOY deployment controllers.

  • :load_balancers (Array<Types::LoadBalancer>) —

    A load balancer object representing the load balancers to use with your service. For more information, see Service load balancing in the Amazon Elastic Container Service Developer Guide.

    If the service uses the rolling update (ECS) deployment controller and using either an Application Load Balancer or Network Load Balancer, you must specify one or more target group ARNs to attach to the service. The service-linked role is required for services that use multiple target groups. For more information, see Using service-linked roles for Amazon ECS in the Amazon Elastic Container Service Developer Guide.

    If the service uses the CODE_DEPLOY deployment controller, the service is required to use either an Application Load Balancer or Network Load Balancer. When creating an CodeDeploy deployment group, you specify two target groups (referred to as a targetGroupPair). During a deployment, CodeDeploy determines which task set in your service has the status PRIMARY, and it associates one target group with it. Then, it also associates the other target group with the replacement task set. The load balancer can also have up to two listeners: a required listener for production traffic and an optional listener that you can use to perform validation tests with Lambda functions before routing production traffic to it.

    If you use the CODE_DEPLOY deployment controller, these values can be changed when updating the service.

    For Application Load Balancers and Network Load Balancers, this object must contain the load balancer target group ARN, the container name, and the container port to access from the load balancer. The container name must be as it appears in a container definition. The load balancer name parameter must be omitted. When a task from this service is placed on a container instance, the container instance and port combination is registered as a target in the target group that's specified here.

    For Classic Load Balancers, this object must contain the load balancer name, the container name , and the container port to access from the load balancer. The container name must be as it appears in a container definition. The target group ARN parameter must be omitted. When a task from this service is placed on a container instance, the container instance is registered with the load balancer that's specified here.

    Services with tasks that use the awsvpc network mode (for example, those with the Fargate launch type) only support Application Load Balancers and Network Load Balancers. Classic Load Balancers aren't supported. Also, when you create any target groups for these services, you must choose ip as the target type, not instance. This is because tasks that use the awsvpc network mode are associated with an elastic network interface, not an Amazon EC2 instance.

  • :service_registries (Array<Types::ServiceRegistry>) —

    The details of the service discovery registry to associate with this service. For more information, see Service discovery.

    Each service may be associated with one service registry. Multiple service registries for each service isn't supported.

  • :desired_count (Integer) —

    The number of instantiations of the specified task definition to place and keep running on your cluster.

    This is required if schedulingStrategy is REPLICA or isn't specified. If schedulingStrategy is DAEMON then this isn't required.

  • :client_token (String) —

    An identifier that you provide to ensure the idempotency of the request. It must be unique and is case sensitive. Up to 32 ASCII characters are allowed.

  • :launch_type (String) —

    The infrastructure that you run your service on. For more information, see Amazon ECS launch types in the Amazon Elastic Container Service Developer Guide.

    The FARGATE launch type runs your tasks on Fargate On-Demand infrastructure.

    Fargate Spot infrastructure is available for use but a capacity provider strategy must be used. For more information, see Fargate capacity providers in the Amazon ECS User Guide for Fargate.

    The EC2 launch type runs your tasks on Amazon EC2 instances registered to your cluster.

    The EXTERNAL launch type runs your tasks on your on-premises server or virtual machine (VM) capacity registered to your cluster.

    A service can use either a launch type or a capacity provider strategy. If a launchType is specified, the capacityProviderStrategy parameter must be omitted.

  • :capacity_provider_strategy (Array<Types::CapacityProviderStrategyItem>) —

    The capacity provider strategy to use for the service.

    If a capacityProviderStrategy is specified, the launchType parameter must be omitted. If no capacityProviderStrategy or launchType is specified, the defaultCapacityProviderStrategy for the cluster is used.

    A capacity provider strategy may contain a maximum of 6 capacity providers.

  • :platform_version (String) —

    The platform version that your tasks in the service are running on. A platform version is specified only for tasks using the Fargate launch type. If one isn't specified, the LATEST platform version is used. For more information, see Fargate platform versions in the Amazon Elastic Container Service Developer Guide.

  • :role (String) —

    The name or full Amazon Resource Name (ARN) of the IAM role that allows Amazon ECS to make calls to your load balancer on your behalf. This parameter is only permitted if you are using a load balancer with your service and your task definition doesn't use the awsvpc network mode. If you specify the role parameter, you must also specify a load balancer object with the loadBalancers parameter.

    If your account has already created the Amazon ECS service-linked role, that role is used for your service unless you specify a role here. The service-linked role is required if your task definition uses the awsvpc network mode or if the service is configured to use service discovery, an external deployment controller, multiple target groups, or Elastic Inference accelerators in which case you don't specify a role here. For more information, see Using service-linked roles for Amazon ECS in the Amazon Elastic Container Service Developer Guide.

    If your specified role has a path other than /, then you must either specify the full role ARN (this is recommended) or prefix the role name with the path. For example, if a role with the name bar has a path of /foo/ then you would specify /foo/bar as the role name. For more information, see Friendly names and paths in the IAM User Guide.

  • :deployment_configuration (Types::DeploymentConfiguration) —

    Optional deployment parameters that control how many tasks run during the deployment and the ordering of stopping and starting tasks.

  • :placement_constraints (Array<Types::PlacementConstraint>) —

    An array of placement constraint objects to use for tasks in your service. You can specify a maximum of 10 constraints for each task. This limit includes constraints in the task definition and those specified at runtime.

  • :placement_strategy (Array<Types::PlacementStrategy>) —

    The placement strategy objects to use for tasks in your service. You can specify a maximum of 5 strategy rules for each service.

  • :network_configuration (Types::NetworkConfiguration) —

    The network configuration for the service. This parameter is required for task definitions that use the awsvpc network mode to receive their own elastic network interface, and it isn't supported for other network modes. For more information, see Task networking in the Amazon Elastic Container Service Developer Guide.

  • :health_check_grace_period_seconds (Integer) —

    The period of time, in seconds, that the Amazon ECS service scheduler ignores unhealthy Elastic Load Balancing target health checks after a task has first started. This is only used when your service is configured to use a load balancer. If your service has a load balancer defined and you don't specify a health check grace period value, the default value of 0 is used.

    If you do not use an Elastic Load Balancing, we recomend that you use the startPeriod in the task definition healtch check parameters. For more information, see Health check.

    If your service's tasks take a while to start and respond to Elastic Load Balancing health checks, you can specify a health check grace period of up to 2,147,483,647 seconds (about 69 years). During that time, the Amazon ECS service scheduler ignores health check status. This grace period can prevent the service scheduler from marking tasks as unhealthy and stopping them before they have time to come up.

  • :scheduling_strategy (String) —

    The scheduling strategy to use for the service. For more information, see Services.

    There are two service scheduler strategies available:

    • REPLICA-The replica scheduling strategy places and maintains the 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. This scheduler strategy is required if the service uses the CODE_DEPLOY or EXTERNAL deployment controller types.

    • 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 and will stop tasks that don't meet the placement constraints. When you're using this strategy, you don't need to specify a desired number of tasks, a task placement strategy, or use Service Auto Scaling policies.

      Tasks using the Fargate launch type or the CODE_DEPLOY or EXTERNAL deployment controller types don't support the DAEMON scheduling strategy.

  • :deployment_controller (Types::DeploymentController) —

    The deployment controller to use for the service. If no deployment controller is specified, the default value of ECS is used.

  • :tags (Array<Types::Tag>) —

    The metadata that you apply to the service to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. When a service is deleted, the tags are deleted as well.

    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.

  • :enable_ecs_managed_tags (Boolean) —

    Specifies whether to turn on Amazon ECS managed tags for the tasks within the service. For more information, see Tagging your Amazon ECS resources in the Amazon Elastic Container Service Developer Guide.

  • :propagate_tags (String) —

    Specifies whether to propagate the tags from the task definition to the task. If no value is specified, the tags aren't propagated. Tags can only be propagated to the task during task creation. To add tags to a task after task creation, use the TagResource API action.

  • :enable_execute_command (Boolean) —

    Determines whether the execute command functionality is enabled for the service. If true, this enables execute command functionality on all containers in the service tasks.

Returns:

See Also:



1451
1452
1453
1454
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 1451

def create_service(params = {}, options = {})
  req = build_request(:create_service, params)
  req.send_request(options)
end

#create_task_set(params = {}) ⇒ Types::CreateTaskSetResponse

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.

Examples:

Request syntax with placeholder values


resp = client.create_task_set({
  service: "String", # required
  cluster: "String", # required
  external_id: "String",
  task_definition: "String", # required
  network_configuration: {
    awsvpc_configuration: {
      subnets: ["String"], # required
      security_groups: ["String"],
      assign_public_ip: "ENABLED", # accepts ENABLED, DISABLED
    },
  },
  load_balancers: [
    {
      target_group_arn: "String",
      load_balancer_name: "String",
      container_name: "String",
      container_port: 1,
    },
  ],
  service_registries: [
    {
      registry_arn: "String",
      port: 1,
      container_name: "String",
      container_port: 1,
    },
  ],
  launch_type: "EC2", # accepts EC2, FARGATE, EXTERNAL
  capacity_provider_strategy: [
    {
      capacity_provider: "String", # required
      weight: 1,
      base: 1,
    },
  ],
  platform_version: "String",
  scale: {
    value: 1.0,
    unit: "PERCENT", # accepts PERCENT
  },
  client_token: "String",
  tags: [
    {
      key: "TagKey",
      value: "TagValue",
    },
  ],
})

Response structure


resp.task_set.id #=> String
resp.task_set.task_set_arn #=> String
resp.task_set.service_arn #=> String
resp.task_set.cluster_arn #=> String
resp.task_set.started_by #=> String
resp.task_set.external_id #=> String
resp.task_set.status #=> String
resp.task_set.task_definition #=> String
resp.task_set.computed_desired_count #=> Integer
resp.task_set.pending_count #=> Integer
resp.task_set.running_count #=> Integer
resp.task_set.created_at #=> Time
resp.task_set.updated_at #=> Time
resp.task_set.launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.task_set.capacity_provider_strategy #=> Array
resp.task_set.capacity_provider_strategy[0].capacity_provider #=> String
resp.task_set.capacity_provider_strategy[0].weight #=> Integer
resp.task_set.capacity_provider_strategy[0].base #=> Integer
resp.task_set.platform_version #=> String
resp.task_set.platform_family #=> String
resp.task_set.network_configuration.awsvpc_configuration.subnets #=> Array
resp.task_set.network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.task_set.network_configuration.awsvpc_configuration.security_groups #=> Array
resp.task_set.network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.task_set.network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.task_set.load_balancers #=> Array
resp.task_set.load_balancers[0].target_group_arn #=> String
resp.task_set.load_balancers[0].load_balancer_name #=> String
resp.task_set.load_balancers[0].container_name #=> String
resp.task_set.load_balancers[0].container_port #=> Integer
resp.task_set.service_registries #=> Array
resp.task_set.service_registries[0].registry_arn #=> String
resp.task_set.service_registries[0].port #=> Integer
resp.task_set.service_registries[0].container_name #=> String
resp.task_set.service_registries[0].container_port #=> Integer
resp.task_set.scale.value #=> Float
resp.task_set.scale.unit #=> String, one of "PERCENT"
resp.task_set.stability_status #=> String, one of "STEADY_STATE", "STABILIZING"
resp.task_set.stability_status_at #=> Time
resp.task_set.tags #=> Array
resp.task_set.tags[0].key #=> String
resp.task_set.tags[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :service (required, String) —

    The short name or full Amazon Resource Name (ARN) of the service to create the task set in.

  • :cluster (required, String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the service to create the task set in.

  • :external_id (String) —

    An optional non-unique tag that identifies this task set in external systems. If the task set is associated with a service discovery registry, the tasks in this task set will have the ECS_TASK_SET_EXTERNAL_ID Cloud Map attribute set to the provided value.

  • :task_definition (required, String) —

    The task definition for the tasks in the task set to use.

  • :network_configuration (Types::NetworkConfiguration) —

    An object representing the network configuration for a task set.

  • :load_balancers (Array<Types::LoadBalancer>) —

    A load balancer object representing the load balancer to use with the task set. The supported load balancer types are either an Application Load Balancer or a Network Load Balancer.

  • :service_registries (Array<Types::ServiceRegistry>) —

    The details of the service discovery registries to assign to this task set. For more information, see Service discovery.

  • :launch_type (String) —

    The launch type that new tasks in the task set uses. For more information, see Amazon ECS launch types in the Amazon Elastic Container Service Developer Guide.

    If a launchType is specified, the capacityProviderStrategy parameter must be omitted.

  • :capacity_provider_strategy (Array<Types::CapacityProviderStrategyItem>) —

    The capacity provider strategy to use for the task set.

    A capacity provider strategy consists of one or more capacity providers along with the base and weight to assign to them. A capacity provider must be associated with the cluster to be used in a capacity provider strategy. The PutClusterCapacityProviders API is used to associate a capacity provider with a cluster. Only capacity providers with an ACTIVE or UPDATING status can be used.

    If a capacityProviderStrategy is specified, the launchType parameter must be omitted. If no capacityProviderStrategy or launchType is specified, the defaultCapacityProviderStrategy for the cluster is used.

    If specifying a capacity provider that uses an Auto Scaling group, the capacity provider must already be created. New 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 PutClusterCapacityProviders API operation is used to update the list of available capacity providers for a cluster after the cluster is created.

  • :platform_version (String) —

    The platform version that the tasks in the task set uses. A platform version is specified only for tasks using the Fargate launch type. If one isn't specified, the LATEST platform version is used.

  • :scale (Types::Scale) —

    A floating-point percentage of the desired number of tasks to place and keep running in the task set.

  • :client_token (String) —

    The identifier that you provide to ensure the idempotency of the request. It's case sensitive and must be unique. It can be up to 32 ASCII characters are allowed.

  • :tags (Array<Types::Tag>) —

    The metadata that you apply to the task set to help you categorize and organize them. Each tag consists of a key and an optional value. You define both. When a service is deleted, the tags are deleted.

    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.

Returns:

See Also:



1688
1689
1690
1691
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 1688

def create_task_set(params = {}, options = {})
  req = build_request(:create_task_set, params)
  req.send_request(options)
end

#delete_account_setting(params = {}) ⇒ Types::DeleteAccountSettingResponse

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

Examples:

Example: To delete your account setting


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

resp = client.({
  name: "serviceLongArnFormat", 
})

resp.to_h outputs the following:
{
  setting: {
    name: "serviceLongArnFormat", 
    value: "enabled", 
    principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
  }, 
}

Example: 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.

resp = client.({
  name: "containerInstanceLongArnFormat", 
  principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
})

resp.to_h outputs the following:
{
  setting: {
    name: "containerInstanceLongArnFormat", 
    value: "enabled", 
    principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
  }, 
}

Request syntax with placeholder values


resp = client.({
  name: "serviceLongArnFormat", # required, accepts serviceLongArnFormat, taskLongArnFormat, containerInstanceLongArnFormat, awsvpcTrunking, containerInsights
  principal_arn: "String",
})

Response structure


resp.setting.name #=> String, one of "serviceLongArnFormat", "taskLongArnFormat", "containerInstanceLongArnFormat", "awsvpcTrunking", "containerInsights"
resp.setting.value #=> String
resp.setting.principal_arn #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :name (required, String) —

    The resource name to disable the account setting for. If serviceLongArnFormat is specified, the ARN for your Amazon ECS services is affected. If taskLongArnFormat is specified, the ARN and resource ID for your Amazon ECS tasks is affected. If containerInstanceLongArnFormat is specified, the ARN and resource ID for your Amazon ECS container instances is affected. If awsvpcTrunking is specified, the ENI limit for your Amazon ECS container instances is affected.

  • :principal_arn (String) —

    The Amazon Resource Name (ARN) of the principal. It can be an IAM user, IAM role, or the root user. If you specify the root user, it disables the account setting for all IAM users, IAM roles, and the root user of the account unless an IAM user or role explicitly overrides these settings. If this field is omitted, the setting is changed only for the authenticated user.

Returns:

See Also:



1772
1773
1774
1775
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 1772

def (params = {}, options = {})
  req = build_request(:delete_account_setting, params)
  req.send_request(options)
end

#delete_attributes(params = {}) ⇒ Types::DeleteAttributesResponse

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

Examples:

Request syntax with placeholder values


resp = client.delete_attributes({
  cluster: "String",
  attributes: [ # required
    {
      name: "String", # required
      value: "String",
      target_type: "container-instance", # accepts container-instance
      target_id: "String",
    },
  ],
})

Response structure


resp.attributes #=> Array
resp.attributes[0].name #=> String
resp.attributes[0].value #=> String
resp.attributes[0].target_type #=> String, one of "container-instance"
resp.attributes[0].target_id #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that contains the resource to delete attributes. If you do not specify a cluster, the default cluster is assumed.

  • :attributes (required, Array<Types::Attribute>) —

    The attributes to delete from your resource. You can specify up to 10 attributes for each request. For custom attributes, specify the attribute name and target ID, but don't specify the value. If you specify the target ID using the short form, you must also specify the target type.

Returns:

See Also:



1821
1822
1823
1824
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 1821

def delete_attributes(params = {}, options = {})
  req = build_request(:delete_attributes, params)
  req.send_request(options)
end

#delete_capacity_provider(params = {}) ⇒ Types::DeleteCapacityProviderResponse

Deletes the specified capacity provider.

The FARGATE and FARGATE_SPOT capacity providers are reserved and can't be deleted. You can disassociate them from a cluster using either the PutClusterCapacityProviders API or by deleting the cluster.

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.

Examples:

Request syntax with placeholder values


resp = client.delete_capacity_provider({
  capacity_provider: "String", # required
})

Response structure


resp.capacity_provider.capacity_provider_arn #=> String
resp.capacity_provider.name #=> String
resp.capacity_provider.status #=> String, one of "ACTIVE", "INACTIVE"
resp.capacity_provider.auto_scaling_group_provider.auto_scaling_group_arn #=> String
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.status #=> String, one of "ENABLED", "DISABLED"
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.target_capacity #=> Integer
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.minimum_scaling_step_size #=> Integer
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.maximum_scaling_step_size #=> Integer
resp.capacity_provider.auto_scaling_group_provider.managed_scaling.instance_warmup_period #=> Integer
resp.capacity_provider.auto_scaling_group_provider.managed_termination_protection #=> String, one of "ENABLED", "DISABLED"
resp.capacity_provider.update_status #=> String, one of "DELETE_IN_PROGRESS", "DELETE_COMPLETE", "DELETE_FAILED", "UPDATE_IN_PROGRESS", "UPDATE_COMPLETE", "UPDATE_FAILED"
resp.capacity_provider.update_status_reason #=> String
resp.capacity_provider.tags #=> Array
resp.capacity_provider.tags[0].key #=> String
resp.capacity_provider.tags[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :capacity_provider (required, String) —

    The short name or full Amazon Resource Name (ARN) of the capacity provider to delete.

Returns:

See Also:



1881
1882
1883
1884
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 1881

def delete_capacity_provider(params = {}, options = {})
  req = build_request(:delete_capacity_provider, params)
  req.send_request(options)
end

#delete_cluster(params = {}) ⇒ Types::DeleteClusterResponse

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.

Examples:

Example: To delete an empty cluster


# This example deletes an empty cluster in your default region.

resp = client.delete_cluster({
  cluster: "my_cluster", 
})

resp.to_h outputs the following:
{
  cluster: {
    active_services_count: 0, 
    cluster_arn: "arn:aws:ecs:us-east-1:012345678910:cluster/my_cluster", 
    cluster_name: "my_cluster", 
    pending_tasks_count: 0, 
    registered_container_instances_count: 0, 
    running_tasks_count: 0, 
    status: "INACTIVE", 
  }, 
}

Request syntax with placeholder values


resp = client.delete_cluster({
  cluster: "String", # required
})

Response structure


resp.cluster.cluster_arn #=> String
resp.cluster.cluster_name #=> String
resp.cluster.configuration.execute_command_configuration.kms_key_id #=> String
resp.cluster.configuration.execute_command_configuration.logging #=> String, one of "NONE", "DEFAULT", "OVERRIDE"
resp.cluster.configuration.execute_command_configuration.log_configuration.cloud_watch_log_group_name #=> String
resp.cluster.configuration.execute_command_configuration.log_configuration.cloud_watch_encryption_enabled #=> Boolean
resp.cluster.configuration.execute_command_configuration.log_configuration.s3_bucket_name #=> String
resp.cluster.configuration.execute_command_configuration.log_configuration.s3_encryption_enabled #=> Boolean
resp.cluster.configuration.execute_command_configuration.log_configuration.s3_key_prefix #=> String
resp.cluster.status #=> String
resp.cluster.registered_container_instances_count #=> Integer
resp.cluster.running_tasks_count #=> Integer
resp.cluster.pending_tasks_count #=> Integer
resp.cluster.active_services_count #=> Integer
resp.cluster.statistics #=> Array
resp.cluster.statistics[0].name #=> String
resp.cluster.statistics[0].value #=> String
resp.cluster.tags #=> Array
resp.cluster.tags[0].key #=> String
resp.cluster.tags[0].value #=> String
resp.cluster.settings #=> Array
resp.cluster.settings[0].name #=> String, one of "containerInsights"
resp.cluster.settings[0].value #=> String
resp.cluster.capacity_providers #=> Array
resp.cluster.capacity_providers[0] #=> String
resp.cluster.default_capacity_provider_strategy #=> Array
resp.cluster.default_capacity_provider_strategy[0].capacity_provider #=> String
resp.cluster.default_capacity_provider_strategy[0].weight #=> Integer
resp.cluster.default_capacity_provider_strategy[0].base #=> Integer
resp.cluster.attachments #=> Array
resp.cluster.attachments[0].id #=> String
resp.cluster.attachments[0].type #=> String
resp.cluster.attachments[0].status #=> String
resp.cluster.attachments[0].details #=> Array
resp.cluster.attachments[0].details[0].name #=> String
resp.cluster.attachments[0].details[0].value #=> String
resp.cluster.attachments_status #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (required, String) —

    The short name or full Amazon Resource Name (ARN) of the cluster to delete.

Returns:

See Also:



1977
1978
1979
1980
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 1977

def delete_cluster(params = {}, options = {})
  req = build_request(:delete_cluster, params)
  req.send_request(options)
end

#delete_service(params = {}) ⇒ Types::DeleteServiceResponse

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.

When you delete a service, if there are still running tasks that require cleanup, the service status moves from ACTIVE to DRAINING, and the service is no longer visible in the console or in the ListServices API operation. After all tasks have transitioned to either STOPPING or STOPPED status, the service status moves from DRAINING to INACTIVE. Services in the DRAINING or INACTIVE status can still be viewed with the DescribeServices API operation. However, in the future, INACTIVE services may be cleaned up and purged from Amazon ECS record keeping, and DescribeServices calls on those services return a ServiceNotFoundException error.

If you attempt to create a new service with the same name as an existing service in either ACTIVE or DRAINING status, you receive an error.

Examples:

Example: 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.

resp = client.delete_service({
  service: "my-http-service", 
})

resp.to_h outputs the following:
{
}

Request syntax with placeholder values


resp = client.delete_service({
  cluster: "String",
  service: "String", # required
  force: false,
})

Response structure


resp.service.service_arn #=> String
resp.service.service_name #=> String
resp.service.cluster_arn #=> String
resp.service.load_balancers #=> Array
resp.service.load_balancers[0].target_group_arn #=> String
resp.service.load_balancers[0].load_balancer_name #=> String
resp.service.load_balancers[0].container_name #=> String
resp.service.load_balancers[0].container_port #=> Integer
resp.service.service_registries #=> Array
resp.service.service_registries[0].registry_arn #=> String
resp.service.service_registries[0].port #=> Integer
resp.service.service_registries[0].container_name #=> String
resp.service.service_registries[0].container_port #=> Integer
resp.service.status #=> String
resp.service.desired_count #=> Integer
resp.service.running_count #=> Integer
resp.service.pending_count #=> Integer
resp.service.launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.service.capacity_provider_strategy #=> Array
resp.service.capacity_provider_strategy[0].capacity_provider #=> String
resp.service.capacity_provider_strategy[0].weight #=> Integer
resp.service.capacity_provider_strategy[0].base #=> Integer
resp.service.platform_version #=> String
resp.service.platform_family #=> String
resp.service.task_definition #=> String
resp.service.deployment_configuration.deployment_circuit_breaker.enable #=> Boolean
resp.service.deployment_configuration.deployment_circuit_breaker.rollback #=> Boolean
resp.service.deployment_configuration.maximum_percent #=> Integer
resp.service.deployment_configuration.minimum_healthy_percent #=> Integer
resp.service.task_sets #=> Array
resp.service.task_sets[0].id #=> String
resp.service.task_sets[0].task_set_arn #=> String
resp.service.task_sets[0].service_arn #=> String
resp.service.task_sets[0].cluster_arn #=> String
resp.service.task_sets[0].started_by #=> String
resp.service.task_sets[0].external_id #=> String
resp.service.task_sets[0].status #=> String
resp.service.task_sets[0].task_definition #=> String
resp.service.task_sets[0].computed_desired_count #=> Integer
resp.service.task_sets[0].pending_count #=> Integer
resp.service.task_sets[0].running_count #=> Integer
resp.service.task_sets[0].created_at #=> Time
resp.service.task_sets[0].updated_at #=> Time
resp.service.task_sets[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.service.task_sets[0].capacity_provider_strategy #=> Array
resp.service.task_sets[0].capacity_provider_strategy[0].capacity_provider #=> String
resp.service.task_sets[0].capacity_provider_strategy[0].weight #=> Integer
resp.service.task_sets[0].capacity_provider_strategy[0].base #=> Integer
resp.service.task_sets[0].platform_version #=> String
resp.service.task_sets[0].platform_family #=> String
resp.service.task_sets[0].network_configuration.awsvpc_configuration.subnets #=> Array
resp.service.task_sets[0].network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.service.task_sets[0].network_configuration.awsvpc_configuration.security_groups #=> Array
resp.service.task_sets[0].network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.service.task_sets[0].network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.service.task_sets[0].load_balancers #=> Array
resp.service.task_sets[0].load_balancers[0].target_group_arn #=> String
resp.service.task_sets[0].load_balancers[0].load_balancer_name #=> String
resp.service.task_sets[0].load_balancers[0].container_name #=> String
resp.service.task_sets[0].load_balancers[0].container_port #=> Integer
resp.service.task_sets[0].service_registries #=> Array
resp.service.task_sets[0].service_registries[0].registry_arn #=> String
resp.service.task_sets[0].service_registries[0].port #=> Integer
resp.service.task_sets[0].service_registries[0].container_name #=> String
resp.service.task_sets[0].service_registries[0].container_port #=> Integer
resp.service.task_sets[0].scale.value #=> Float
resp.service.task_sets[0].scale.unit #=> String, one of "PERCENT"
resp.service.task_sets[0].stability_status #=> String, one of "STEADY_STATE", "STABILIZING"
resp.service.task_sets[0].stability_status_at #=> Time
resp.service.task_sets[0].tags #=> Array
resp.service.task_sets[0].tags[0].key #=> String
resp.service.task_sets[0].tags[0].value #=> String
resp.service.deployments #=> Array
resp.service.deployments[0].id #=> String
resp.service.deployments[0].status #=> String
resp.service.deployments[0].task_definition #=> String
resp.service.deployments[0].desired_count #=> Integer
resp.service.deployments[0].pending_count #=> Integer
resp.service.deployments[0].running_count #=> Integer
resp.service.deployments[0].failed_tasks #=> Integer
resp.service.deployments[0].created_at #=> Time
resp.service.deployments[0].updated_at #=> Time
resp.service.deployments[0].capacity_provider_strategy #=> Array
resp.service.deployments[0].capacity_provider_strategy[0].capacity_provider #=> String
resp.service.deployments[0].capacity_provider_strategy[0].weight #=> Integer
resp.service.deployments[0].capacity_provider_strategy[0].base #=> Integer
resp.service.deployments[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.service.deployments[0].platform_version #=> String
resp.service.deployments[0].platform_family #=> String
resp.service.deployments[0].network_configuration.awsvpc_configuration.subnets #=> Array
resp.service.deployments[0].network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.service.deployments[0].network_configuration.awsvpc_configuration.security_groups #=> Array
resp.service.deployments[0].network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.service.deployments[0].network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.service.deployments[0].rollout_state #=> String, one of "COMPLETED", "FAILED", "IN_PROGRESS"
resp.service.deployments[0].rollout_state_reason #=> String
resp.service.role_arn #=> String
resp.service.events #=> Array
resp.service.events[0].id #=> String
resp.service.events[0].created_at #=> Time
resp.service.events[0].message #=> String
resp.service.created_at #=> Time
resp.service.placement_constraints #=> Array
resp.service.placement_constraints[0].type #=> String, one of "distinctInstance", "memberOf"
resp.service.placement_constraints[0].expression #=> String
resp.service.placement_strategy #=> Array
resp.service.placement_strategy[0].type #=> String, one of "random", "spread", "binpack"
resp.service.placement_strategy[0].field #=> String
resp.service.network_configuration.awsvpc_configuration.subnets #=> Array
resp.service.network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.service.network_configuration.awsvpc_configuration.security_groups #=> Array
resp.service.network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.service.network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.service.health_check_grace_period_seconds #=> Integer
resp.service.scheduling_strategy #=> String, one of "REPLICA", "DAEMON"
resp.service.deployment_controller.type #=> String, one of "ECS", "CODE_DEPLOY", "EXTERNAL"
resp.service.tags #=> Array
resp.service.tags[0].key #=> String
resp.service.tags[0].value #=> String
resp.service.created_by #=> String
resp.service.enable_ecs_managed_tags #=> Boolean
resp.service.propagate_tags #=> String, one of "TASK_DEFINITION", "SERVICE", "NONE"
resp.service.enable_execute_command #=> Boolean

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the service to delete. If you do not specify a cluster, the default cluster is assumed.

  • :service (required, String) —

    The name of the service to delete.

  • :force (Boolean) —

    If true, allows you to delete a service even if it wasn't scaled down to zero tasks. It's only necessary to use this if the service uses the REPLICA scheduling strategy.

Returns:

See Also:



2174
2175
2176
2177
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 2174

def delete_service(params = {}, options = {})
  req = build_request(:delete_service, params)
  req.send_request(options)
end

#delete_task_set(params = {}) ⇒ Types::DeleteTaskSetResponse

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.

Examples:

Request syntax with placeholder values


resp = client.delete_task_set({
  cluster: "String", # required
  service: "String", # required
  task_set: "String", # required
  force: false,
})

Response structure


resp.task_set.id #=> String
resp.task_set.task_set_arn #=> String
resp.task_set.service_arn #=> String
resp.task_set.cluster_arn #=> String
resp.task_set.started_by #=> String
resp.task_set.external_id #=> String
resp.task_set.status #=> String
resp.task_set.task_definition #=> String
resp.task_set.computed_desired_count #=> Integer
resp.task_set.pending_count #=> Integer
resp.task_set.running_count #=> Integer
resp.task_set.created_at #=> Time
resp.task_set.updated_at #=> Time
resp.task_set.launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.task_set.capacity_provider_strategy #=> Array
resp.task_set.capacity_provider_strategy[0].capacity_provider #=> String
resp.task_set.capacity_provider_strategy[0].weight #=> Integer
resp.task_set.capacity_provider_strategy[0].base #=> Integer
resp.task_set.platform_version #=> String
resp.task_set.platform_family #=> String
resp.task_set.network_configuration.awsvpc_configuration.subnets #=> Array
resp.task_set.network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.task_set.network_configuration.awsvpc_configuration.security_groups #=> Array
resp.task_set.network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.task_set.network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.task_set.load_balancers #=> Array
resp.task_set.load_balancers[0].target_group_arn #=> String
resp.task_set.load_balancers[0].load_balancer_name #=> String
resp.task_set.load_balancers[0].container_name #=> String
resp.task_set.load_balancers[0].container_port #=> Integer
resp.task_set.service_registries #=> Array
resp.task_set.service_registries[0].registry_arn #=> String
resp.task_set.service_registries[0].port #=> Integer
resp.task_set.service_registries[0].container_name #=> String
resp.task_set.service_registries[0].container_port #=> Integer
resp.task_set.scale.value #=> Float
resp.task_set.scale.unit #=> String, one of "PERCENT"
resp.task_set.stability_status #=> String, one of "STEADY_STATE", "STABILIZING"
resp.task_set.stability_status_at #=> Time
resp.task_set.tags #=> Array
resp.task_set.tags[0].key #=> String
resp.task_set.tags[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (required, String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the service that the task set found in to delete.

  • :service (required, String) —

    The short name or full Amazon Resource Name (ARN) of the service that hosts the task set to delete.

  • :task_set (required, String) —

    The task set ID or full Amazon Resource Name (ARN) of the task set to delete.

  • :force (Boolean) —

    If true, you can delete a task set even if it hasn't been scaled down to zero.

Returns:

See Also:



2266
2267
2268
2269
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 2266

def delete_task_set(params = {}, options = {})
  req = build_request(:delete_task_set, params)
  req.send_request(options)
end

#deregister_container_instance(params = {}) ⇒ Types::DeregisterContainerInstanceResponse

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.

If you terminate a running container instance, Amazon ECS automatically deregisters the instance from your cluster (stopped container instances or instances with disconnected agents aren't automatically deregistered when terminated).

Examples:

Example: 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.

resp = client.deregister_container_instance({
  cluster: "default", 
  container_instance: "container_instance_UUID", 
  force: true, 
})

resp.to_h outputs the following:
{
}

Request syntax with placeholder values


resp = client.deregister_container_instance({
  cluster: "String",
  container_instance: "String", # required
  force: false,
})

Response structure


resp.container_instance.container_instance_arn #=> String
resp.container_instance.ec2_instance_id #=> String
resp.container_instance.capacity_provider_name #=> String
resp.container_instance.version #=> Integer
resp.container_instance.version_info.agent_version #=> String
resp.container_instance.version_info.agent_hash #=> String
resp.container_instance.version_info.docker_version #=> String
resp.container_instance.remaining_resources #=> Array
resp.container_instance.remaining_resources[0].name #=> String
resp.container_instance.remaining_resources[0].type #=> String
resp.container_instance.remaining_resources[0].double_value #=> Float
resp.container_instance.remaining_resources[0].long_value #=> Integer
resp.container_instance.remaining_resources[0].integer_value #=> Integer
resp.container_instance.remaining_resources[0].string_set_value #=> Array
resp.container_instance.remaining_resources[0].string_set_value[0] #=> String
resp.container_instance.registered_resources #=> Array
resp.container_instance.registered_resources[0].name #=> String
resp.container_instance.registered_resources[0].type #=> String
resp.container_instance.registered_resources[0].double_value #=> Float
resp.container_instance.registered_resources[0].long_value #=> Integer
resp.container_instance.registered_resources[0].integer_value #=> Integer
resp.container_instance.registered_resources[0].string_set_value #=> Array
resp.container_instance.registered_resources[0].string_set_value[0] #=> String
resp.container_instance.status #=> String
resp.container_instance.status_reason #=> String
resp.container_instance.agent_connected #=> Boolean
resp.container_instance.running_tasks_count #=> Integer
resp.container_instance.pending_tasks_count #=> Integer
resp.container_instance.agent_update_status #=> String, one of "PENDING", "STAGING", "STAGED", "UPDATING", "UPDATED", "FAILED"
resp.container_instance.attributes #=> Array
resp.container_instance.attributes[0].name #=> String
resp.container_instance.attributes[0].value #=> String
resp.container_instance.attributes[0].target_type #=> String, one of "container-instance"
resp.container_instance.attributes[0].target_id #=> String
resp.container_instance.registered_at #=> Time
resp.container_instance.attachments #=> Array
resp.container_instance.attachments[0].id #=> String
resp.container_instance.attachments[0].type #=> String
resp.container_instance.attachments[0].status #=> String
resp.container_instance.attachments[0].details #=> Array
resp.container_instance.attachments[0].details[0].name #=> String
resp.container_instance.attachments[0].details[0].value #=> String
resp.container_instance.tags #=> Array
resp.container_instance.tags[0].key #=> String
resp.container_instance.tags[0].value #=> String
resp.container_instance.health_status.overall_status #=> String, one of "OK", "IMPAIRED", "INSUFFICIENT_DATA", "INITIALIZING"
resp.container_instance.health_status.details #=> Array
resp.container_instance.health_status.details[0].type #=> String, one of "CONTAINER_RUNTIME"
resp.container_instance.health_status.details[0].status #=> String, one of "OK", "IMPAIRED", "INSUFFICIENT_DATA", "INITIALIZING"
resp.container_instance.health_status.details[0].last_updated #=> Time
resp.container_instance.health_status.details[0].last_status_change #=> Time

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the container instance to deregister. If you do not specify a cluster, the default cluster is assumed.

  • :container_instance (required, String) —

    The container instance ID or full ARN of the container instance to deregister. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.

  • :force (Boolean) —

    Forces the container instance to be deregistered. If you have tasks running on the container instance when you deregister it with the force option, these tasks remain running until you terminate the instance or the tasks stop through some other means, but they're orphaned (no longer monitored or accounted for by Amazon ECS). If an orphaned task on your container instance is part of an Amazon ECS service, then the service scheduler starts another copy of that task, on a different container instance if possible.

    Any containers in orphaned service tasks that are registered with a Classic Load Balancer or an Application Load Balancer target group are deregistered. They begin connection draining according to the settings on the load balancer or target group.

Returns:

See Also:



2406
2407
2408
2409
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 2406

def deregister_container_instance(params = {}, options = {})
  req = build_request(:deregister_container_instance, params)
  req.send_request(options)
end

#deregister_task_definition(params = {}) ⇒ Types::DeregisterTaskDefinitionResponse

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.

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.

At this time, INACTIVE task definitions remain discoverable in your account indefinitely. However, this behavior is subject to change in the future. We don't recommend that you rely on INACTIVE task definitions persisting beyond the lifecycle of any associated tasks and services.

Examples:

Request syntax with placeholder values


resp = client.deregister_task_definition({
  task_definition: "String", # required
})

Response structure


resp.task_definition.task_definition_arn #=> String
resp.task_definition.container_definitions #=> Array
resp.task_definition.container_definitions[0].name #=> String
resp.task_definition.container_definitions[0].image #=> String
resp.task_definition.container_definitions[0].repository_credentials.credentials_parameter #=> String
resp.task_definition.container_definitions[0].cpu #=> Integer
resp.task_definition.container_definitions[0].memory #=> Integer
resp.task_definition.container_definitions[0].memory_reservation #=> Integer
resp.task_definition.container_definitions[0].links #=> Array
resp.task_definition.container_definitions[0].links[0] #=> String
resp.task_definition.container_definitions[0].port_mappings #=> Array
resp.task_definition.container_definitions[0].port_mappings[0].container_port #=> Integer
resp.task_definition.container_definitions[0].port_mappings[0].host_port #=> Integer
resp.task_definition.container_definitions[0].port_mappings[0].protocol #=> String, one of "tcp", "udp"
resp.task_definition.container_definitions[0].essential #=> Boolean
resp.task_definition.container_definitions[0].entry_point #=> Array
resp.task_definition.container_definitions[0].entry_point[0] #=> String
resp.task_definition.container_definitions[0].command #=> Array
resp.task_definition.container_definitions[0].command[0] #=> String
resp.task_definition.container_definitions[0].environment #=> Array
resp.task_definition.container_definitions[0].environment[0].name #=> String
resp.task_definition.container_definitions[0].environment[0].value #=> String
resp.task_definition.container_definitions[0].environment_files #=> Array
resp.task_definition.container_definitions[0].environment_files[0].value #=> String
resp.task_definition.container_definitions[0].environment_files[0].type #=> String, one of "s3"
resp.task_definition.container_definitions[0].mount_points #=> Array
resp.task_definition.container_definitions[0].mount_points[0].source_volume #=> String
resp.task_definition.container_definitions[0].mount_points[0].container_path #=> String
resp.task_definition.container_definitions[0].mount_points[0].read_only #=> Boolean
resp.task_definition.container_definitions[0].volumes_from #=> Array
resp.task_definition.container_definitions[0].volumes_from[0].source_container #=> String
resp.task_definition.container_definitions[0].volumes_from[0].read_only #=> Boolean
resp.task_definition.container_definitions[0].linux_parameters.capabilities.add #=> Array
resp.task_definition.container_definitions[0].linux_parameters.capabilities.add[0] #=> String
resp.task_definition.container_definitions[0].linux_parameters.capabilities.drop #=> Array
resp.task_definition.container_definitions[0].linux_parameters.capabilities.drop[0] #=> String
resp.task_definition.container_definitions[0].linux_parameters.devices #=> Array
resp.task_definition.container_definitions[0].linux_parameters.devices[0].host_path #=> String
resp.task_definition.container_definitions[0].linux_parameters.devices[0].container_path #=> String
resp.task_definition.container_definitions[0].linux_parameters.devices[0].permissions #=> Array
resp.task_definition.container_definitions[0].linux_parameters.devices[0].permissions[0] #=> String, one of "read", "write", "mknod"
resp.task_definition.container_definitions[0].linux_parameters.init_process_enabled #=> Boolean
resp.task_definition.container_definitions[0].linux_parameters.shared_memory_size #=> Integer
resp.task_definition.container_definitions[0].linux_parameters.tmpfs #=> Array
resp.task_definition.container_definitions[0].linux_parameters.tmpfs[0].container_path #=> String
resp.task_definition.container_definitions[0].linux_parameters.tmpfs[0].size #=> Integer
resp.task_definition.container_definitions[0].linux_parameters.tmpfs[0].mount_options #=> Array
resp.task_definition.container_definitions[0].linux_parameters.tmpfs[0].mount_options[0] #=> String
resp.task_definition.container_definitions[0].linux_parameters.max_swap #=> Integer
resp.task_definition.container_definitions[0].linux_parameters.swappiness #=> Integer
resp.task_definition.container_definitions[0].secrets #=> Array
resp.task_definition.container_definitions[0].secrets[0].name #=> String
resp.task_definition.container_definitions[0].secrets[0].value_from #=> String
resp.task_definition.container_definitions[0].depends_on #=> Array
resp.task_definition.container_definitions[0].depends_on[0].container_name #=> String
resp.task_definition.container_definitions[0].depends_on[0].condition #=> String, one of "START", "COMPLETE", "SUCCESS", "HEALTHY"
resp.task_definition.container_definitions[0].start_timeout #=> Integer
resp.task_definition.container_definitions[0].stop_timeout #=> Integer
resp.task_definition.container_definitions[0].hostname #=> String
resp.task_definition.container_definitions[0].user #=> String
resp.task_definition.container_definitions[0].working_directory #=> String
resp.task_definition.container_definitions[0].disable_networking #=> Boolean
resp.task_definition.container_definitions[0].privileged #=> Boolean
resp.task_definition.container_definitions[0].readonly_root_filesystem #=> Boolean
resp.task_definition.container_definitions[0].dns_servers #=> Array
resp.task_definition.container_definitions[0].dns_servers[0] #=> String
resp.task_definition.container_definitions[0].dns_search_domains #=> Array
resp.task_definition.container_definitions[0].dns_search_domains[0] #=> String
resp.task_definition.container_definitions[0].extra_hosts #=> Array
resp.task_definition.container_definitions[0].extra_hosts[0].hostname #=> String
resp.task_definition.container_definitions[0].extra_hosts[0].ip_address #=> String
resp.task_definition.container_definitions[0].docker_security_options #=> Array
resp.task_definition.container_definitions[0].docker_security_options[0] #=> String
resp.task_definition.container_definitions[0].interactive #=> Boolean
resp.task_definition.container_definitions[0].pseudo_terminal #=> Boolean
resp.task_definition.container_definitions[0].docker_labels #=> Hash
resp.task_definition.container_definitions[0].docker_labels["String"] #=> String
resp.task_definition.container_definitions[0].ulimits #=> Array
resp.task_definition.container_definitions[0].ulimits[0].name #=> String, one of "core", "cpu", "data", "fsize", "locks", "memlock", "msgqueue", "nice", "nofile", "nproc", "rss", "rtprio", "rttime", "sigpending", "stack"
resp.task_definition.container_definitions[0].ulimits[0].soft_limit #=> Integer
resp.task_definition.container_definitions[0].ulimits[0].hard_limit #=> Integer
resp.task_definition.container_definitions[0].log_configuration.log_driver #=> String, one of "json-file", "syslog", "journald", "gelf", "fluentd", "awslogs", "splunk", "awsfirelens"
resp.task_definition.container_definitions[0].log_configuration.options #=> Hash
resp.task_definition.container_definitions[0].log_configuration.options["String"] #=> String
resp.task_definition.container_definitions[0].log_configuration.secret_options #=> Array
resp.task_definition.container_definitions[0].log_configuration.secret_options[0].name #=> String
resp.task_definition.container_definitions[0].log_configuration.secret_options[0].value_from #=> String
resp.task_definition.container_definitions[0].health_check.command #=> Array
resp.task_definition.container_definitions[0].health_check.command[0] #=> String
resp.task_definition.container_definitions[0].health_check.interval #=> Integer
resp.task_definition.container_definitions[0].health_check.timeout #=> Integer
resp.task_definition.container_definitions[0].health_check.retries #=> Integer
resp.task_definition.container_definitions[0].health_check.start_period #=> Integer
resp.task_definition.container_definitions[0].system_controls #=> Array
resp.task_definition.container_definitions[0].system_controls[0].namespace #=> String
resp.task_definition.container_definitions[0].system_controls[0].value #=> String
resp.task_definition.container_definitions[0].resource_requirements #=> Array
resp.task_definition.container_definitions[0].resource_requirements[0].value #=> String
resp.task_definition.container_definitions[0].resource_requirements[0].type #=> String, one of "GPU", "InferenceAccelerator"
resp.task_definition.container_definitions[0].firelens_configuration.type #=> String, one of "fluentd", "fluentbit"
resp.task_definition.container_definitions[0].firelens_configuration.options #=> Hash
resp.task_definition.container_definitions[0].firelens_configuration.options["String"] #=> String
resp.task_definition.family #=> String
resp.task_definition.task_role_arn #=> String
resp.task_definition.execution_role_arn #=> String
resp.task_definition.network_mode #=> String, one of "bridge", "host", "awsvpc", "none"
resp.task_definition.revision #=> Integer
resp.task_definition.volumes #=> Array
resp.task_definition.volumes[0].name #=> String
resp.task_definition.volumes[0].host.source_path #=> String
resp.task_definition.volumes[0].docker_volume_configuration.scope #=> String, one of "task", "shared"
resp.task_definition.volumes[0].docker_volume_configuration.autoprovision #=> Boolean
resp.task_definition.volumes[0].docker_volume_configuration.driver #=> String
resp.task_definition.volumes[0].docker_volume_configuration.driver_opts #=> Hash
resp.task_definition.volumes[0].docker_volume_configuration.driver_opts["String"] #=> String
resp.task_definition.volumes[0].docker_volume_configuration.labels #=> Hash
resp.task_definition.volumes[0].docker_volume_configuration.labels["String"] #=> String
resp.task_definition.volumes[0].efs_volume_configuration.file_system_id #=> String
resp.task_definition.volumes[0].efs_volume_configuration.root_directory #=> String
resp.task_definition.volumes[0].efs_volume_configuration.transit_encryption #=> String, one of "ENABLED", "DISABLED"
resp.task_definition.volumes[0].efs_volume_configuration.transit_encryption_port #=> Integer
resp.task_definition.volumes[0].efs_volume_configuration.authorization_config.access_point_id #=> String
resp.task_definition.volumes[0].efs_volume_configuration.authorization_config.iam #=> String, one of "ENABLED", "DISABLED"
resp.task_definition.volumes[0].fsx_windows_file_server_volume_configuration.file_system_id #=> String
resp.task_definition.volumes[0].fsx_windows_file_server_volume_configuration.root_directory #=> String
resp.task_definition.volumes[0].fsx_windows_file_server_volume_configuration.authorization_config.credentials_parameter #=> String
resp.task_definition.volumes[0].fsx_windows_file_server_volume_configuration.authorization_config.domain #=> String
resp.task_definition.status #=> String, one of "ACTIVE", "INACTIVE"
resp.task_definition.requires_attributes #=> Array
resp.task_definition.requires_attributes[0].name #=> String
resp.task_definition.requires_attributes[0].value #=> String
resp.task_definition.requires_attributes[0].target_type #=> String, one of "container-instance"
resp.task_definition.requires_attributes[0].target_id #=> String
resp.task_definition.placement_constraints #=> Array
resp.task_definition.placement_constraints[0].type #=> String, one of "memberOf"
resp.task_definition.placement_constraints[0].expression #=> String
resp.task_definition.compatibilities #=> Array
resp.task_definition.compatibilities[0] #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.task_definition.runtime_platform.cpu_architecture #=> String, one of "X86_64", "ARM64"
resp.task_definition.runtime_platform.operating_system_family #=> String, one of "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_20H2_CORE", "LINUX"
resp.task_definition.requires_compatibilities #=> Array
resp.task_definition.requires_compatibilities[0] #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.task_definition.cpu #=> String
resp.task_definition.memory #=> String
resp.task_definition.inference_accelerators #=> Array
resp.task_definition.inference_accelerators[0].device_name #=> String
resp.task_definition.inference_accelerators[0].device_type #=> String
resp.task_definition.pid_mode #=> String, one of "host", "task"
resp.task_definition.ipc_mode #=> String, one of "host", "task", "none"
resp.task_definition.proxy_configuration.type #=> String, one of "APPMESH"
resp.task_definition.proxy_configuration.container_name #=> String
resp.task_definition.proxy_configuration.properties #=> Array
resp.task_definition.proxy_configuration.properties[0].name #=> String
resp.task_definition.proxy_configuration.properties[0].value #=> String
resp.task_definition.registered_at #=> Time
resp.task_definition.deregistered_at #=> Time
resp.task_definition.registered_by #=> String
resp.task_definition.ephemeral_storage.size_in_gi_b #=> Integer

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :task_definition (required, String) —

    The family and revision (family:revision) or full Amazon Resource Name (ARN) of the task definition to deregister. You must specify a revision.

Returns:

See Also:



2612
2613
2614
2615
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 2612

def deregister_task_definition(params = {}, options = {})
  req = build_request(:deregister_task_definition, params)
  req.send_request(options)
end

#describe_capacity_providers(params = {}) ⇒ Types::DescribeCapacityProvidersResponse

Describes one or more of your capacity providers.

Examples:

Request syntax with placeholder values


resp = client.describe_capacity_providers({
  capacity_providers: ["String"],
  include: ["TAGS"], # accepts TAGS
  max_results: 1,
  next_token: "String",
})

Response structure


resp.capacity_providers #=> Array
resp.capacity_providers[0].capacity_provider_arn #=> String
resp.capacity_providers[0].name #=> String
resp.capacity_providers[0].status #=> String, one of "ACTIVE", "INACTIVE"
resp.capacity_providers[0].auto_scaling_group_provider.auto_scaling_group_arn #=> String
resp.capacity_providers[0].auto_scaling_group_provider.managed_scaling.status #=> String, one of "ENABLED", "DISABLED"
resp.capacity_providers[0].auto_scaling_group_provider.managed_scaling.target_capacity #=> Integer
resp.capacity_providers[0].auto_scaling_group_provider.managed_scaling.minimum_scaling_step_size #=> Integer
resp.capacity_providers[0].auto_scaling_group_provider.managed_scaling.maximum_scaling_step_size #=> Integer
resp.capacity_providers[0].auto_scaling_group_provider.managed_scaling.instance_warmup_period #=> Integer
resp.capacity_providers[0].auto_scaling_group_provider.managed_termination_protection #=> String, one of "ENABLED", "DISABLED"
resp.capacity_providers[0].update_status #=> String, one of "DELETE_IN_PROGRESS", "DELETE_COMPLETE", "DELETE_FAILED", "UPDATE_IN_PROGRESS", "UPDATE_COMPLETE", "UPDATE_FAILED"
resp.capacity_providers[0].update_status_reason #=> String
resp.capacity_providers[0].tags #=> Array
resp.capacity_providers[0].tags[0].key #=> String
resp.capacity_providers[0].tags[0].value #=> String
resp.failures #=> Array
resp.failures[0].arn #=> String
resp.failures[0].reason #=> String
resp.failures[0].detail #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :capacity_providers (Array<String>) —

    The short name or full Amazon Resource Name (ARN) of one or more capacity providers. Up to 100 capacity providers can be described in an action.

  • :include (Array<String>) —

    Specifies whether or not you want to see the resource tags for the capacity provider. If TAGS is specified, the tags are included in the response. If this field is omitted, tags aren't included in the response.

  • :max_results (Integer) —

    The maximum number of account setting results returned by DescribeCapacityProviders in paginated output. When this parameter is used, DescribeCapacityProviders only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another DescribeCapacityProviders request with the returned nextToken value. This value can be between 1 and 10. If this parameter is not used, then DescribeCapacityProviders returns up to 10 results and a nextToken value if applicable.

  • :next_token (String) —

    The nextToken value returned from a previous paginated DescribeCapacityProviders request where maxResults was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the nextToken value.

    This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

Returns:

See Also:



2697
2698
2699
2700
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 2697

def describe_capacity_providers(params = {}, options = {})
  req = build_request(:describe_capacity_providers, params)
  req.send_request(options)
end

#describe_clusters(params = {}) ⇒ Types::DescribeClustersResponse

Describes one or more of your clusters.

Examples:

Example: To describe a cluster


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

resp = client.describe_clusters({
  clusters: [
    "default", 
  ], 
})

resp.to_h outputs the following:
{
  clusters: [
    {
      cluster_arn: "arn:aws:ecs:us-east-1:aws_account_id:cluster/default", 
      cluster_name: "default", 
      status: "ACTIVE", 
    }, 
  ], 
  failures: [
  ], 
}

Request syntax with placeholder values


resp = client.describe_clusters({
  clusters: ["String"],
  include: ["ATTACHMENTS"], # accepts ATTACHMENTS, CONFIGURATIONS, SETTINGS, STATISTICS, TAGS
})

Response structure


resp.clusters #=> Array
resp.clusters[0].cluster_arn #=> String
resp.clusters[0].cluster_name #=> String
resp.clusters[0].configuration.execute_command_configuration.kms_key_id #=> String
resp.clusters[0].configuration.execute_command_configuration.logging #=> String, one of "NONE", "DEFAULT", "OVERRIDE"
resp.clusters[0].configuration.execute_command_configuration.log_configuration.cloud_watch_log_group_name #=> String
resp.clusters[0].configuration.execute_command_configuration.log_configuration.cloud_watch_encryption_enabled #=> Boolean
resp.clusters[0].configuration.execute_command_configuration.log_configuration.s3_bucket_name #=> String
resp.clusters[0].configuration.execute_command_configuration.log_configuration.s3_encryption_enabled #=> Boolean
resp.clusters[0].configuration.execute_command_configuration.log_configuration.s3_key_prefix #=> String
resp.clusters[0].status #=> String
resp.clusters[0].registered_container_instances_count #=> Integer
resp.clusters[0].running_tasks_count #=> Integer
resp.clusters[0].pending_tasks_count #=> Integer
resp.clusters[0].active_services_count #=> Integer
resp.clusters[0].statistics #=> Array
resp.clusters[0].statistics[0].name #=> String
resp.clusters[0].statistics[0].value #=> String
resp.clusters[0].tags #=> Array
resp.clusters[0].tags[0].key #=> String
resp.clusters[0].tags[0].value #=> String
resp.clusters[0].settings #=> Array
resp.clusters[0].settings[0].name #=> String, one of "containerInsights"
resp.clusters[0].settings[0].value #=> String
resp.clusters[0].capacity_providers #=> Array
resp.clusters[0].capacity_providers[0] #=> String
resp.clusters[0].default_capacity_provider_strategy #=> Array
resp.clusters[0].default_capacity_provider_strategy[0].capacity_provider #=> String
resp.clusters[0].default_capacity_provider_strategy[0].weight #=> Integer
resp.clusters[0].default_capacity_provider_strategy[0].base #=> Integer
resp.clusters[0].attachments #=> Array
resp.clusters[0].attachments[0].id #=> String
resp.clusters[0].attachments[0].type #=> String
resp.clusters[0].attachments[0].status #=> String
resp.clusters[0].attachments[0].details #=> Array
resp.clusters[0].attachments[0].details[0].name #=> String
resp.clusters[0].attachments[0].details[0].value #=> String
resp.clusters[0].attachments_status #=> String
resp.failures #=> Array
resp.failures[0].arn #=> String
resp.failures[0].reason #=> String
resp.failures[0].detail #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :clusters (Array<String>) —

    A list of up to 100 cluster names or full cluster Amazon Resource Name (ARN) entries. If you do not specify a cluster, the default cluster is assumed.

  • :include (Array<String>) —

    Determines whether to include additional information about the clusters in the response. If this field is omitted, this information isn't included.

    If ATTACHMENTS is specified, the attachments for the container instances or tasks within the cluster are included.

    If SETTINGS is specified, the settings for the cluster are included.

    If CONFIGURATIONS is specified, the configuration for the cluster is included.

    If STATISTICS is specified, the task and service count is included, separated by launch type.

    If TAGS is specified, the metadata tags associated with the cluster are included.

Returns:

See Also:



2813
2814
2815
2816
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 2813

def describe_clusters(params = {}, options = {})
  req = build_request(:describe_clusters, params)
  req.send_request(options)
end

#describe_container_instances(params = {}) ⇒ Types::DescribeContainerInstancesResponse

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

Examples:

Example: 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.

resp = client.describe_container_instances({
  cluster: "default", 
  container_instances: [
    "f2756532-8f13-4d53-87c9-aed50dc94cd7", 
  ], 
})

resp.to_h outputs the following:
{
  container_instances: [
    {
      agent_connected: true, 
      container_instance_arn: "arn:aws:ecs:us-east-1:012345678910:container-instance/f2756532-8f13-4d53-87c9-aed50dc94cd7", 
      ec2_instance_id: "i-807f3249", 
      pending_tasks_count: 0, 
      registered_resources: [
        {
          name: "CPU", 
          type: "INTEGER", 
          double_value: 0.0, 
          integer_value: 2048, 
          long_value: 0, 
        }, 
        {
          name: "MEMORY", 
          type: "INTEGER", 
          double_value: 0.0, 
          integer_value: 3768, 
          long_value: 0, 
        }, 
        {
          name: "PORTS", 
          type: "STRINGSET", 
          double_value: 0.0, 
          integer_value: 0, 
          long_value: 0, 
          string_set_value: [
            "2376", 
            "22", 
            "51678", 
            "2375", 
          ], 
        }, 
      ], 
      remaining_resources: [
        {
          name: "CPU", 
          type: "INTEGER", 
          double_value: 0.0, 
          integer_value: 1948, 
          long_value: 0, 
        }, 
        {
          name: "MEMORY", 
          type: "INTEGER", 
          double_value: 0.0, 
          integer_value: 3668, 
          long_value: 0, 
        }, 
        {
          name: "PORTS", 
          type: "STRINGSET", 
          double_value: 0.0, 
          integer_value: 0, 
          long_value: 0, 
          string_set_value: [
            "2376", 
            "22", 
            "80", 
            "51678", 
            "2375", 
          ], 
        }, 
      ], 
      running_tasks_count: 1, 
      status: "ACTIVE", 
    }, 
  ], 
  failures: [
  ], 
}

Request syntax with placeholder values


resp = client.describe_container_instances({
  cluster: "String",
  container_instances: ["String"], # required
  include: ["TAGS"], # accepts TAGS, CONTAINER_INSTANCE_HEALTH
})

Response structure


resp.container_instances #=> Array
resp.container_instances[0].container_instance_arn #=> String
resp.container_instances[0].ec2_instance_id #=> String
resp.container_instances[0].capacity_provider_name #=> String
resp.container_instances[0].version #=> Integer
resp.container_instances[0].version_info.agent_version #=> String
resp.container_instances[0].version_info.agent_hash #=> String
resp.container_instances[0].version_info.docker_version #=> String
resp.container_instances[0].remaining_resources #=> Array
resp.container_instances[0].remaining_resources[0].name #=> String
resp.container_instances[0].remaining_resources[0].type #=> String
resp.container_instances[0].remaining_resources[0].double_value #=> Float
resp.container_instances[0].remaining_resources[0].long_value #=> Integer
resp.container_instances[0].remaining_resources[0].integer_value #=> Integer
resp.container_instances[0].remaining_resources[0].string_set_value #=> Array
resp.container_instances[0].remaining_resources[0].string_set_value[0] #=> String
resp.container_instances[0].registered_resources #=> Array
resp.container_instances[0].registered_resources[0].name #=> String
resp.container_instances[0].registered_resources[0].type #=> String
resp.container_instances[0].registered_resources[0].double_value #=> Float
resp.container_instances[0].registered_resources[0].long_value #=> Integer
resp.container_instances[0].registered_resources[0].integer_value #=> Integer
resp.container_instances[0].registered_resources[0].string_set_value #=> Array
resp.container_instances[0].registered_resources[0].string_set_value[0] #=> String
resp.container_instances[0].status #=> String
resp.container_instances[0].status_reason #=> String
resp.container_instances[0].agent_connected #=> Boolean
resp.container_instances[0].running_tasks_count #=> Integer
resp.container_instances[0].pending_tasks_count #=> Integer
resp.container_instances[0].agent_update_status #=> String, one of "PENDING", "STAGING", "STAGED", "UPDATING", "UPDATED", "FAILED"
resp.container_instances[0].attributes #=> Array
resp.container_instances[0].attributes[0].name #=> String
resp.container_instances[0].attributes[0].value #=> String
resp.container_instances[0].attributes[0].target_type #=> String, one of "container-instance"
resp.container_instances[0].attributes[0].target_id #=> String
resp.container_instances[0].registered_at #=> Time
resp.container_instances[0].attachments #=> Array
resp.container_instances[0].attachments[0].id #=> String
resp.container_instances[0].attachments[0].type #=> String
resp.container_instances[0].attachments[0].status #=> String
resp.container_instances[0].attachments[0].details #=> Array
resp.container_instances[0].attachments[0].details[0].name #=> String
resp.container_instances[0].attachments[0].details[0].value #=> String
resp.container_instances[0].tags #=> Array
resp.container_instances[0].tags[0].key #=> String
resp.container_instances[0].tags[0].value #=> String
resp.container_instances[0].health_status.overall_status #=> String, one of "OK", "IMPAIRED", "INSUFFICIENT_DATA", "INITIALIZING"
resp.container_instances[0].health_status.details #=> Array
resp.container_instances[0].health_status.details[0].type #=> String, one of "CONTAINER_RUNTIME"
resp.container_instances[0].health_status.details[0].status #=> String, one of "OK", "IMPAIRED", "INSUFFICIENT_DATA", "INITIALIZING"
resp.container_instances[0].health_status.details[0].last_updated #=> Time
resp.container_instances[0].health_status.details[0].last_status_change #=> Time
resp.failures #=> Array
resp.failures[0].arn #=> String
resp.failures[0].reason #=> String
resp.failures[0].detail #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the container instances to describe. If you do not specify a cluster, the default cluster is assumed. This parameter is required if the container instance or container instances you are describing were launched in any cluster other than the default cluster.

  • :container_instances (required, Array<String>) —

    A list of up to 100 container instance IDs or full Amazon Resource Name (ARN) entries.

  • :include (Array<String>) —

    Specifies whether you want to see the resource tags for the container instance. If TAGS is specified, the tags are included in the response. If CONTAINER_INSTANCE_HEALTH is specified, the container instance health is included in the response. If this field is omitted, tags and container instance health status aren't included in the response.

Returns:

See Also:



3004
3005
3006
3007
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 3004

def describe_container_instances(params = {}, options = {})
  req = build_request(:describe_container_instances, params)
  req.send_request(options)
end

#describe_services(params = {}) ⇒ Types::DescribeServicesResponse

Describes the specified services running in your cluster.

The following waiters are defined for this operation (see #wait_until for detailed usage):

  • services_inactive
  • services_stable

Examples:

Example: To describe a service


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

resp = client.describe_services({
  services: [
    "ecs-simple-service", 
  ], 
})

resp.to_h outputs the following:
{
  failures: [
  ], 
  services: [
    {
      cluster_arn: "arn:aws:ecs:us-east-1:012345678910:cluster/default", 
      created_at: Time.parse("2016-08-29T16:25:52.130Z"), 
      deployment_configuration: {
        maximum_percent: 200, 
        minimum_healthy_percent: 100, 
      }, 
      deployments: [
        {
          created_at: Time.parse("2016-08-29T16:25:52.130Z"), 
          desired_count: 1, 
          id: "ecs-svc/9223370564341623665", 
          pending_count: 0, 
          running_count: 0, 
          status: "PRIMARY", 
          task_definition: "arn:aws:ecs:us-east-1:012345678910:task-definition/hello_world:6", 
          updated_at: Time.parse("2016-08-29T16:25:52.130Z"), 
        }, 
      ], 
      desired_count: 1, 
      events: [
        {
          created_at: Time.parse("2016-08-29T16:25:58.520Z"), 
          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.", # In this example, there is a service event that shows unavailable cluster resources.
        }, 
      ], 
      load_balancers: [
      ], 
      pending_count: 0, 
      running_count: 0, 
      service_arn: "arn:aws:ecs:us-east-1:012345678910:service/ecs-simple-service", 
      service_name: "ecs-simple-service", 
      status: "ACTIVE", 
      task_definition: "arn:aws:ecs:us-east-1:012345678910:task-definition/hello_world:6", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.describe_services({
  cluster: "String",
  services: ["String"], # required
  include: ["TAGS"], # accepts TAGS
})

Response structure


resp.services #=> Array
resp.services[0].service_arn #=> String
resp.services[0].service_name #=> String
resp.services[0].cluster_arn #=> String
resp.services[0].load_balancers #=> Array
resp.services[0].load_balancers[0].target_group_arn #=> String
resp.services[0].load_balancers[0].load_balancer_name #=> String
resp.services[0].load_balancers[0].container_name #=> String
resp.services[0].load_balancers[0].container_port #=> Integer
resp.services[0].service_registries #=> Array
resp.services[0].service_registries[0].registry_arn #=> String
resp.services[0].service_registries[0].port #=> Integer
resp.services[0].service_registries[0].container_name #=> String
resp.services[0].service_registries[0].container_port #=> Integer
resp.services[0].status #=> String
resp.services[0].desired_count #=> Integer
resp.services[0].running_count #=> Integer
resp.services[0].pending_count #=> Integer
resp.services[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.services[0].capacity_provider_strategy #=> Array
resp.services[0].capacity_provider_strategy[0].capacity_provider #=> String
resp.services[0].capacity_provider_strategy[0].weight #=> Integer
resp.services[0].capacity_provider_strategy[0].base #=> Integer
resp.services[0].platform_version #=> String
resp.services[0].platform_family #=> String
resp.services[0].task_definition #=> String
resp.services[0].deployment_configuration.deployment_circuit_breaker.enable #=> Boolean
resp.services[0].deployment_configuration.deployment_circuit_breaker.rollback #=> Boolean
resp.services[0].deployment_configuration.maximum_percent #=> Integer
resp.services[0].deployment_configuration.minimum_healthy_percent #=> Integer
resp.services[0].task_sets #=> Array
resp.services[0].task_sets[0].id #=> String
resp.services[0].task_sets[0].task_set_arn #=> String
resp.services[0].task_sets[0].service_arn #=> String
resp.services[0].task_sets[0].cluster_arn #=> String
resp.services[0].task_sets[0].started_by #=> String
resp.services[0].task_sets[0].external_id #=> String
resp.services[0].task_sets[0].status #=> String
resp.services[0].task_sets[0].task_definition #=> String
resp.services[0].task_sets[0].computed_desired_count #=> Integer
resp.services[0].task_sets[0].pending_count #=> Integer
resp.services[0].task_sets[0].running_count #=> Integer
resp.services[0].task_sets[0].created_at #=> Time
resp.services[0].task_sets[0].updated_at #=> Time
resp.services[0].task_sets[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.services[0].task_sets[0].capacity_provider_strategy #=> Array
resp.services[0].task_sets[0].capacity_provider_strategy[0].capacity_provider #=> String
resp.services[0].task_sets[0].capacity_provider_strategy[0].weight #=> Integer
resp.services[0].task_sets[0].capacity_provider_strategy[0].base #=> Integer
resp.services[0].task_sets[0].platform_version #=> String
resp.services[0].task_sets[0].platform_family #=> String
resp.services[0].task_sets[0].network_configuration.awsvpc_configuration.subnets #=> Array
resp.services[0].task_sets[0].network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.services[0].task_sets[0].network_configuration.awsvpc_configuration.security_groups #=> Array
resp.services[0].task_sets[0].network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.services[0].task_sets[0].network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.services[0].task_sets[0].load_balancers #=> Array
resp.services[0].task_sets[0].load_balancers[0].target_group_arn #=> String
resp.services[0].task_sets[0].load_balancers[0].load_balancer_name #=> String
resp.services[0].task_sets[0].load_balancers[0].container_name #=> String
resp.services[0].task_sets[0].load_balancers[0].container_port #=> Integer
resp.services[0].task_sets[0].service_registries #=> Array
resp.services[0].task_sets[0].service_registries[0].registry_arn #=> String
resp.services[0].task_sets[0].service_registries[0].port #=> Integer
resp.services[0].task_sets[0].service_registries[0].container_name #=> String
resp.services[0].task_sets[0].service_registries[0].container_port #=> Integer
resp.services[0].task_sets[0].scale.value #=> Float
resp.services[0].task_sets[0].scale.unit #=> String, one of "PERCENT"
resp.services[0].task_sets[0].stability_status #=> String, one of "STEADY_STATE", "STABILIZING"
resp.services[0].task_sets[0].stability_status_at #=> Time
resp.services[0].task_sets[0].tags #=> Array
resp.services[0].task_sets[0].tags[0].key #=> String
resp.services[0].task_sets[0].tags[0].value #=> String
resp.services[0].deployments #=> Array
resp.services[0].deployments[0].id #=> String
resp.services[0].deployments[0].status #=> String
resp.services[0].deployments[0].task_definition #=> String
resp.services[0].deployments[0].desired_count #=> Integer
resp.services[0].deployments[0].pending_count #=> Integer
resp.services[0].deployments[0].running_count #=> Integer
resp.services[0].deployments[0].failed_tasks #=> Integer
resp.services[0].deployments[0].created_at #=> Time
resp.services[0].deployments[0].updated_at #=> Time
resp.services[0].deployments[0].capacity_provider_strategy #=> Array
resp.services[0].deployments[0].capacity_provider_strategy[0].capacity_provider #=> String
resp.services[0].deployments[0].capacity_provider_strategy[0].weight #=> Integer
resp.services[0].deployments[0].capacity_provider_strategy[0].base #=> Integer
resp.services[0].deployments[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.services[0].deployments[0].platform_version #=> String
resp.services[0].deployments[0].platform_family #=> String
resp.services[0].deployments[0].network_configuration.awsvpc_configuration.subnets #=> Array
resp.services[0].deployments[0].network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.services[0].deployments[0].network_configuration.awsvpc_configuration.security_groups #=> Array
resp.services[0].deployments[0].network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.services[0].deployments[0].network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.services[0].deployments[0].rollout_state #=> String, one of "COMPLETED", "FAILED", "IN_PROGRESS"
resp.services[0].deployments[0].rollout_state_reason #=> String
resp.services[0].role_arn #=> String
resp.services[0].events #=> Array
resp.services[0].events[0].id #=> String
resp.services[0].events[0].created_at #=> Time
resp.services[0].events[0].message #=> String
resp.services[0].created_at #=> Time
resp.services[0].placement_constraints #=> Array
resp.services[0].placement_constraints[0].type #=> String, one of "distinctInstance", "memberOf"
resp.services[0].placement_constraints[0].expression #=> String
resp.services[0].placement_strategy #=> Array
resp.services[0].placement_strategy[0].type #=> String, one of "random", "spread", "binpack"
resp.services[0].placement_strategy[0].field #=> String
resp.services[0].network_configuration.awsvpc_configuration.subnets #=> Array
resp.services[0].network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.services[0].network_configuration.awsvpc_configuration.security_groups #=> Array
resp.services[0].network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.services[0].network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.services[0].health_check_grace_period_seconds #=> Integer
resp.services[0].scheduling_strategy #=> String, one of "REPLICA", "DAEMON"
resp.services[0].deployment_controller.type #=> String, one of "ECS", "CODE_DEPLOY", "EXTERNAL"
resp.services[0].tags #=> Array
resp.services[0].tags[0].key #=> String
resp.services[0].tags[0].value #=> String
resp.services[0].created_by #=> String
resp.services[0].enable_ecs_managed_tags #=> Boolean
resp.services[0].propagate_tags #=> String, one of "TASK_DEFINITION", "SERVICE", "NONE"
resp.services[0].enable_execute_command #=> Boolean
resp.failures #=> Array
resp.failures[0].arn #=> String
resp.failures[0].reason #=> String
resp.failures[0].detail #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN)the cluster that hosts the service to describe. If you do not specify a cluster, the default cluster is assumed. This parameter is required if the service or services you are describing were launched in any cluster other than the default cluster.

  • :services (required, Array<String>) —

    A list of services to describe. You may specify up to 10 services to describe in a single operation.

  • :include (Array<String>) —

    Determines whether you want to see the resource tags for the service. If TAGS is specified, the tags are included in the response. If this field is omitted, tags aren't included in the response.

Returns:

See Also:



3236
3237
3238
3239
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 3236

def describe_services(params = {}, options = {})
  req = build_request(:describe_services, params)
  req.send_request(options)
end

#describe_task_definition(params = {}) ⇒ Types::DescribeTaskDefinitionResponse

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.

You can only describe INACTIVE task definitions while an active task or service references them.

Examples:

Example: To describe a task definition


# This example provides a description of the specified task definition.

resp = client.describe_task_definition({
  task_definition: "hello_world:8", 
})

resp.to_h outputs the following:
{
  task_definition: {
    container_definitions: [
      {
        name: "wordpress", 
        cpu: 10, 
        environment: [
        ], 
        essential: true, 
        image: "wordpress", 
        links: [
          "mysql", 
        ], 
        memory: 500, 
        mount_points: [
        ], 
        port_mappings: [
          {
            container_port: 80, 
            host_port: 80, 
          }, 
        ], 
        volumes_from: [
        ], 
      }, 
      {
        name: "mysql", 
        cpu: 10, 
        environment: [
          {
            name: "MYSQL_ROOT_PASSWORD", 
            value: "password", 
          }, 
        ], 
        essential: true, 
        image: "mysql", 
        memory: 500, 
        mount_points: [
        ], 
        port_mappings: [
        ], 
        volumes_from: [
        ], 
      }, 
    ], 
    family: "hello_world", 
    revision: 8, 
    task_definition_arn: "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/hello_world:8", 
    volumes: [
    ], 
  }, 
}

Request syntax with placeholder values


resp = client.describe_task_definition({
  task_definition: "String", # required
  include: ["TAGS"], # accepts TAGS
})

Response structure


resp.task_definition.task_definition_arn #=> String
resp.task_definition.container_definitions #=> Array
resp.task_definition.container_definitions[0].name #=> String
resp.task_definition.container_definitions[0].image #=> String
resp.task_definition.container_definitions[0].repository_credentials.credentials_parameter #=> String
resp.task_definition.container_definitions[0].cpu #=> Integer
resp.task_definition.container_definitions[0].memory #=> Integer
resp.task_definition.container_definitions[0].memory_reservation #=> Integer
resp.task_definition.container_definitions[0].links #=> Array
resp.task_definition.container_definitions[0].links[0] #=> String
resp.task_definition.container_definitions[0].port_mappings #=> Array
resp.task_definition.container_definitions[0].port_mappings[0].container_port #=> Integer
resp.task_definition.container_definitions[0].port_mappings[0].host_port #=> Integer
resp.task_definition.container_definitions[0].port_mappings[0].protocol #=> String, one of "tcp", "udp"
resp.task_definition.container_definitions[0].essential #=> Boolean
resp.task_definition.container_definitions[0].entry_point #=> Array
resp.task_definition.container_definitions[0].entry_point[0] #=> String
resp.task_definition.container_definitions[0].command #=> Array
resp.task_definition.container_definitions[0].command[0] #=> String
resp.task_definition.container_definitions[0].environment #=> Array
resp.task_definition.container_definitions[0].environment[0].name #=> String
resp.task_definition.container_definitions[0].environment[0].value #=> String
resp.task_definition.container_definitions[0].environment_files #=> Array
resp.task_definition.container_definitions[0].environment_files[0].value #=> String
resp.task_definition.container_definitions[0].environment_files[0].type #=> String, one of "s3"
resp.task_definition.container_definitions[0].mount_points #=> Array
resp.task_definition.container_definitions[0].mount_points[0].source_volume #=> String
resp.task_definition.container_definitions[0].mount_points[0].container_path #=> String
resp.task_definition.container_definitions[0].mount_points[0].read_only #=> Boolean
resp.task_definition.container_definitions[0].volumes_from #=> Array
resp.task_definition.container_definitions[0].volumes_from[0].source_container #=> String
resp.task_definition.container_definitions[0].volumes_from[0].read_only #=> Boolean
resp.task_definition.container_definitions[0].linux_parameters.capabilities.add #=> Array
resp.task_definition.container_definitions[0].linux_parameters.capabilities.add[0] #=> String
resp.task_definition.container_definitions[0].linux_parameters.capabilities.drop #=> Array
resp.task_definition.container_definitions[0].linux_parameters.capabilities.drop[0] #=> String
resp.task_definition.container_definitions[0].linux_parameters.devices #=> Array
resp.task_definition.container_definitions[0].linux_parameters.devices[0].host_path #=> String
resp.task_definition.container_definitions[0].linux_parameters.devices[0].container_path #=> String
resp.task_definition.container_definitions[0].linux_parameters.devices[0].permissions #=> Array
resp.task_definition.container_definitions[0].linux_parameters.devices[0].permissions[0] #=> String, one of "read", "write", "mknod"
resp.task_definition.container_definitions[0].linux_parameters.init_process_enabled #=> Boolean
resp.task_definition.container_definitions[0].linux_parameters.shared_memory_size #=> Integer
resp.task_definition.container_definitions[0].linux_parameters.tmpfs #=> Array
resp.task_definition.container_definitions[0].linux_parameters.tmpfs[0].container_path #=> String
resp.task_definition.container_definitions[0].linux_parameters.tmpfs[0].size #=> Integer
resp.task_definition.container_definitions[0].linux_parameters.tmpfs[0].mount_options #=> Array
resp.task_definition.container_definitions[0].linux_parameters.tmpfs[0].mount_options[0] #=> String
resp.task_definition.container_definitions[0].linux_parameters.max_swap #=> Integer
resp.task_definition.container_definitions[0].linux_parameters.swappiness #=> Integer
resp.task_definition.container_definitions[0].secrets #=> Array
resp.task_definition.container_definitions[0].secrets[0].name #=> String
resp.task_definition.container_definitions[0].secrets[0].value_from #=> String
resp.task_definition.container_definitions[0].depends_on #=> Array
resp.task_definition.container_definitions[0].depends_on[0].container_name #=> String
resp.task_definition.container_definitions[0].depends_on[0].condition #=> String, one of "START", "COMPLETE", "SUCCESS", "HEALTHY"
resp.task_definition.container_definitions[0].start_timeout #=> Integer
resp.task_definition.container_definitions[0].stop_timeout #=> Integer
resp.task_definition.container_definitions[0].hostname #=> String
resp.task_definition.container_definitions[0].user #=> String
resp.task_definition.container_definitions[0].working_directory #=> String
resp.task_definition.container_definitions[0].disable_networking #=> Boolean
resp.task_definition.container_definitions[0].privileged #=> Boolean
resp.task_definition.container_definitions[0].readonly_root_filesystem #=> Boolean
resp.task_definition.container_definitions[0].dns_servers #=> Array
resp.task_definition.container_definitions[0].dns_servers[0] #=> String
resp.task_definition.container_definitions[0].dns_search_domains #=> Array
resp.task_definition.container_definitions[0].dns_search_domains[0] #=> String
resp.task_definition.container_definitions[0].extra_hosts #=> Array
resp.task_definition.container_definitions[0].extra_hosts[0].hostname #=> String
resp.task_definition.container_definitions[0].extra_hosts[0].ip_address #=> String
resp.task_definition.container_definitions[0].docker_security_options #=> Array
resp.task_definition.container_definitions[0].docker_security_options[0] #=> String
resp.task_definition.container_definitions[0].interactive #=> Boolean
resp.task_definition.container_definitions[0].pseudo_terminal #=> Boolean
resp.task_definition.container_definitions[0].docker_labels #=> Hash
resp.task_definition.container_definitions[0].docker_labels["String"] #=> String
resp.task_definition.container_definitions[0].ulimits #=> Array
resp.task_definition.container_definitions[0].ulimits[0].name #=> String, one of "core", "cpu", "data", "fsize", "locks", "memlock", "msgqueue", "nice", "nofile", "nproc", "rss", "rtprio", "rttime", "sigpending", "stack"
resp.task_definition.container_definitions[0].ulimits[0].soft_limit #=> Integer
resp.task_definition.container_definitions[0].ulimits[0].hard_limit #=> Integer
resp.task_definition.container_definitions[0].log_configuration.log_driver #=> String, one of "json-file", "syslog", "journald", "gelf", "fluentd", "awslogs", "splunk", "awsfirelens"
resp.task_definition.container_definitions[0].log_configuration.options #=> Hash
resp.task_definition.container_definitions[0].log_configuration.options["String"] #=> String
resp.task_definition.container_definitions[0].log_configuration.secret_options #=> Array
resp.task_definition.container_definitions[0].log_configuration.secret_options[0].name #=> String
resp.task_definition.container_definitions[0].log_configuration.secret_options[0].value_from #=> String
resp.task_definition.container_definitions[0].health_check.command #=> Array
resp.task_definition.container_definitions[0].health_check.command[0] #=> String
resp.task_definition.container_definitions[0].health_check.interval #=> Integer
resp.task_definition.container_definitions[0].health_check.timeout #=> Integer
resp.task_definition.container_definitions[0].health_check.retries #=> Integer
resp.task_definition.container_definitions[0].health_check.start_period #=> Integer
resp.task_definition.container_definitions[0].system_controls #=> Array
resp.task_definition.container_definitions[0].system_controls[0].namespace #=> String
resp.task_definition.container_definitions[0].system_controls[0].value #=> String
resp.task_definition.container_definitions[0].resource_requirements #=> Array
resp.task_definition.container_definitions[0].resource_requirements[0].value #=> String
resp.task_definition.container_definitions[0].resource_requirements[0].type #=> String, one of "GPU", "InferenceAccelerator"
resp.task_definition.container_definitions[0].firelens_configuration.type #=> String, one of "fluentd", "fluentbit"
resp.task_definition.container_definitions[0].firelens_configuration.options #=> Hash
resp.task_definition.container_definitions[0].firelens_configuration.options["String"] #=> String
resp.task_definition.family #=> String
resp.task_definition.task_role_arn #=> String
resp.task_definition.execution_role_arn #=> String
resp.task_definition.network_mode #=> String, one of "bridge", "host", "awsvpc", "none"
resp.task_definition.revision #=> Integer
resp.task_definition.volumes #=> Array
resp.task_definition.volumes[0].name #=> String
resp.task_definition.volumes[0].host.source_path #=> String
resp.task_definition.volumes[0].docker_volume_configuration.scope #=> String, one of "task", "shared"
resp.task_definition.volumes[0].docker_volume_configuration.autoprovision #=> Boolean
resp.task_definition.volumes[0].docker_volume_configuration.driver #=> String
resp.task_definition.volumes[0].docker_volume_configuration.driver_opts #=> Hash
resp.task_definition.volumes[0].docker_volume_configuration.driver_opts["String"] #=> String
resp.task_definition.volumes[0].docker_volume_configuration.labels #=> Hash
resp.task_definition.volumes[0].docker_volume_configuration.labels["String"] #=> String
resp.task_definition.volumes[0].efs_volume_configuration.file_system_id #=> String
resp.task_definition.volumes[0].efs_volume_configuration.root_directory #=> String
resp.task_definition.volumes[0].efs_volume_configuration.transit_encryption #=> String, one of "ENABLED", "DISABLED"
resp.task_definition.volumes[0].efs_volume_configuration.transit_encryption_port #=> Integer
resp.task_definition.volumes[0].efs_volume_configuration.authorization_config.access_point_id #=> String
resp.task_definition.volumes[0].efs_volume_configuration.authorization_config.iam #=> String, one of "ENABLED", "DISABLED"
resp.task_definition.volumes[0].fsx_windows_file_server_volume_configuration.file_system_id #=> String
resp.task_definition.volumes[0].fsx_windows_file_server_volume_configuration.root_directory #=> String
resp.task_definition.volumes[0].fsx_windows_file_server_volume_configuration.authorization_config.credentials_parameter #=> String
resp.task_definition.volumes[0].fsx_windows_file_server_volume_configuration.authorization_config.domain #=> String
resp.task_definition.status #=> String, one of "ACTIVE", "INACTIVE"
resp.task_definition.requires_attributes #=> Array
resp.task_definition.requires_attributes[0].name #=> String
resp.task_definition.requires_attributes[0].value #=> String
resp.task_definition.requires_attributes[0].target_type #=> String, one of "container-instance"
resp.task_definition.requires_attributes[0].target_id #=> String
resp.task_definition.placement_constraints #=> Array
resp.task_definition.placement_constraints[0].type #=> String, one of "memberOf"
resp.task_definition.placement_constraints[0].expression #=> String
resp.task_definition.compatibilities #=> Array
resp.task_definition.compatibilities[0] #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.task_definition.runtime_platform.cpu_architecture #=> String, one of "X86_64", "ARM64"
resp.task_definition.runtime_platform.operating_system_family #=> String, one of "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_20H2_CORE", "LINUX"
resp.task_definition.requires_compatibilities #=> Array
resp.task_definition.requires_compatibilities[0] #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.task_definition.cpu #=> String
resp.task_definition.memory #=> String
resp.task_definition.inference_accelerators #=> Array
resp.task_definition.inference_accelerators[0].device_name #=> String
resp.task_definition.inference_accelerators[0].device_type #=> String
resp.task_definition.pid_mode #=> String, one of "host", "task"
resp.task_definition.ipc_mode #=> String, one of "host", "task", "none"
resp.task_definition.proxy_configuration.type #=> String, one of "APPMESH"
resp.task_definition.proxy_configuration.container_name #=> String
resp.task_definition.proxy_configuration.properties #=> Array
resp.task_definition.proxy_configuration.properties[0].name #=> String
resp.task_definition.proxy_configuration.properties[0].value #=> String
resp.task_definition.registered_at #=> Time
resp.task_definition.deregistered_at #=> Time
resp.task_definition.registered_by #=> String
resp.task_definition.ephemeral_storage.size_in_gi_b #=> Integer
resp.tags #=> Array
resp.tags[0].key #=> String
resp.tags[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :task_definition (required, String) —

    The family for the latest ACTIVE revision, family and revision (family:revision) for a specific revision in the family, or full Amazon Resource Name (ARN) of the task definition to describe.

  • :include (Array<String>) —

    Determines whether to see the resource tags for the task definition. If TAGS is specified, the tags are included in the response. If this field is omitted, tags aren't included in the response.

Returns:

See Also:



3504
3505
3506
3507
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 3504

def describe_task_definition(params = {}, options = {})
  req = build_request(:describe_task_definition, params)
  req.send_request(options)
end

#describe_task_sets(params = {}) ⇒ Types::DescribeTaskSetsResponse

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.

Examples:

Request syntax with placeholder values


resp = client.describe_task_sets({
  cluster: "String", # required
  service: "String", # required
  task_sets: ["String"],
  include: ["TAGS"], # accepts TAGS
})

Response structure


resp.task_sets #=> Array
resp.task_sets[0].id #=> String
resp.task_sets[0].task_set_arn #=> String
resp.task_sets[0].service_arn #=> String
resp.task_sets[0].cluster_arn #=> String
resp.task_sets[0].started_by #=> String
resp.task_sets[0].external_id #=> String
resp.task_sets[0].status #=> String
resp.task_sets[0].task_definition #=> String
resp.task_sets[0].computed_desired_count #=> Integer
resp.task_sets[0].pending_count #=> Integer
resp.task_sets[0].running_count #=> Integer
resp.task_sets[0].created_at #=> Time
resp.task_sets[0].updated_at #=> Time
resp.task_sets[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.task_sets[0].capacity_provider_strategy #=> Array
resp.task_sets[0].capacity_provider_strategy[0].capacity_provider #=> String
resp.task_sets[0].capacity_provider_strategy[0].weight #=> Integer
resp.task_sets[0].capacity_provider_strategy[0].base #=> Integer
resp.task_sets[0].platform_version #=> String
resp.task_sets[0].platform_family #=> String
resp.task_sets[0].network_configuration.awsvpc_configuration.subnets #=> Array
resp.task_sets[0].network_configuration.awsvpc_configuration.subnets[0] #=> String
resp.task_sets[0].network_configuration.awsvpc_configuration.security_groups #=> Array
resp.task_sets[0].network_configuration.awsvpc_configuration.security_groups[0] #=> String
resp.task_sets[0].network_configuration.awsvpc_configuration.assign_public_ip #=> String, one of "ENABLED", "DISABLED"
resp.task_sets[0].load_balancers #=> Array
resp.task_sets[0].load_balancers[0].target_group_arn #=> String
resp.task_sets[0].load_balancers[0].load_balancer_name #=> String
resp.task_sets[0].load_balancers[0].container_name #=> String
resp.task_sets[0].load_balancers[0].container_port #=> Integer
resp.task_sets[0].service_registries #=> Array
resp.task_sets[0].service_registries[0].registry_arn #=> String
resp.task_sets[0].service_registries[0].port #=> Integer
resp.task_sets[0].service_registries[0].container_name #=> String
resp.task_sets[0].service_registries[0].container_port #=> Integer
resp.task_sets[0].scale.value #=> Float
resp.task_sets[0].scale.unit #=> String, one of "PERCENT"
resp.task_sets[0].stability_status #=> String, one of "STEADY_STATE", "STABILIZING"
resp.task_sets[0].stability_status_at #=> Time
resp.task_sets[0].tags #=> Array
resp.task_sets[0].tags[0].key #=> String
resp.task_sets[0].tags[0].value #=> String
resp.failures #=> Array
resp.failures[0].arn #=> String
resp.failures[0].reason #=> String
resp.failures[0].detail #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (required, String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the service that the task sets exist in.

  • :service (required, String) —

    The short name or full Amazon Resource Name (ARN) of the service that the task sets exist in.

  • :task_sets (Array<String>) —

    The ID or full Amazon Resource Name (ARN) of task sets to describe.

  • :include (Array<String>) —

    Specifies whether to see the resource tags for the task set. If TAGS is specified, the tags are included in the response. If this field is omitted, tags aren't included in the response.

Returns:

See Also:



3602
3603
3604
3605
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 3602

def describe_task_sets(params = {}, options = {})
  req = build_request(:describe_task_sets, params)
  req.send_request(options)
end

#describe_tasks(params = {}) ⇒ Types::DescribeTasksResponse

Describes a specified task or tasks.

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

The following waiters are defined for this operation (see #wait_until for detailed usage):

  • tasks_running
  • tasks_stopped

Examples:

Example: To describe a task


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

resp = client.describe_tasks({
  tasks: [
    "c5cba4eb-5dad-405e-96db-71ef8eefe6a8", 
  ], 
})

resp.to_h outputs the following:
{
  failures: [
  ], 
  tasks: [
    {
      cluster_arn: "arn:aws:ecs:<region>:<aws_account_id>:cluster/default", 
      container_instance_arn: "arn:aws:ecs:<region>:<aws_account_id>:container-instance/18f9eda5-27d7-4c19-b133-45adc516e8fb", 
      containers: [
        {
          name: "ecs-demo", 
          container_arn: "arn:aws:ecs:<region>:<aws_account_id>:container/7c01765b-c588-45b3-8290-4ba38bd6c5a6", 
          last_status: "RUNNING", 
          network_bindings: [
            {
              bind_ip: "0.0.0.0", 
              container_port: 80, 
              host_port: 80, 
            }, 
          ], 
          task_arn: "arn:aws:ecs:<region>:<aws_account_id>:task/c5cba4eb-5dad-405e-96db-71ef8eefe6a8", 
        }, 
      ], 
      desired_status: "RUNNING", 
      last_status: "RUNNING", 
      overrides: {
        container_overrides: [
          {
            name: "ecs-demo", 
          }, 
        ], 
      }, 
      started_by: "ecs-svc/9223370608528463088", 
      task_arn: "arn:aws:ecs:<region>:<aws_account_id>:task/c5cba4eb-5dad-405e-96db-71ef8eefe6a8", 
      task_definition_arn: "arn:aws:ecs:<region>:<aws_account_id>:task-definition/amazon-ecs-sample:1", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.describe_tasks({
  cluster: "String",
  tasks: ["String"], # required
  include: ["TAGS"], # accepts TAGS
})

Response structure


resp.tasks #=> Array
resp.tasks[0].attachments #=> Array
resp.tasks[0].attachments[0].id #=> String
resp.tasks[0].attachments[0].type #=> String
resp.tasks[0].attachments[0].status #=> String
resp.tasks[0].attachments[0].details #=> Array
resp.tasks[0].attachments[0].details[0].name #=> String
resp.tasks[0].attachments[0].details[0].value #=> String
resp.tasks[0].attributes #=> Array
resp.tasks[0].attributes[0].name #=> String
resp.tasks[0].attributes[0].value #=> String
resp.tasks[0].attributes[0].target_type #=> String, one of "container-instance"
resp.tasks[0].attributes[0].target_id #=> String
resp.tasks[0].availability_zone #=> String
resp.tasks[0].capacity_provider_name #=> String
resp.tasks[0].cluster_arn #=> String
resp.tasks[0].connectivity #=> String, one of "CONNECTED", "DISCONNECTED"
resp.tasks[0].connectivity_at #=> Time
resp.tasks[0].container_instance_arn #=> String
resp.tasks[0].containers #=> Array
resp.tasks[0].containers[0].container_arn #=> String
resp.tasks[0].containers[0].task_arn #=> String
resp.tasks[0].containers[0].name #=> String
resp.tasks[0].containers[0].image #=> String
resp.tasks[0].containers[0].image_digest #=> String
resp.tasks[0].containers[0].runtime_id #=> String
resp.tasks[0].containers[0].last_status #=> String
resp.tasks[0].containers[0].exit_code #=> Integer
resp.tasks[0].containers[0].reason #=> String
resp.tasks[0].containers[0].network_bindings #=> Array
resp.tasks[0].containers[0].network_bindings[0].bind_ip #=> String
resp.tasks[0].containers[0].network_bindings[0].container_port #=> Integer
resp.tasks[0].containers[0].network_bindings[0].host_port #=> Integer
resp.tasks[0].containers[0].network_bindings[0].protocol #=> String, one of "tcp", "udp"
resp.tasks[0].containers[0].network_interfaces #=> Array
resp.tasks[0].containers[0].network_interfaces[0].attachment_id #=> String
resp.tasks[0].containers[0].network_interfaces[0].private_ipv_4_address #=> String
resp.tasks[0].containers[0].network_interfaces[0].ipv6_address #=> String
resp.tasks[0].containers[0].health_status #=> String, one of "HEALTHY", "UNHEALTHY", "UNKNOWN"
resp.tasks[0].containers[0].managed_agents #=> Array
resp.tasks[0].containers[0].managed_agents[0].last_started_at #=> Time
resp.tasks[0].containers[0].managed_agents[0].name #=> String, one of "ExecuteCommandAgent"
resp.tasks[0].containers[0].managed_agents[0].reason #=> String
resp.tasks[0].containers[0].managed_agents[0].last_status #=> String
resp.tasks[0].containers[0].cpu #=> String
resp.tasks[0].containers[0].memory #=> String
resp.tasks[0].containers[0].memory_reservation #=> String
resp.tasks[0].containers[0].gpu_ids #=> Array
resp.tasks[0].containers[0].gpu_ids[0] #=> String
resp.tasks[0].cpu #=> String
resp.tasks[0].created_at #=> Time
resp.tasks[0].desired_status #=> String
resp.tasks[0].enable_execute_command #=> Boolean
resp.tasks[0].execution_stopped_at #=> Time
resp.tasks[0].group #=> String
resp.tasks[0].health_status #=> String, one of "HEALTHY", "UNHEALTHY", "UNKNOWN"
resp.tasks[0].inference_accelerators #=> Array
resp.tasks[0].inference_accelerators[0].device_name #=> String
resp.tasks[0].inference_accelerators[0].device_type #=> String
resp.tasks[0].last_status #=> String
resp.tasks[0].launch_type #=> String, one of "EC2", "FARGATE", "EXTERNAL"
resp.tasks[0].memory #=> String
resp.tasks[0].overrides.container_overrides #=> Array
resp.tasks[0].overrides.container_overrides[0].name #=> String
resp.tasks[0].overrides.container_overrides[0].command #=> Array
resp.tasks[0].overrides.container_overrides[0].command[0] #=> String
resp.tasks[0].overrides.container_overrides[0].environment #=> Array
resp.tasks[0].overrides.container_overrides[0].environment[0].name #=> String
resp.tasks[0].overrides.container_overrides[0].environment[0].value #=> String
resp.tasks[0].overrides.container_overrides[0].environment_files #=> Array
resp.tasks[0].overrides.container_overrides[0].environment_files[0].value #=> String
resp.tasks[0].overrides.container_overrides[0].environment_files[0].type #=> String, one of "s3"
resp.tasks[0].overrides.container_overrides[0].cpu #=> Integer
resp.tasks[0].overrides.container_overrides[0].memory #=> Integer
resp.tasks[0].overrides.container_overrides[0].memory_reservation #=> Integer
resp.tasks[0].overrides.container_overrides[0].resource_requirements #=> Array
resp.tasks[0].overrides.container_overrides[0].resource_requirements[0].value #=> String
resp.tasks[0].overrides.container_overrides[0].resource_requirements[0].type #=> String, one of "GPU", "InferenceAccelerator"
resp.tasks[0].overrides.cpu #=> String
resp.tasks[0].overrides.inference_accelerator_overrides #=> Array
resp.tasks[0].overrides.inference_accelerator_overrides[0].device_name #=> String
resp.tasks[0].overrides.inference_accelerator_overrides[0].device_type #=> String
resp.tasks[0].overrides.execution_role_arn #=> String
resp.tasks[0].overrides.memory #=> String
resp.tasks[0].overrides.task_role_arn #=> String
resp.tasks[0].overrides.ephemeral_storage.size_in_gi_b #=> Integer
resp.tasks[0].platform_version #=> String
resp.tasks[0].platform_family #=> String
resp.tasks[0].pull_started_at #=> Time
resp.tasks[0].pull_stopped_at #=> Time
resp.tasks[0].started_at #=> Time
resp.tasks[0].started_by #=> String
resp.tasks[0].stop_code #=> String, one of "TaskFailedToStart", "EssentialContainerExited", "UserInitiated"
resp.tasks[0].stopped_at #=> Time
resp.tasks[0].stopped_reason #=> String
resp.tasks[0].stopping_at #=> Time
resp.tasks[0].tags #=> Array
resp.tasks[0].tags[0].key #=> String
resp.tasks[0].tags[0].value #=> String
resp.tasks[0].task_arn #=> String
resp.tasks[0].task_definition_arn #=> String
resp.tasks[0].version #=> Integer
resp.tasks[0].ephemeral_storage.size_in_gi_b #=> Integer
resp.failures #=> Array
resp.failures[0].arn #=> String
resp.failures[0].reason #=> String
resp.failures[0].detail #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the task or tasks to describe. If you do not specify a cluster, the default cluster is assumed. This parameter is required if the task or tasks you are describing were launched in any cluster other than the default cluster.

  • :tasks (required, Array<String>) —

    A list of up to 100 task IDs or full ARN entries.

  • :include (Array<String>) —

    Specifies whether you want to see the resource tags for the task. If TAGS is specified, the tags are included in the response. If this field is omitted, tags aren't included in the response.

Returns:

See Also:



3810
3811
3812
3813
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 3810

def describe_tasks(params = {}, options = {})
  req = build_request(:describe_tasks, params)
  req.send_request(options)
end

#discover_poll_endpoint(params = {}) ⇒ Types::DiscoverPollEndpointResponse

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.

Examples:

Request syntax with placeholder values


resp = client.discover_poll_endpoint({
  container_instance: "String",
  cluster: "String",
})

Response structure


resp.endpoint #=> String
resp.telemetry_endpoint #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :container_instance (String) —

    The container instance ID or full ARN of the container instance. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that the container instance belongs to.

Returns:

See Also:



3856
3857
3858
3859
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 3856

def discover_poll_endpoint(params = {}, options = {})
  req = build_request(:discover_poll_endpoint, params)
  req.send_request(options)
end

#execute_command(params = {}) ⇒ Types::ExecuteCommandResponse

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 recevie an AccessDeniedException when there is a mismatch between the condition key value and the corresponding parameter value.

Examples:

Request syntax with placeholder values


resp = client.execute_command({
  cluster: "String",
  container: "String",
  command: "String", # required
  interactive: false, # required
  task: "String", # required
})

Response structure


resp.cluster_arn #=> String
resp.container_arn #=> String
resp.container_name #=> String
resp.interactive #=> Boolean
resp.session.session_id #=> String
resp.session.stream_url #=> String
resp.session.token_value #=> String
resp.task_arn #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The Amazon Resource Name (ARN) or short name of the cluster the task is running in. If you do not specify a cluster, the default cluster is assumed.

  • :container (String) —

    The name of the container to execute the command on. A container name only needs to be specified for tasks containing multiple containers.

  • :command (required, String) —

    The command to run on the container.

  • :interactive (required, Boolean) —

    Use this flag to run your command in interactive mode.

  • :task (required, String) —

    The Amazon Resource Name (ARN) or ID of the task the container is part of.

Returns:

See Also:



3922
3923
3924
3925
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 3922

def execute_command(params = {}, options = {})
  req = build_request(:execute_command, params)
  req.send_request(options)
end

#list_account_settings(params = {}) ⇒ Types::ListAccountSettingsResponse

Lists the account settings for a specified principal.

The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.

Examples:

Example: To view your effective account settings


# This example displays the effective account settings for your account.

resp = client.({
  effective_settings: true, 
})

resp.to_h outputs the following:
{
  settings: [
    {
      name: "containerInstanceLongArnFormat", 
      value: "disabled", 
      principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
    }, 
    {
      name: "serviceLongArnFormat", 
      value: "enabled", 
      principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
    }, 
    {
      name: "taskLongArnFormat", 
      value: "disabled", 
      principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
    }, 
  ], 
}

Example: 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.

resp = client.({
  effective_settings: true, 
  principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
})

resp.to_h outputs the following:
{
  settings: [
    {
      name: "containerInstanceLongArnFormat", 
      value: "disabled", 
      principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
    }, 
    {
      name: "serviceLongArnFormat", 
      value: "enabled", 
      principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
    }, 
    {
      name: "taskLongArnFormat", 
      value: "disabled", 
      principal_arn: "arn:aws:iam::<aws_account_id>:user/principalName", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.({
  name: "serviceLongArnFormat", # accepts serviceLongArnFormat, taskLongArnFormat, containerInstanceLongArnFormat, awsvpcTrunking, containerInsights
  value: "String",
  principal_arn: "String",
  effective_settings: false,
  next_token: "String",
  max_results: 1,
})

Response structure


resp.settings #=> Array
resp.settings[0].name #=> String, one of "serviceLongArnFormat", "taskLongArnFormat", "containerInstanceLongArnFormat", "awsvpcTrunking", "containerInsights"
resp.settings[0].value #=> String
resp.settings[0].principal_arn #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :name (String) —

    The name of the account setting you want to list the settings for.

  • :value (String) —

    The value of the account settings to filter results with. You must also specify an account setting name to use this parameter.

  • :principal_arn (String) —

    The ARN of the principal, which can be an IAM user, IAM role, or the root user. If this field is omitted, the account settings are listed only for the authenticated user.

    Federated users assume the account setting of the root user and can't have explicit account settings set for them.

  • :effective_settings (Boolean) —

    Determines whether to return the effective settings. If true, the account settings for the root user or the default setting for the principalArn are returned. If false, the account settings for the principalArn are returned if they're set. Otherwise, no account settings are returned.

  • :next_token (String) —

    The nextToken value returned from a ListAccountSettings request indicating that more results are available to fulfill the request and further calls will be needed. If maxResults was provided, it's possible the number of results to be fewer than maxResults.

    This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

  • :max_results (Integer) —

    The maximum number of account setting results returned by ListAccountSettings in paginated output. When this parameter is used, ListAccountSettings only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListAccountSettings request with the returned nextToken value. This value can be between 1 and 10. If this parameter isn't used, then ListAccountSettings returns up to 10 results and a nextToken value if applicable.

Returns:

See Also:



4066
4067
4068
4069
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 4066

def (params = {}, options = {})
  req = build_request(:list_account_settings, params)
  req.send_request(options)
end

#list_attributes(params = {}) ⇒ Types::ListAttributesResponse

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).

The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.

Examples:

Request syntax with placeholder values


resp = client.list_attributes({
  cluster: "String",
  target_type: "container-instance", # required, accepts container-instance
  attribute_name: "String",
  attribute_value: "String",
  next_token: "String",
  max_results: 1,
})

Response structure


resp.attributes #=> Array
resp.attributes[0].name #=> String
resp.attributes[0].value #=> String
resp.attributes[0].target_type #=> String, one of "container-instance"
resp.attributes[0].target_id #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster to list attributes. If you do not specify a cluster, the default cluster is assumed.

  • :target_type (required, String) —

    The type of the target to list attributes with.

  • :attribute_name (String) —

    The name of the attribute to filter the results with.

  • :attribute_value (String) —

    The value of the attribute to filter results with. You must also specify an attribute name to use this parameter.

  • :next_token (String) —

    The nextToken value returned from a ListAttributes request indicating that more results are available to fulfill the request and further calls are needed. If maxResults was provided, it's possible the number of results to be fewer than maxResults.

    This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

  • :max_results (Integer) —

    The maximum number of cluster results that ListAttributes returned in paginated output. When this parameter is used, ListAttributes only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListAttributes request with the returned nextToken value. This value can be between 1 and 100. If this parameter isn't used, then ListAttributes returns up to 100 results and a nextToken value if applicable.

Returns:

See Also:



4148
4149
4150
4151
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 4148

def list_attributes(params = {}, options = {})
  req = build_request(:list_attributes, params)
  req.send_request(options)
end

#list_clusters(params = {}) ⇒ Types::ListClustersResponse

Returns a list of existing clusters.

The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.

Examples:

Example: To list your available clusters


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

resp = client.list_clusters({
})

resp.to_h outputs the following:
{
  cluster_arns: [
    "arn:aws:ecs:us-east-1:<aws_account_id>:cluster/test", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:cluster/default", 
  ], 
}

Request syntax with placeholder values


resp = client.list_clusters({
  next_token: "String",
  max_results: 1,
})

Response structure


resp.cluster_arns #=> Array
resp.cluster_arns[0] #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :next_token (String) —

    The nextToken value returned from a ListClusters request indicating that more results are available to fulfill the request and further calls are needed. If maxResults was provided, it's possible the number of results to be fewer than maxResults.

    This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

  • :max_results (Integer) —

    The maximum number of cluster results that ListClusters returned in paginated output. When this parameter is used, ListClusters only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListClusters request with the returned nextToken value. This value can be between 1 and 100. If this parameter isn't used, then ListClusters returns up to 100 results and a nextToken value if applicable.

Returns:

See Also:



4217
4218
4219
4220
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 4217

def list_clusters(params = {}, options = {})
  req = build_request(:list_clusters, params)
  req.send_request(options)
end

#list_container_instances(params = {}) ⇒ Types::ListContainerInstancesResponse

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.

The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.

Examples:

Example: 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.

resp = client.list_container_instances({
  cluster: "default", 
})

resp.to_h outputs the following:
{
  container_instance_arns: [
    "arn:aws:ecs:us-east-1:<aws_account_id>:container-instance/f6bbb147-5370-4ace-8c73-c7181ded911f", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:container-instance/ffe3d344-77e2-476c-a4d0-bf560ad50acb", 
  ], 
}

Request syntax with placeholder values


resp = client.list_container_instances({
  cluster: "String",
  filter: "String",
  next_token: "String",
  max_results: 1,
  status: "ACTIVE", # accepts ACTIVE, DRAINING, REGISTERING, DEREGISTERING, REGISTRATION_FAILED
})

Response structure


resp.container_instance_arns #=> Array
resp.container_instance_arns[0] #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the container instances to list. If you do not specify a cluster, the default cluster is assumed.

  • :filter (String) —

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

  • :next_token (String) —

    The nextToken value returned from a ListContainerInstances request indicating that more results are available to fulfill the request and further calls are needed. If maxResults was provided, it's possible the number of results to be fewer than maxResults.

    This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

  • :max_results (Integer) —

    The maximum number of container instance results that ListContainerInstances returned in paginated output. When this parameter is used, ListContainerInstances only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListContainerInstances request with the returned nextToken value. This value can be between 1 and 100. If this parameter isn't used, then ListContainerInstances returns up to 100 results and a nextToken value if applicable.

  • :status (String) —

    Filters the container instances by status. For example, if you specify the DRAINING status, the results include only container instances that have been set to DRAINING using UpdateContainerInstancesState. If you don't specify this parameter, the default is to include container instances set to all states other than INACTIVE.

Returns:

See Also:



4321
4322
4323
4324
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 4321

def list_container_instances(params = {}, options = {})
  req = build_request(:list_container_instances, params)
  req.send_request(options)
end

#list_services(params = {}) ⇒ Types::ListServicesResponse

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

The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.

Examples:

Example: To list the services in a cluster


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

resp = client.list_services({
})

resp.to_h outputs the following:
{
  service_arns: [
    "arn:aws:ecs:us-east-1:012345678910:service/my-http-service", 
  ], 
}

Request syntax with placeholder values


resp = client.list_services({
  cluster: "String",
  next_token: "String",
  max_results: 1,
  launch_type: "EC2", # accepts EC2, FARGATE, EXTERNAL
  scheduling_strategy: "REPLICA", # accepts REPLICA, DAEMON
})

Response structure


resp.service_arns #=> Array
resp.service_arns[0] #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster to use when filtering the ListServices results. If you do not specify a cluster, the default cluster is assumed.

  • :next_token (String) —

    The nextToken value returned from a ListServices request indicating that more results are available to fulfill the request and further calls will be needed. If maxResults was provided, it is possible the number of results to be fewer than maxResults.

    This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

  • :max_results (Integer) —

    The maximum number of service results that ListServices returned in paginated output. When this parameter is used, ListServices only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListServices request with the returned nextToken value. This value can be between 1 and 100. If this parameter isn't used, then ListServices returns up to 10 results and a nextToken value if applicable.

  • :launch_type (String) —

    The launch type to use when filtering the ListServices results.

  • :scheduling_strategy (String) —

    The scheduling strategy to use when filtering the ListServices results.

Returns:

See Also:



4405
4406
4407
4408
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 4405

def list_services(params = {}, options = {})
  req = build_request(:list_services, params)
  req.send_request(options)
end

#list_tags_for_resource(params = {}) ⇒ Types::ListTagsForResourceResponse

List the tags for an Amazon ECS resource.

Examples:

Example: To list the tags for a cluster.


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

resp = client.list_tags_for_resource({
  resource_arn: "arn:aws:ecs:region:aws_account_id:cluster/dev", 
})

resp.to_h outputs the following:
{
  tags: [
    {
      key: "team", 
      value: "dev", 
    }, 
  ], 
}

Request syntax with placeholder values


resp = client.list_tags_for_resource({
  resource_arn: "String", # required
})

Response structure


resp.tags #=> Array
resp.tags[0].key #=> String
resp.tags[0].value #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :resource_arn (required, String) —

    The Amazon Resource Name (ARN) that identifies the resource to list the tags for. Currently, the supported resources are Amazon ECS tasks, services, task definitions, clusters, and container instances.

Returns:

See Also:



4456
4457
4458
4459
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 4456

def list_tags_for_resource(params = {}, options = {})
  req = build_request(:list_tags_for_resource, params)
  req.send_request(options)
end

#list_task_definition_families(params = {}) ⇒ Types::ListTaskDefinitionFamiliesResponse

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.

The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.

Examples:

Example: To list your registered task definition families


# This example lists all of your registered task definition families.

resp = client.list_task_definition_families({
})

resp.to_h outputs the following:
{
  families: [
    "node-js-app", 
    "web-timer", 
    "hpcc", 
    "hpcc-c4-8xlarge", 
  ], 
}

Example: To filter your registered task definition families


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

resp = client.list_task_definition_families({
  family_prefix: "hpcc", 
})

resp.to_h outputs the following:
{
  families: [
    "hpcc", 
    "hpcc-c4-8xlarge", 
  ], 
}

Request syntax with placeholder values


resp = client.list_task_definition_families({
  family_prefix: "String",
  status: "ACTIVE", # accepts ACTIVE, INACTIVE, ALL
  next_token: "String",
  max_results: 1,
})

Response structure


resp.families #=> Array
resp.families[0] #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :family_prefix (String) —

    The familyPrefix is a string that's used to filter the results of ListTaskDefinitionFamilies. If you specify a familyPrefix, only task definition family names that begin with the familyPrefix string are returned.

  • :status (String) —

    The task definition family status to filter the ListTaskDefinitionFamilies results with. By default, both ACTIVE and INACTIVE task definition families are listed. If this parameter is set to ACTIVE, only task definition families that have an ACTIVE task definition revision are returned. If this parameter is set to INACTIVE, only task definition families that do not have any ACTIVE task definition revisions are returned. If you paginate the resulting output, be sure to keep the status value constant in each subsequent request.

  • :next_token (String) —

    The nextToken value returned from a ListTaskDefinitionFamilies request indicating that more results are available to fulfill the request and further calls will be needed. If maxResults was provided, it is possible the number of results to be fewer than maxResults.

    This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

  • :max_results (Integer) —

    The maximum number of task definition family results that ListTaskDefinitionFamilies returned in paginated output. When this parameter is used, ListTaskDefinitions only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListTaskDefinitionFamilies request with the returned nextToken value. This value can be between 1 and 100. If this parameter isn't used, then ListTaskDefinitionFamilies returns up to 100 results and a nextToken value if applicable.

Returns:

See Also:



4571
4572
4573
4574
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 4571

def list_task_definition_families(params = {}, options = {})
  req = build_request(:list_task_definition_families, params)
  req.send_request(options)
end

#list_task_definitions(params = {}) ⇒ Types::ListTaskDefinitionsResponse

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.

The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.

Examples:

Example: To list your registered task definitions


# This example lists all of your registered task definitions.

resp = client.list_task_definitions({
})

resp.to_h outputs the following:
{
  task_definition_arns: [
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/sleep300:2", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/sleep360:1", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:3", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:4", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:5", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:6", 
  ], 
}

Example: To list the registered task definitions in a family


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

resp = client.list_task_definitions({
  family_prefix: "wordpress", 
})

resp.to_h outputs the following:
{
  task_definition_arns: [
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:3", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:4", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:5", 
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:6", 
  ], 
}

Request syntax with placeholder values


resp = client.list_task_definitions({
  family_prefix: "String",
  status: "ACTIVE", # accepts ACTIVE, INACTIVE
  sort: "ASC", # accepts ASC, DESC
  next_token: "String",
  max_results: 1,
})

Response structure


resp.task_definition_arns #=> Array
resp.task_definition_arns[0] #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :family_prefix (String) —

    The full family name to filter the ListTaskDefinitions results with. Specifying a familyPrefix limits the listed task definitions to task definition revisions that belong to that family.

  • :status (String) —

    The task definition status to filter the ListTaskDefinitions results with. By default, only ACTIVE task definitions are listed. By setting this parameter to INACTIVE, you can view task definitions that are INACTIVE as long as an active task or service still references them. If you paginate the resulting output, be sure to keep the status value constant in each subsequent request.

  • :sort (String) —

    The order to sort the results in. Valid values are ASC and DESC. By default, (ASC) task definitions are listed lexicographically by family name and in ascending numerical order by revision so that the newest task definitions in a family are listed last. Setting this parameter to DESC reverses the sort order on family name and revision. This is so that the newest task definitions in a family are listed first.

  • :next_token (String) —

    The nextToken value returned from a ListTaskDefinitions request indicating that more results are available to fulfill the request and further calls will be needed. If maxResults was provided, it is possible the number of results to be fewer than maxResults.

    This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

  • :max_results (Integer) —

    The maximum number of task definition results that ListTaskDefinitions returned in paginated output. When this parameter is used, ListTaskDefinitions only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListTaskDefinitions request with the returned nextToken value. This value can be between 1 and 100. If this parameter isn't used, then ListTaskDefinitions returns up to 100 results and a nextToken value if applicable.

Returns:

See Also:



4690
4691
4692
4693
 
# File 'gems/aws-sdk-ecs/lib/aws-sdk-ecs/client.rb', line 4690

def list_task_definitions(params = {}, options = {})
  req = build_request(:list_task_definitions, params)
  req.send_request(options)
end

#list_tasks(params = {}) ⇒ Types::ListTasksResponse

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. Currently, stopped tasks appear in the returned results for at least one hour.

The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.

Examples:

Example: To list the tasks in a cluster


# This example lists all of the tasks in a cluster.

resp = client.list_tasks({
  cluster: "default", 
})

resp.to_h outputs the following:
{
  task_arns: [
    "arn:aws:ecs:us-east-1:012345678910:task/0cc43cdb-3bee-4407-9c26-c0e6ea5bee84", 
    "arn:aws:ecs:us-east-1:012345678910:task/6b809ef6-c67e-4467-921f-ee261c15a0a1", 
  ], 
}

Example: 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.

resp = client.list_tasks({
  cluster: "default", 
  container_instance: "f6bbb147-5370-4ace-8c73-c7181ded911f", 
})

resp.to_h outputs the following:
{
  task_arns: [
    "arn:aws:ecs:us-east-1:012345678910:task/0cc43cdb-3bee-4407-9c26-c0e6ea5bee84", 
  ], 
}

Request syntax with placeholder values


resp = client.list_tasks({
  cluster: "String",
  container_instance: "String",
  family: "String",
  next_token: "String",
  max_results: 1,
  started_by: "String",
  service_name: "String",
  desired_status: "RUNNING", # accepts RUNNING, PENDING, STOPPED
  launch_type: "EC2", # accepts EC2, FARGATE, EXTERNAL
})

Response structure


resp.task_arns #=> Array
resp.task_arns[0] #=> String
resp.next_token #=> String

Parameters:

  • params (Hash) (defaults to: {}) —

    ({})

Options Hash (params):

  • :cluster (String) —

    The short name or full Amazon Resource Name (ARN) of the cluster to use when filtering the ListTasks results. If