Amazon ECS cluster

ECS Cluster targets are used by the ECS steps to define the context in which deployments and scripts are run.

Refer to the AWS documentation for detailed instructions on how to provision a new ECS cluster.

From Octopus 2022.2, ECS Cluster targets can be discovered using tags on your cluster resource.

Discovering ECS cluster targets

Octopus can discover ECS cluster targets as part of your deployment using tags on your resource.

From Octopus 2022.3, you can configure the well-known variables used to discover ECS Cluster targets when editing your deployment process in the Web Portal. See cloud target discovery for more information.

To discover targets use the following steps:

  • Add an AWS account variable named Octopus.Aws.Account to your project, or configure your worker with credentials that will allow your target to be discovered. See AWS discovery configuration for more information on how to configure target discovery for AWS.
  • Add tags to your ECS cluster so that Octopus can match it to your deployment step and environment.
  • Add a Deploy Amazon ECS Service or Update Amazon ECS Service step to your deployment process. During deployment, the target role on the step will be used along with the environment being deployed to, to discover cluster targets to deploy to.

See cloud target discovery for more information.

Creating an ECS cluster target

  1. Navigate to Infrastructure ➜ Deployment Targets, and click ADD DEPLOYMENT TARGET.

  2. Select AWS and click ADD on the Amazon ECS Cluster target type.

  3. Enter a display name for the Amazon ECS Cluster.

  4. Select at least one environment for the target.

  5. Select at least one target role for the target.

  6. In the Authentication section (see Authentication below for more information):

    • Select whether to use an AWS account configured in Octopus or to use credentials from the worker on which your deployment runs.
    • Select an AWS account if necessary. If you don’t have an AWS Account defined yet, check our documentation on how to set one up.
    • Select whether to assume an IAM role during authentication.
  7. In the ECS Cluster section:

    • Enter the AWS region where the ECS cluster is running in AWS.
    • Enter a cluster name that matches the cluster name running in your AWS region.

    ECS Cluster Deployment Target Settings


There are multiple authentication options supported for ECS clusters.

Worker credentials

Authentication can be configured to use credentials from the worker on which a deployment or cluster health check runs. AWS supports sourcing these credentials in several different ways, including environment variables and EC2 instance roles. See Setting credentials in node.js for more information on the different ways credentials can be provided.

To configure the ECS cluster to use worker credentials select the “Use credentials provided on the worker” option in the Credentials field.

ECS Cluster Worker Credentials

AWS Account

Authentication can be configured to use an AWS Account. To configure your ECS cluster to use an account select the “Use account” option in the Credentials field.

ECS Cluster Account Credentials

Assuming an IAM role

AWS supports assuming a specific role when interacting with services, allowing you to configure granular permissions for a given operation. See Using IAM roles for more information on using and assuming roles.

To configure the ECS cluster to use an assumed role select the “Assume role” option in the Assume IAM role field.

When assuming a role there are a number of options which can be configured.

Role ARNThe ARN of the role to be assumedY
Session NameThe name of the session to use when assuming the role. If this is not provided a default session will be automatically generated.N
Session DurationThe duration that the session will be available for. If this is not provided the default session duration for the role will be used.N
External IDAn external ID which can be provided to authorize third-party access. See the AWS documentation on External Id for more informationN

ECS Cluster Assume Role

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, October 4, 2023