Octopus Deploy Documentation

Amazon ECS cluster

Last updated

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

Authentication

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.

Field Description Required
Role ARN The ARN of the role to be assumed Y
Session Name The name of the session to use when assuming the role. If this is not provided a default session will be automatically generated. N
Session Duration The 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 ID An external ID which can be provided to authorize third-party access. See the AWS documentation on External Id for more information N

ECS Cluster Assume Role

Need support? We're here to help.