Amazon ECS
User Guide for AWS Fargate (API Version 2014-11-13)

External Deployment

The external deployment type enables you to use any third-party deployment controller for full control over the deployment process for an Amazon ECS service. The details for your service are managed by either the service management API actions (CreateService, UpdateService, and DeleteService) or the task set management API actions (CreateTaskSet, UpdateTaskSet, UpdateServicePrimaryTaskSet, and DeleteTask). Each API action has a subset of the service definition parameters that it can manage.

The UpdateService API action updates the desired count and health check grace period parameters for a service. If the launch type, platform version, load balancer details, network configuration, or task definition need to be updated, you must create a new task set.

The UpdateTaskSet API action updates only the scale parameter for a task set.

The UpdateServicePrimaryTaskSet API action modifies which task set in a service is the primary task set. When you call the DescribeServices API action, it returns all fields specified for a primary task set. If the primary task set for a service is updated, any task set parameter values that exist on the new primary task set that differ from the old primary task set in a service are updated to the new value when a new primary task set is defined. If no primary task set is defined for a service, when describing the service, the task set fields are null.

External Deployment Considerations

Consider the following when using the external deployment type:

  • Service auto scaling is not supported when using an external deployment controller.

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

External Deployment Workflow

The following is the basic workflow to managing an external deployment on Amazon ECS.

To manage an Amazon ECS service using an external deployment controller

  1. Create an Amazon ECS service. The only required parameter is the service name. You can specify the following parameters when creating a service using an external deployment controller. All other service parameters are specified when creating a task set within the service.

    serviceName

    The name of your service. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores 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.

    Required: Yes

    desiredCount

    The number of instantiations of the specified task set task definition to place and keep running within the service.

    deploymentConfiguration

    Optional deployment parameters that control how many tasks run during a deployment and the ordering of stopping and starting tasks. For more information, see deploymentConfiguration.

    tags

    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. Tag keys can have a maximum character length of 128 characters, and tag values can have a maximum length of 256 characters. For more information, see Tagging Your Amazon ECS Resources.

    key

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

    value

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

    enableECSManagedTags

    Specifies whether to enable Amazon ECS managed tags for the tasks within the service. For more information, see Tagging Your Resources for Billing.

    propagateTags

    Specifies whether to copy the tags from the task definition or the service to the tasks in the service. If no value is specified, the tags are not copied. Tags can only be copied to the tasks within the service during service creation. To add tags to a task after service creation, use the TagResource API action.

    healthCheckGracePeriodSeconds

    The period of time, in seconds, that the Amazon ECS service scheduler should ignore unhealthy Elastic Load Balancing target health checks, container health checks, and Route 53 health checks after a task has first started. This is only valid if your service is configured to use a load balancer. If your service's tasks take a while to start and respond to health checks, you can specify a health check grace period of up to 2,147,483,647 seconds during which the ECS service scheduler ignores the health check status. This grace period can prevent the ECS service scheduler from marking tasks as unhealthy and stopping them before they have time to come up.

    schedulingStrategy

    The scheduling strategy to use. Services using an external deployment controller support only the REPLICA scheduling strategy. For more information, see Service Scheduler Concepts.

    placementConstraints

    An array of placement constraint objects to use for tasks in your service. You can specify a maximum of 10 constraints per task (this limit includes constraints in the task definition and those specified at run time). If you are using the Fargate launch type, task placement constraints aren't supported.

    placementStrategy

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

    The following is an example service definition for a service using an external deployment controller.

    { "cluster": "", "serviceName": "", "desiredCount": 0, "role": "", "deploymentConfiguration": { "maximumPercent": 0, "minimumHealthyPercent": 0 }, "placementConstraints": [ { "type": "distinctInstance", "expression": "" } ], "placementStrategy": [ { "type": "binpack", "field": "" } ], "healthCheckGracePeriodSeconds": 0, "schedulingStrategy": "REPLICA", "deploymentController": { "type": "EXTERNAL" }, "tags": [ { "key": "", "value": "" } ], "enableECSManagedTags": true, "propagateTags": "TASK_DEFINITION" }
  2. Create an initial task set. The task set contains the following details about your service:

    taskDefinition

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

    launchType

    The launch type on which to run your service. Accepted values are FARGATE or EC2. If a launch type is not specified, EC2 is used by default. For more information, see Amazon ECS Launch Types.

    platformVersion

    The platform version on which your tasks in the service are running. A platform version is only specified for tasks using the Fargate launch type. If one is not specified, the latest version (LATEST) is used by default.

    AWS Fargate platform versions are used to refer to a specific runtime environment for the Fargate task infrastructure. When specifying the LATEST platform version when running a task or creating a service, you get the most current platform version available for your tasks. When you scale up your service, those tasks receive the platform version that was specified on the service's current deployment. For more information, see AWS Fargate Platform Versions.

    loadBalancers

    A load balancer object representing the load balancer to use with your service. When using an external deployment controller, only Application Load Balancers and Network Load Balancers are supported. If you're using an Application Load Balancer, only one Application Load Balancer target group is allowed per task set.

    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's not supported for other network modes. For more information, see Task Networking with the awsvpc Network Mode.

    serviceRegistries

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

    scale

    A floating-point percentage of the desired number of tasks to place and keep running in the task set. The value is specified as a percent total of a service's desiredCount. Accepted values are numbers between 0 and 100.

  3. When service changes are needed, use the UpdateService, UpdateTaskSet, or CreateTaskSet API action depending on which parameters you're updating. If you created a task set, use the scale parameter for each task set in a service to determine how many tasks to keep running in the service. For example, if you have a service that contains tasksetA and you create a tasksetB, you might test the validity of tasksetB before wanting to transition production traffic to it. You could set the scale for both task sets to 100, and when you were ready to transition all production traffic to tasksetB, you could update the scale for tasksetA to 0 to scale it down.