Initialize connection to ECS

Notes

options parameter must include values for :aws_access_key_id and :aws_secret_access_key in order to create a connection

Examples

  ecs = ECS.new(
   :aws_access_key_id => your_aws_access_key_id,
   :aws_secret_access_key => your_aws_secret_access_key
  )

Parameters

• options<~Hash> - config arguments for connection. Defaults to {}.
  • region<~String> - optional region to use. For instance, ‘eu-west-1’, ‘us-east-1’ and etc.

Returns

• ECS object with connection to AWS.

Creates a new Amazon ECS cluster docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCluster.html

Parameters

• clusterName <~String> - The name of your cluster.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘Cluster’ <~Hash> - The full description of your new cluster

Runs and maintains a desired number of tasks from a specified task definition. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html

Parameters

• clientToken <~String> - unique, case-sensitive identifier you provide to ensure the idempotency of the request.
• cluster <~String> - short name or full Amazon Resource Name (ARN) of the cluster that you want to run your service on.
• desiredCount <~Integer> - number of instantiations of the specified task definition that you would like to place and keep running on your cluster.
• loadBalancers <~Array> - list of load balancer objects, containing the load balancer name, the container name (as it appears in a container definition), and the container port to access from the load balancer.
• role <~String> - name or full Amazon Resource Name (ARN) of the IAM role that allows your Amazon ECS container agent to make calls to your load balancer on your behalf.
• serviceName <~String> - name of your service
• taskDefinition <~String> - family and revision (family:revision) or full Amazon Resource Name (ARN) of the task definition that you want to run in your service

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘Service’ <~Hash> - The full description of your new service

Deletes the specified cluster docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeleteCluster.html

Parameters

• cluster <~String> - The short name or full Amazon Resource Name (ARN) of the cluster that you want to delete

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘Cluster’<~Hash> - The full description of the deleted cluster

Deletes a specified service within a cluster. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeleteService.html

Parameters

• cluster <~String> - name of the cluster that hosts the service you want to delete.
• service <~String> - name of the service you want to delete.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘Service’<~Hash> - The full description of the deleted service

Deregisters an Amazon ECS container instance from the specified cluster. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeregisterContainerInstance.html

Parameters

• cluster <~String> - short name or full ARN of the cluster that hosts the container instance you want to deregister.
• containerInstance <~String> - container instance UUID or full Amazon Resource Name (ARN) of the container instance you want to deregister.
• force <~Boolean> - Force the deregistration of the container instance.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘ContainerInstance’ <~Hash> - full description of the deregistered container instance

Deregisters the specified task definition. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeregisterTaskDefinition.html

Parameters

• taskDefinition <~String> - The family and revision (family:revision) or full Amazon Resource Name (ARN) of the task definition that you want to deregister.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘TaskDefinition’ <~Hash> - full description of the deregistered task

Describes one or more of your clusters. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeClusters.html

Parameters

• clusters <~Array> - list of cluster names or full cluster Amazon Resource Name (ARN) entries

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘clusters’ <~Array> - The list of clusters
    • ‘failures’ <~Array> - The list of failures (if any)

Describes Amazon EC2 Container Service container instances. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeContainerInstances.html

Parameters

• cluster <~String> - short name or full ARN of the cluster that hosts the container instances you want to describe.
• containerInstances <~Array> - list of container instance UUIDs or full Amazon Resource Name (ARN) entries.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘containerInstances’ <~Array> - list of container instances.
    • ‘failures’ <~Array> - list of failures (if any)

Describes the specified services running in your cluster. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeServices.html

Parameters

• cluster <~String> - name of the cluster that hosts the service you want to describe.
• services <~Array> - list of services you want to describe.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘services’ <~Array> - The list of services described.
    • ‘failures’ <~Array> - The list of failures associated with the call (if any).

Describes a task definition docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTaskDefinition.html

Parameters

• taskDefinition <~String> - The family for the latest revision, family and revision (family:revision) for a specific revision in the family, or full Amazon Resource Name (ARN) of the task definition that you want to describe.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘taskDefinition’ <~Hash> - full task definition description

Describes a specified task or tasks. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html

Parameters

• cluster <~String> - short name or full Amazon Resource Name (ARN) of the cluster that hosts the task you want to describe
• tasks <~Array> - space-separated list of task UUIDs or full Amazon Resource Name (ARN) entries

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘tasks’ <~Array> - The list of tasks
    • ‘failures’ <~Array> - The list of failures (if any)

Returns a list of existing clusters docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListClusters.html

Parameters

• maxResults <~Integer> - The maximum number of cluster results returned by ListClusters in paginated output.
• nextToken <~String> - The nextToken value returned from a previous paginated ListClusters request where maxResults was used.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘ClusterArns’ <~Array> - list of full Amazon Resource Name (ARN) entries for each cluster associated with your account.
    • ‘NextToken’ <~String> - nextToken value to include in a future ListClusters request.

Returns a list of container instances in a specified cluster. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListContainerInstances.html

Parameters

• cluster <~String> - short name or full Amazon Resource Name (ARN) of the cluster that hosts the container instances you want to list.
• maxResults <~Integer> - maximum number of container instance results returned by ListContainerInstances in paginated output.
• nextToken <~String> - nextToken value returned from a previous paginated ListContainerInstances request where maxResults was used.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘ContainerInstanceArns’ <~Array> - list of container instance full ARN entries for each container instance associated with the specified cluster.
    • ‘NextToken’ <~String> - nextToken value to include in a future ListContainerInstances request.

