com.amazonaws.services.ecs.AmazonECS Maven / Gradle / Ivy
/*
* Copyright 2012-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with
* the License. A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
* CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
* and limitations under the License.
*/
package com.amazonaws.services.ecs;
import javax.annotation.Generated;
import com.amazonaws.*;
import com.amazonaws.regions.*;
import com.amazonaws.services.ecs.model.*;
import com.amazonaws.services.ecs.waiters.AmazonECSWaiters;
/**
* Interface for accessing Amazon ECS.
*
* Note: Do not directly implement this interface, new methods are added to it regularly. Extend from
* {@link com.amazonaws.services.ecs.AbstractAmazonECS} instead.
*
*
*
* Amazon EC2 Container Service (Amazon ECS) is a highly scalable, fast, container management service that makes it easy
* to run, stop, and manage Docker containers on a cluster of EC2 instances. Amazon ECS lets you launch and stop
* container-enabled applications with simple API calls, allows you to get the state of your cluster from a centralized
* service, and gives you access to many familiar Amazon EC2 features like security groups, Amazon EBS volumes, and IAM
* roles.
*
*
* You can use Amazon ECS to schedule the placement of containers across your cluster based on your resource needs,
* isolation policies, and availability requirements. Amazon EC2 Container Service eliminates the need for you to
* operate your own cluster management and configuration management systems or worry about scaling your management
* infrastructure.
*
*/
@Generated("com.amazonaws:aws-java-sdk-code-generator")
public interface AmazonECS {
/**
* The region metadata service name for computing region endpoints. You can use this value to retrieve metadata
* (such as supported regions) of the service.
*
* @see RegionUtils#getRegionsForService(String)
*/
String ENDPOINT_PREFIX = "ecs";
/**
* Overrides the default endpoint for this client ("https://ecs.us-east-1.amazonaws.com"). Callers can use this
* method to control which AWS region they want to work with.
*
* Callers can pass in just the endpoint (ex: "ecs.us-east-1.amazonaws.com") or a full URL, including the protocol
* (ex: "https://ecs.us-east-1.amazonaws.com"). If the protocol is not specified here, the default protocol from
* this client's {@link ClientConfiguration} will be used, which by default is HTTPS.
*
* For more information on using AWS regions with the AWS SDK for Java, and a complete list of all available
* endpoints for all AWS services, see:
* http://developer.amazonwebservices.com/connect/entry.jspa?externalID=3912
*
* This method is not threadsafe. An endpoint should be configured when the client is created and before any
* service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in
* transit or retrying.
*
* @param endpoint
* The endpoint (ex: "ecs.us-east-1.amazonaws.com") or a full URL, including the protocol (ex:
* "https://ecs.us-east-1.amazonaws.com") of the region specific AWS endpoint this client will communicate
* with.
* @deprecated use {@link AwsClientBuilder#setEndpointConfiguration(AwsClientBuilder.EndpointConfiguration)} for
* example:
* {@code builder.setEndpointConfiguration(new EndpointConfiguration(endpoint, signingRegion));}
*/
@Deprecated
void setEndpoint(String endpoint);
/**
* An alternative to {@link AmazonECS#setEndpoint(String)}, sets the regional endpoint for this client's service
* calls. Callers can use this method to control which AWS region they want to work with.
*
* By default, all service endpoints in all regions use the https protocol. To use http instead, specify it in the
* {@link ClientConfiguration} supplied at construction.
*
* This method is not threadsafe. A region should be configured when the client is created and before any service
* requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit
* or retrying.
*
* @param region
* The region this client will communicate with. See {@link Region#getRegion(com.amazonaws.regions.Regions)}
* for accessing a given region. Must not be null and must be a region where the service is available.
*
* @see Region#getRegion(com.amazonaws.regions.Regions)
* @see Region#createClient(Class, com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration)
* @see Region#isServiceSupported(String)
* @deprecated use {@link AwsClientBuilder#setRegion(String)}
*/
@Deprecated
void setRegion(Region region);
/**
*
* 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.
*
*
* @param createClusterRequest
* @return Result of the CreateCluster operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.CreateCluster
* @see AWS API
* Documentation
*/
CreateClusterResult createCluster(CreateClusterRequest createClusterRequest);
/**
* Simplified method form for invoking the CreateCluster operation.
*
* @see #createCluster(CreateClusterRequest)
*/
CreateClusterResult createCluster();
/**
*
* Runs and maintains a desired number of tasks from a specified task definition. If the number of tasks running in
* a service drops below desiredCount, Amazon ECS spawns another copy of the task in the specified
* cluster. To update an existing service, see UpdateService.
*
*
* In addition to maintaining the desired count of tasks in your service, you can optionally run your service behind
* a load balancer. The load balancer distributes traffic across the tasks that are associated with the service. For
* more information, see Service Load
* Balancing in the Amazon EC2 Container Service Developer Guide.
*
*
* You can optionally specify a deployment configuration for your service. During a deployment (which is triggered
* by changing the task definition or the desired count of a service with an UpdateService operation), the
* service scheduler uses the minimumHealthyPercent and maximumPercent parameters to
* determine the deployment strategy.
*
*
* The minimumHealthyPercent represents a lower limit on the number of your service's tasks that must
* remain in the RUNNING state during a deployment, as a percentage of the desiredCount
* (rounded up to the nearest integer). This parameter enables you to deploy without using additional cluster
* capacity. For example, if desiredCount is four tasks and the minimum is 50%, the scheduler can stop
* two existing tasks to free up cluster capacity before starting two new tasks. Tasks for services that do not use
* a load balancer are considered healthy if they are in the RUNNING state. Tasks for services that use
* a load balancer are considered healthy if they are in the RUNNING state and the container instance
* they are hosted on is reported as healthy by the load balancer. The default value is 50% in the console and 100%
* for the AWS CLI, the AWS SDKs, and the APIs.
*
*
* The maximumPercent parameter represents an upper limit on the number of your service's tasks that
* are allowed in the RUNNING or PENDING state during a deployment, as a percentage of the
* desiredCount (rounded down to the nearest integer). This parameter enables you to define the
* deployment batch size. For example, if desiredCount is four tasks and the maximum is 200%, the
* scheduler can start four new tasks before stopping the four older tasks (provided that the cluster resources
* required to do this are available). The default value is 200%.
*
*
* 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 your service's task definition (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 (although
* you can choose a different placement strategy):
*
*
* -
*
* Sort the valid container instances by the fewest number of running tasks for this service in the same
* Availability Zone as the instance. 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.
*
*
*
*
*
*
* @param createServiceRequest
* @return Result of the CreateService operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.CreateService
* @see AWS API
* Documentation
*/
CreateServiceResult createService(CreateServiceRequest createServiceRequest);
/**
*
* Deletes one or more custom attributes from an Amazon ECS resource.
*
*
* @param deleteAttributesRequest
* @return Result of the DeleteAttributes operation returned by the service.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @throws TargetNotFoundException
* The specified target could not be found. You can view your available container instances with
* ListContainerInstances. Amazon ECS container instances are cluster-specific and region-specific.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.DeleteAttributes
* @see AWS API
* Documentation
*/
DeleteAttributesResult deleteAttributes(DeleteAttributesRequest deleteAttributesRequest);
/**
*
* Deletes the specified cluster. 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.
*
*
* @param deleteClusterRequest
* @return Result of the DeleteCluster operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @throws ClusterContainsContainerInstancesException
* You cannot delete a cluster that has registered container instances. You must first deregister the
* container instances before you can delete the cluster. For more information, see
* DeregisterContainerInstance.
* @throws ClusterContainsServicesException
* You cannot delete a cluster that contains services. You must first update the service to reduce its
* desired task count to 0 and then delete the service. For more information, see UpdateService and
* DeleteService.
* @sample AmazonECS.DeleteCluster
* @see AWS API
* Documentation
*/
DeleteClusterResult deleteCluster(DeleteClusterRequest deleteClusterRequest);
/**
*
* 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 cannot 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
* ListServices API operations. After the tasks have stopped, then the service status moves from
* DRAINING to INACTIVE. Services in the DRAINING or INACTIVE
* status can still be viewed with DescribeServices API operations; however, in the future,
* INACTIVE services may be cleaned up and purged from Amazon ECS record keeping, and
* DescribeServices API operations on those services will return a ServiceNotFoundException
* error.
*
*
*
* @param deleteServiceRequest
* @return Result of the DeleteService operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @throws ServiceNotFoundException
* The specified service could not be found. You can view your available services with ListServices.
* Amazon ECS services are cluster-specific and region-specific.
* @sample AmazonECS.DeleteService
* @see AWS API
* Documentation
*/
DeleteServiceResult deleteService(DeleteServiceRequest deleteServiceRequest);
/**
*
* 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, you should stop all of
* the tasks running on the container instance before deregistration to avoid any orphaned tasks from consuming
* resources.
*
*
* Deregistering a container instance removes the instance from a cluster, but it does not 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 are not automatically deregistered
* when terminated).
*
*
*
* @param deregisterContainerInstanceRequest
* @return Result of the DeregisterContainerInstance operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.DeregisterContainerInstance
* @see AWS API Documentation
*/
DeregisterContainerInstanceResult deregisterContainerInstance(DeregisterContainerInstanceRequest deregisterContainerInstanceRequest);
/**
*
* 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 cannot use an INACTIVE task definition to run new tasks or create new services, and you cannot
* update an existing service to reference an INACTIVE task definition (although there may be up to a
* 10 minute window following deregistration where these restrictions have not yet taken effect).
*
*
* @param deregisterTaskDefinitionRequest
* @return Result of the DeregisterTaskDefinition operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.DeregisterTaskDefinition
* @see AWS
* API Documentation
*/
DeregisterTaskDefinitionResult deregisterTaskDefinition(DeregisterTaskDefinitionRequest deregisterTaskDefinitionRequest);
/**
*
* Describes one or more of your clusters.
*
*
* @param describeClustersRequest
* @return Result of the DescribeClusters operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.DescribeClusters
* @see AWS API
* Documentation
*/
DescribeClustersResult describeClusters(DescribeClustersRequest describeClustersRequest);
/**
* Simplified method form for invoking the DescribeClusters operation.
*
* @see #describeClusters(DescribeClustersRequest)
*/
DescribeClustersResult describeClusters();
/**
*
* Describes Amazon EC2 Container Service container instances. Returns metadata about registered and remaining
* resources on each container instance requested.
*
*
* @param describeContainerInstancesRequest
* @return Result of the DescribeContainerInstances operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.DescribeContainerInstances
* @see AWS
* API Documentation
*/
DescribeContainerInstancesResult describeContainerInstances(DescribeContainerInstancesRequest describeContainerInstancesRequest);
/**
*
* Describes the specified services running in your cluster.
*
*
* @param describeServicesRequest
* @return Result of the DescribeServices operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.DescribeServices
* @see AWS API
* Documentation
*/
DescribeServicesResult describeServices(DescribeServicesRequest describeServicesRequest);
/**
*
* 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.
*
*
*
* @param describeTaskDefinitionRequest
* @return Result of the DescribeTaskDefinition operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.DescribeTaskDefinition
* @see AWS API
* Documentation
*/
DescribeTaskDefinitionResult describeTaskDefinition(DescribeTaskDefinitionRequest describeTaskDefinitionRequest);
/**
*
* Describes a specified task or tasks.
*
*
* @param describeTasksRequest
* @return Result of the DescribeTasks operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.DescribeTasks
* @see AWS API
* Documentation
*/
DescribeTasksResult describeTasks(DescribeTasksRequest describeTasksRequest);
/**
*
*
* This action is only used by the Amazon EC2 Container Service agent, and it is not intended for use outside of the
* agent.
*
*
*
* Returns an endpoint for the Amazon EC2 Container Service agent to poll for updates.
*
*
* @param discoverPollEndpointRequest
* @return Result of the DiscoverPollEndpoint operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @sample AmazonECS.DiscoverPollEndpoint
* @see AWS API
* Documentation
*/
DiscoverPollEndpointResult discoverPollEndpoint(DiscoverPollEndpointRequest discoverPollEndpointRequest);
/**
* Simplified method form for invoking the DiscoverPollEndpoint operation.
*
* @see #discoverPollEndpoint(DiscoverPollEndpointRequest)
*/
DiscoverPollEndpointResult discoverPollEndpoint();
/**
*
* Lists the attributes for Amazon ECS resources within a specified target type and cluster. When you specify a
* target type and cluster, LisAttributes 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, for example, to see which container
* instances in a cluster are running a Linux AMI (ecs.os-type=linux).
*
*
* @param listAttributesRequest
* @return Result of the ListAttributes operation returned by the service.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.ListAttributes
* @see AWS API
* Documentation
*/
ListAttributesResult listAttributes(ListAttributesRequest listAttributesRequest);
/**
*
* Returns a list of existing clusters.
*
*
* @param listClustersRequest
* @return Result of the ListClusters operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.ListClusters
* @see AWS API
* Documentation
*/
ListClustersResult listClusters(ListClustersRequest listClustersRequest);
/**
* Simplified method form for invoking the ListClusters operation.
*
* @see #listClusters(ListClustersRequest)
*/
ListClustersResult listClusters();
/**
*
* 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 EC2 Container Service Developer Guide.
*
*
* @param listContainerInstancesRequest
* @return Result of the ListContainerInstances operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.ListContainerInstances
* @see AWS API
* Documentation
*/
ListContainerInstancesResult listContainerInstances(ListContainerInstancesRequest listContainerInstancesRequest);
/**
* Simplified method form for invoking the ListContainerInstances operation.
*
* @see #listContainerInstances(ListContainerInstancesRequest)
*/
ListContainerInstancesResult listContainerInstances();
/**
*
* Lists the services that are running in a specified cluster.
*
*
* @param listServicesRequest
* @return Result of the ListServices operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.ListServices
* @see AWS API
* Documentation
*/
ListServicesResult listServices(ListServicesRequest listServicesRequest);
/**
* Simplified method form for invoking the ListServices operation.
*
* @see #listServices(ListServicesRequest)
*/
ListServicesResult listServices();
/**
*
* Returns a list of task definition families that are registered to your account (which may include task definition
* families that no longer have any ACTIVE task definition revisions).
*
*
* You can filter out task definition families that do not contain any ACTIVE task definition revisions
* by setting the status parameter to ACTIVE. You can also filter the results with the
* familyPrefix parameter.
*
*
* @param listTaskDefinitionFamiliesRequest
* @return Result of the ListTaskDefinitionFamilies operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.ListTaskDefinitionFamilies
* @see AWS
* API Documentation
*/
ListTaskDefinitionFamiliesResult listTaskDefinitionFamilies(ListTaskDefinitionFamiliesRequest listTaskDefinitionFamiliesRequest);
/**
* Simplified method form for invoking the ListTaskDefinitionFamilies operation.
*
* @see #listTaskDefinitionFamilies(ListTaskDefinitionFamiliesRequest)
*/
ListTaskDefinitionFamiliesResult listTaskDefinitionFamilies();
/**
*
* 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.
*
*
* @param listTaskDefinitionsRequest
* @return Result of the ListTaskDefinitions operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.ListTaskDefinitions
* @see AWS API
* Documentation
*/
ListTaskDefinitionsResult listTaskDefinitions(ListTaskDefinitionsRequest listTaskDefinitionsRequest);
/**
* Simplified method form for invoking the ListTaskDefinitions operation.
*
* @see #listTaskDefinitions(ListTaskDefinitionsRequest)
*/
ListTaskDefinitionsResult listTaskDefinitions();
/**
*
* Returns a list of tasks for a specified cluster. You can filter the results by family name, by a particular
* container instance, or by the desired status of the task with the family,
* containerInstance, and desiredStatus parameters.
*
*
* Recently-stopped tasks might appear in the returned results. Currently, stopped tasks appear in the returned
* results for at least one hour.
*
*
* @param listTasksRequest
* @return Result of the ListTasks operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @throws ServiceNotFoundException
* The specified service could not be found. You can view your available services with ListServices.
* Amazon ECS services are cluster-specific and region-specific.
* @sample AmazonECS.ListTasks
* @see AWS API
* Documentation
*/
ListTasksResult listTasks(ListTasksRequest listTasksRequest);
/**
* Simplified method form for invoking the ListTasks operation.
*
* @see #listTasks(ListTasksRequest)
*/
ListTasksResult listTasks();
/**
*
* Create or update an attribute on an Amazon ECS resource. If the attribute does not exist, it is created. If the
* attribute exists, its value is replaced with the specified value. To delete an attribute, use
* DeleteAttributes. For more information, see Attributes in the Amazon EC2 Container Service Developer Guide.
*
*
* @param putAttributesRequest
* @return Result of the PutAttributes operation returned by the service.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @throws TargetNotFoundException
* The specified target could not be found. You can view your available container instances with
* ListContainerInstances. Amazon ECS container instances are cluster-specific and region-specific.
* @throws AttributeLimitExceededException
* You can apply up to 10 custom attributes per resource. You can view the attributes of a resource with
* ListAttributes. You can remove existing attributes on a resource with DeleteAttributes.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.PutAttributes
* @see AWS API
* Documentation
*/
PutAttributesResult putAttributes(PutAttributesRequest putAttributesRequest);
/**
*
*
* This action is only used by the Amazon EC2 Container Service agent, and it is not intended for use outside of the
* agent.
*
*
*
* Registers an EC2 instance into the specified cluster. This instance becomes available to place containers on.
*
*
* @param registerContainerInstanceRequest
* @return Result of the RegisterContainerInstance operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @sample AmazonECS.RegisterContainerInstance
* @see AWS
* API Documentation
*/
RegisterContainerInstanceResult registerContainerInstance(RegisterContainerInstanceRequest registerContainerInstanceRequest);
/**
*
* Registers a new task definition from the supplied family and containerDefinitions.
* Optionally, you can add data volumes to your containers with the volumes parameter. For more
* information about task definition parameters and defaults, see Amazon ECS Task
* Definitions in the Amazon EC2 Container Service Developer Guide.
*
*
* You can specify an IAM role for your task with the taskRoleArn parameter. When you specify an IAM
* role for a task, its containers can then use the latest versions of the AWS CLI or SDKs to make API requests to
* the AWS services that are specified in the IAM policy associated with the role. For more information, see IAM Roles for Tasks in
* the Amazon EC2 Container Service Developer Guide.
*
*
* You can specify a Docker networking mode for the containers in your task definition with the
* networkMode parameter. The available network modes correspond to those described in Network settings in the Docker run
* reference.
*
*
* @param registerTaskDefinitionRequest
* @return Result of the RegisterTaskDefinition operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @sample AmazonECS.RegisterTaskDefinition
* @see AWS API
* Documentation
*/
RegisterTaskDefinitionResult registerTaskDefinition(RegisterTaskDefinitionRequest registerTaskDefinitionRequest);
/**
*
* Starts a new task using the specified task definition.
*
*
* You can allow Amazon ECS to place tasks for you, or you can customize how Amazon ECS places tasks using placement
* constraints and placement strategies. For more information, see Scheduling Tasks in
* the Amazon EC2 Container Service Developer Guide.
*
*
* Alternatively, you can use StartTask to use your own scheduler or place tasks manually on specific
* container instances.
*
*
* @param runTaskRequest
* @return Result of the RunTask operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.RunTask
* @see AWS API
* Documentation
*/
RunTaskResult runTask(RunTaskRequest runTaskRequest);
/**
*
* Starts a new task from the specified task definition on the specified container instance or instances.
*
*
* Alternatively, you can use RunTask to place tasks for you. For more information, see Scheduling Tasks in
* the Amazon EC2 Container Service Developer Guide.
*
*
* @param startTaskRequest
* @return Result of the StartTask operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.StartTask
* @see AWS API
* Documentation
*/
StartTaskResult startTask(StartTaskRequest startTaskRequest);
/**
*
* Stops a running task.
*
*
* When StopTask is called on a task, the equivalent of docker stop is issued to the containers
* running in the task. This results in a SIGTERM and a 30-second timeout, after which
* SIGKILL is sent and the containers are forcibly stopped. If the container handles the
* SIGTERM gracefully and exits within 30 seconds from receiving it, no SIGKILL is sent.
*
*
* @param stopTaskRequest
* @return Result of the StopTask operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.StopTask
* @see AWS API
* Documentation
*/
StopTaskResult stopTask(StopTaskRequest stopTaskRequest);
/**
*
*
* This action is only used by the Amazon EC2 Container Service agent, and it is not intended for use outside of the
* agent.
*
*
*
* Sent to acknowledge that a container changed states.
*
*
* @param submitContainerStateChangeRequest
* @return Result of the SubmitContainerStateChange operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @sample AmazonECS.SubmitContainerStateChange
* @see AWS
* API Documentation
*/
SubmitContainerStateChangeResult submitContainerStateChange(SubmitContainerStateChangeRequest submitContainerStateChangeRequest);
/**
* Simplified method form for invoking the SubmitContainerStateChange operation.
*
* @see #submitContainerStateChange(SubmitContainerStateChangeRequest)
*/
SubmitContainerStateChangeResult submitContainerStateChange();
/**
*
*
* This action is only used by the Amazon EC2 Container Service agent, and it is not intended for use outside of the
* agent.
*
*
*
* Sent to acknowledge that a task changed states.
*
*
* @param submitTaskStateChangeRequest
* @return Result of the SubmitTaskStateChange operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @sample AmazonECS.SubmitTaskStateChange
* @see AWS API
* Documentation
*/
SubmitTaskStateChangeResult submitTaskStateChange(SubmitTaskStateChangeRequest submitTaskStateChangeRequest);
/**
*
* Updates the Amazon ECS container agent on a specified container instance. Updating the Amazon ECS container agent
* does not interrupt running tasks or services on the container instance. The process for updating the agent
* differs depending on whether your container instance was launched with the Amazon ECS-optimized AMI or another
* operating system.
*
*
* UpdateContainerAgent requires the Amazon ECS-optimized AMI or Amazon Linux with the
* ecs-init service installed and running. For help updating the Amazon ECS container agent on other
* operating systems, see Manually Updating the Amazon ECS Container Agent in the Amazon EC2 Container Service Developer Guide.
*
*
* @param updateContainerAgentRequest
* @return Result of the UpdateContainerAgent operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @throws UpdateInProgressException
* There is already a current Amazon ECS container agent update in progress on the specified container
* instance. If the container agent becomes disconnected while it is in a transitional stage, such as
* PENDING or STAGING, the update process can get stuck in that state. However,
* when the agent reconnects, it resumes where it stopped previously.
* @throws NoUpdateAvailableException
* There is no update available for this Amazon ECS container agent. This could be because the agent is
* already running the latest version, or it is so old that there is no update path to the current version.
* @throws MissingVersionException
* Amazon ECS is unable to determine the current version of the Amazon ECS container agent on the container
* instance and does not have enough information to proceed with an update. This could be because the agent
* running on the container instance is an older or custom version that does not use our version
* information.
* @sample AmazonECS.UpdateContainerAgent
* @see AWS API
* Documentation
*/
UpdateContainerAgentResult updateContainerAgent(UpdateContainerAgentRequest updateContainerAgentRequest);
/**
*
* Modifies the status of an Amazon ECS container instance.
*
*
* You can change the status of a container instance to DRAINING to manually remove an instance from a
* cluster, for example to perform system updates, update the Docker daemon, or scale down the cluster size.
*
*
* When you set a container instance to DRAINING, Amazon ECS prevents new tasks from being scheduled
* for placement on the container instance and replacement service tasks are started on other container instances in
* the cluster if the resources are available. Service tasks on the container instance that are in the
* PENDING state are stopped immediately.
*
*
* Service tasks on the container instance that are in the RUNNING state are stopped and replaced
* according the service's deployment configuration parameters, minimumHealthyPercent and
* maximumPercent. Note that you can change the deployment configuration of your service using
* UpdateService.
*
*
* -
*
* If minimumHealthyPercent is below 100%, the scheduler can ignore desiredCount
* temporarily during task replacement. For example, desiredCount is four tasks, a minimum of 50%
* allows the scheduler to stop two existing tasks before starting two new tasks. If the minimum is 100%, the
* service scheduler can't remove existing tasks until the replacement tasks are considered healthy. Tasks for
* services that do not use a load balancer are considered healthy if they are in the RUNNING state.
* Tasks for services that use a load balancer are considered healthy if they are in the RUNNING state
* and the container instance they are hosted on is reported as healthy by the load balancer.
*
*
* -
*
* The maximumPercent parameter represents an upper limit on the number of running tasks during task
* replacement, which enables you to define the replacement batch size. For example, if desiredCount of
* four tasks, a maximum of 200% starts four new tasks before stopping the four tasks to be drained (provided that
* the cluster resources required to do this are available). If the maximum is 100%, then replacement tasks can't
* start until the draining tasks have stopped.
*
*
*
*
* Any PENDING or RUNNING tasks that do not belong to a service are not affected; you must
* wait for them to finish or stop them manually.
*
*
* A container instance has completed draining when it has no more RUNNING tasks. You can verify this
* using ListTasks.
*
*
* When you set a container instance to ACTIVE, the Amazon ECS scheduler can begin scheduling tasks on
* the instance again.
*
*
* @param updateContainerInstancesStateRequest
* @return Result of the UpdateContainerInstancesState operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @sample AmazonECS.UpdateContainerInstancesState
* @see AWS API Documentation
*/
UpdateContainerInstancesStateResult updateContainerInstancesState(UpdateContainerInstancesStateRequest updateContainerInstancesStateRequest);
/**
*
* Modifies the desired count, deployment configuration, or task definition used in a service.
*
*
* You can add to or subtract from the number of instantiations of a task definition in a service by specifying the
* cluster that the service is running in and a new desiredCount parameter.
*
*
* You can use UpdateService to modify your task definition and deploy a new version of your service.
*
*
* You can also update the deployment configuration of a service. When a deployment is triggered by updating the
* task definition of a service, the service scheduler uses the deployment configuration parameters,
* minimumHealthyPercent and maximumPercent, to determine the deployment strategy.
*
*
* -
*
* If minimumHealthyPercent is below 100%, the scheduler can ignore desiredCount
* temporarily during a deployment. For example, if desiredCount is four tasks, a minimum of 50% allows
* the scheduler to stop two existing tasks before starting two new tasks. Tasks for services that do not use a load
* balancer are considered healthy if they are in the RUNNING state. Tasks for services that use a load
* balancer are considered healthy if they are in the RUNNING state and the container instance they are
* hosted on is reported as healthy by the load balancer.
*
*
* -
*
* The maximumPercent parameter represents an upper limit on the number of running tasks during a
* deployment, which enables you to define the deployment batch size. For example, if desiredCount is
* four tasks, a maximum of 200% starts four new tasks before stopping the four older tasks (provided that the
* cluster resources required to do this are available).
*
*
*
*
* When UpdateService stops a task during a deployment, the equivalent of docker stop is issued
* to the containers running in the task. This results in a SIGTERM and a 30-second timeout, after
* which SIGKILL is sent and the containers are forcibly stopped. If the container handles the
* SIGTERM gracefully and exits within 30 seconds from receiving it, no SIGKILL is sent.
*
*
* When the service scheduler launches new tasks, it determines task placement in your cluster with the following
* logic:
*
*
* -
*
* Determine which of the container instances in your cluster can support your service's task definition (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 (although
* you can choose a different placement strategy):
*
*
* -
*
* Sort the valid container instances by the fewest number of running tasks for this service in the same
* Availability Zone as the instance. 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.
*
*
*
*
*
*
* When the service scheduler stops running tasks, it attempts to maintain balance across the Availability Zones in
* your cluster using the following logic:
*
*
* -
*
* Sort the container instances by the largest number of running tasks for this service in the same Availability
* Zone as the instance. For example, if zone A has one running service task and zones B and C each have two,
* container instances in either zone B or C are considered optimal for termination.
*
*
* -
*
* Stop the task on a container instance in an optimal Availability Zone (based on the previous steps), favoring
* container instances with the largest number of running tasks for this service.
*
*
*
*
* @param updateServiceRequest
* @return Result of the UpdateService operation returned by the service.
* @throws ServerException
* These errors are usually caused by a server issue.
* @throws ClientException
* These errors are usually caused by a client action, such as using an action or resource on behalf of a
* user that doesn't have permission to use the action or resource, or specifying an identifier that is not
* valid.
* @throws InvalidParameterException
* The specified parameter is invalid. Review the available parameters for the API request.
* @throws ClusterNotFoundException
* The specified cluster could not be found. You can view your available clusters with ListClusters.
* Amazon ECS clusters are region-specific.
* @throws ServiceNotFoundException
* The specified service could not be found. You can view your available services with ListServices.
* Amazon ECS services are cluster-specific and region-specific.
* @throws ServiceNotActiveException
* The specified service is not active. You cannot update a service that is not active. If you have
* previously deleted a service, you can re-create it with CreateService.
* @sample AmazonECS.UpdateService
* @see AWS API
* Documentation
*/
UpdateServiceResult updateService(UpdateServiceRequest updateServiceRequest);
/**
* Shuts down this client object, releasing any resources that might be held open. This is an optional method, and
* callers are not expected to call it, but can if they want to explicitly release any open resources. Once a client
* has been shutdown, it should not be used to make any more requests.
*/
void shutdown();
/**
* Returns additional metadata for a previously executed successful request, typically used for debugging issues
* where a service isn't acting as expected. This data isn't considered part of the result data returned by an
* operation, so it's available through this separate, diagnostic interface.
*
* Response metadata is only cached for a limited period of time, so if you need to access this extra diagnostic
* information for an executed request, you should use this method to retrieve it as soon as possible after
* executing a request.
*
* @param request
* The originally executed request.
*
* @return The response metadata for the specified request, or null if none is available.
*/
ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request);
AmazonECSWaiters waiters();
}