Lists the services that are running in a specified cluster. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListServices.html

Parameters

• cluster <~String> - The short name or full Amazon Resource Name (ARN) of the cluster that hosts the services you want to list.
• maxResults <~Integer> - The maximum number of container instance results returned by ListServices in paginated output.
• nextToken <~String> - The nextToken value returned from a previous paginated ListServices request where maxResults was used.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘ServiceArns’ <~Array> - list of full Amazon Resource Name (ARN) entries for each service associated with the specified cluster.
    • ‘NextToken’ <~String> - nextToken value to include in a future ListServices request.

Returns a list of task definition families that are registered to your account. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTaskDefinitionFamilies.html

Parameters

• familyPrefix <~String> - familyPrefix is a string that is used to filter the results of ListTaskDefinitionFamilies.
• maxResults <~Integer> - maximum number of task definition family results returned by ListTaskDefinitionFamilies in paginated output.
• nextToken <~String> - nextToken value returned from a previous paginated ListTaskDefinitionFamilies request where maxResults was used.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘Families’ <~Array> - list of task definition family names that match the ListTaskDefinitionFamilies request.
    • ‘NextToken’ <~String> - nextToken value to include in a future ListTaskDefinitionFamilies request.

Returns a list of task definitions that are registered to your account docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTaskDefinitions.html

Parameters

• familyPrefix <~String> - The full family name that you want to filter the ListTaskDefinitions results with.
• maxResults <~Integer> - The maximum number of task definition results returned by ListTaskDefinitions in paginated output.
• nextToken <~String> - The nextToken value returned from a previous paginated ListTaskDefinitions request.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘TaskDefinitionArns’ <~Array> - list of task definition Amazon Resource Name (ARN) entries for the ListTaskDefintions request.
    • ‘NextToken’ <~String> - nextToken value to include in a future ListTaskDefinitions request

Returns a list of tasks for a specified cluster. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTasks.html

Parameters

• cluster <~String> - short name or full Amazon Resource Name (ARN) of the cluster that hosts the tasks you want to list.
• containerInstance <~String> - container instance UUID or full Amazon Resource Name (ARN) of the container instance that you want to filter the ListTasks results with.
• family <~String> - name of the family that you want to filter the ListTasks results with.
• maxResults <~Integer> - maximum number of task results returned by ListTasks in paginated output.
• nextToken <~String> - nextToken value returned from a previous paginated ListTasks request where maxResults was used.
• serviceName <~String> - name of the service that you want to filter the ListTasks results with.
• startedBy <~String> - startedBy value that you want to filter the task results with.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘TaskArns’ <~Array> - list of task Amazon Resource Name (ARN) entries for the ListTasks request.
    • ‘NextToken’ <~String> - nextToken value to include in a future ListTasks request.

Registers a new task definition from the supplied family and containerDefinitions. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html

Parameters

• containerDefinitions <~Array> - list of container definitions in JSON format that describe the different containers that make up your task.
• family <~String> - family for a task definition, which allows you to track multiple versions of the same task definition.
• volumes <~String> - list of volume definitions in JSON format that containers in your task may use.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘TaskDefinition’ <~Array> - full task definition description registered

Start a task using random placement and the default Amazon ECS scheduler. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html

Parameters

• cluster <~String> - short name or full Amazon Resource Name (ARN) of the cluster that you want to run your task on.
• count <~Integer> - number of instantiations of the specified task that you would like to place on your cluster.
• overrides <~Hash> - list of container overrides.
• startedBy <~String> - optional tag specified when a task is started
• taskDefinition <~String> - family and revision (family:revision) or full ARN of the task definition that you want to run.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘tasks’ <~Array> - full description of the tasks that were run.
    • ‘failures’ <~Array> - Any failed tasks from your RunTask action are listed here.

Starts a new task from the specified task definition on the specified container instance or instances. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_StartTask.html

Parameters

• cluster <~String> - short name or full Amazon Resource Name (ARN) of the cluster that you want to start your task on.
• containerInstances <~Array> - container instance UUIDs or full ARN entries for the container instances on which you would like to place your task.
• overrides <~Hash> - list of container overrides.
• startedBy <~String> - optional tag specified when a task is started
• taskDefinition <~String> - family and revision (family:revision) or full ARN of the task definition that you want to start.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘tasks’ <~Array> - full description of the tasks that were started.
    • ‘failures’ <~Array> - Any failed tasks from your StartTask action are listed here.

Stops a running task. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_StopTask.html

Parameters

• cluster <~String> - short name or full Amazon Resource Name (ARN) of the cluster that hosts the task you want to stop.
• task <~String> - task UUIDs or full Amazon Resource Name (ARN) entry of the task you would like to stop.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘Task’ <~Hash> - The full description of the stopped task.

Modify the desired count or task definition used in a service. docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html

Parameters

• cluster <~String> - short name or full Amazon Resource Name (ARN) of the cluster that your service is running on.
• desiredCount <~Integer> - number of instantiations of the task that you would like to place and keep running in your service.
• service <~String> - name of the service that you want to update.
• taskDefinition <~String> - family and revision (family:revision) or full Amazon Resource Name (ARN) of the task definition that you want to run in your service.

Returns

• response<~Excon::Response>:
  • body<~Hash>:
    • ‘Service’<~Hash> - The full description of the updated cluster