awsecs

README

go-awsecs

Library and tools for AWS ECS operations.

contributing

See CONTRIBUTING.md.

tools

update-aws-ecs-service

Reliably update a single ECS service with a single simple discrete command.

Is a deployment tool inspired by AWS CodePipeline image definitions file method for updating existing ECS services. This tool is first and foremost an acknowledgment that orchestrating application deployments is a hard problem and does not attempt to solve that, instead, it tries to do something similar to AWS CodePipeline in a standalone fashion without depending on AWS CodePipeline, and more importantly without having to create individual AWS CodePipeline pipelines.

Get:

Grab binary distribution from releases tab. Or.

go get -v -u github.com/Autodesk/go-awsecs/cmd/update-aws-ecs-service

Use¹:

update-aws-ecs-service --help
Usage of ./update-aws-ecs-service:
  -cluster string
    	cluster name
  -container-envvar value
    	container-name=envvar-name=envvar-value
  -container-image value
    	container-name=image
  -container-logopt value
    	container-name=logdriver=logopt=value
  -container-logsecret value
    	container-name=logdriver=logsecret=valuefrom
  -container-secret value
    	container-name=secret-name=secret-valuefrom
  -desired-count int
    	desired-count (negative: no change) (default -1)
  -profile string
    	profile name
  -region string
    	region name
  -service string
    	service name
  -task-role string
    	task iam role, set to "None" to clear
  -taskdef string
    	base task definition (instead of current)

Example.

First, build and push a new Docker image for your service somewhere else.

docker build -t myrepo/myimg:newtag .
docker push myrepo/myimg:newtag

Then, alter the existing container image only, like AWS CodePipeline does.

update-aws-ecs-service \
  -cluster mycluster \
  -service myservice \
  -container-image mycontainer=myrepo/myimg:newtag
# default timeout for the operation is 15 minutes

You may also alter more than one container at the same time.

update-aws-ecs-service \
  -cluster mycluster \
  -service myservice \
  -container-image mycontainer1=myrepo/myimg1:newtag \
  -container-image mycontainer2=myrepo/myimg2:newtag

Alternatively, you can also alter environment variables and service desired count.

update-aws-ecs-service \
  -cluster mycluster \
  -service myservice \
  -container-image mycontainer=myrepo/myimg:newtag \
  -container-envvar mycontainer=envvarname=envvarvalue \
  -desired-count 1

💡 Use the empty value on -container-envvar or -container-secret to unset (K.O.) the environment variable or secret. Example.

update-aws-ecs-service \
  -cluster mycluster \
  -service myservice \
  -container-envvar mycontainer=myenvvarname= \
  -container-secret mycontainer=mysecretname= \

💡 Combined updates are possible. For example: "Update the application container image and adjust the awslogs log driver options for the sidecar container."

update-aws-ecs-service \
  -cluster example \
  -service service1-application1 \
  -container-image application=example.com/service1/application1:1a2b3c4 \
  -container-logopt sidecar=awslogs=awslogs-group=/com/example/service1/application1 \
  -container-logopt sidecar=awslogs=awslogs-stream-prefix=sidecar-1a2b3c4

update-aws-ecs-service compared to AWS CodePipeline

• With update-aws-ecs-service there is no need to create individual AWS CodePipeline pipelines per service
• update-aws-ecs-service allow updates of container definitions "Environment" and "Secrets"

update-aws-ecs-service compared to AWS CLI

Although similar results can be achieved glueing multiple awscli commands, a single update-aws-ecs-service is different.

• aws ecs update-service only invokes UpdateService which is an async call
• aws ecs wait services-stable is not linked to the ECS Deployment Entity² returned by UpdateService
• update-aws-ecs-service provides automatic rollback

update-aws-ecs-service compared to Terraform

It is a known issue that Terraform, does not wait for an ECS Service to be updated, a decision made probably by design by Hashicorp.

However, update-aws-ecs-service can be used in conjunction with Terraform, just keep in mind that when provisioning a service, start with an "initial task definition", and configure the lifecycle of the task_definition attribute to ignore_changes.

resource "aws_ecs_service" "my_service" {
  task_definition = "my_initial_task_def"
  // ...

  lifecycle {
    ignore_changes = ["task_definition" /* ... */]
  }
}

That way Terraform will be maintained as the "provisioning tool" and update-aws-ecs-service as the "deployment tool".

update-aws-ecs-service compared to Terraform+scripts

• Why not just do aws ecs wait services-stable commands after the terraform apply command

  Caveat 1: wait evaluates service stability but not that the desired deployment is applied the service may have become stable because it was rolled back or rolled forward somewhere else, there is no certainty that "our" deployment was the one that rendered the service stable

  Caveat 2: wait does not handle service deployment rollback

• Why not just do curl|httpie commands after the terraform apply command until a desired result is obtained probably after a number of times, for example by looking at an endpoint that returns the "deployed version" like: http://myservice.example.com/api/version returns {"version": "v2.0.0"}

  Caveat 1: This works only for services which are public (internet reachable) or reachable from the same location where curl|httpie is executed, this is not always the case, some services are internal or not reachable from every location

  Caveat 2: Works only for HTTP services that provide a "version" endpoint

update-aws-ecs-service compared to AWS CodeDeploy

TBC³.

update-aws-ecs-service compared to amazon-ecs-cli

TBC.

update-aws-ecs-service compared to ecs-deploy

The ecs-deploy script doesn't recognize multi-container tasks.

update-aws-ecs-service compared to ecs-goploy

ecs-goploy as a re-implementation of ecs-deploy shares the same caveats.

update-aws-ecs-service compared to Autodesk CloudOS

update-aws-ecs-service is not a framework, is just a tool to update existing AWS ECS services. You just need to know how to build Docker images.

update-aws-ecs-service compared to X

TBC.

enforce-aws-ecs-asg-launchconfig

This tool is useful to ensure that all EC2 instances in a ECS cluster backed up by a ASG share the launch configuration defined in the ASG. This tool does not work with launch templates! ECS EC2 Container Instances will be drained. EC2 Instances will be terminated (after they have been drained).

Important: Depending of your cluster service(s) deployment configuration, services will experiment downtime. For example use a service deployment configuration like, "Minimum healthy percent": 100 and "Maximum percent": 200 to prevent downtime enforce-aws-ecs-asg-launchconfig does not do anything special to prevent downtime it depends entirely of your cluster service(s) specific configuration(s).

Get:

Grab binary distribution from releases tab. Or.

go get -v -u github.com/Autodesk/go-awsecs/cmd/enforce-aws-ecs-asg-launchconfig

Use:

enforce-aws-ecs-asg-launchconfig --help
Usage of enforce-aws-ecs-asg-launchconfig:
  -asg string
    	asg name
  -cluster string
    	cluster name
  -profile string
    	profile name
  -region string
    	region name

Example:

enforce-aws-ecs-asg-launchconfig \
  -asg myasgname \
  -cluster myclustername
# default timeout for the operation is 15 minutes

---

1. https://unix.stackexchange.com/a/111557/19393
2. https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Deployment.html
3. To Be Compared

Documentation

Index

• Constants
• Variables
• type ECSServiceUpdate
  • func (e *ECSServiceUpdate) Apply() error
• type EnforceLaunchConfig
  • func (e *EnforceLaunchConfig) Apply() error

Constants

const (
	WaitUntilPrimaryRolled   = "primary-rolled"
	WaitUntilDrainingStarted = "draining-started"
)

const TaskRoleKnockoutValue = "None"

TaskRoleKnockoutValue when passed value matches the task role is set to nil

Variables

var (
	// ErrNothingToRollback nothing to rollback
	ErrNothingToRollback = errors.New("nothing to rollback")
	// ErrPermanentNothingToRollback permanent nothing to rollback
	ErrPermanentNothingToRollback = backoff.Permanent(ErrNothingToRollback)
	// ErrSuccessfulRollback successful rollback
	ErrSuccessfulRollback = errors.New("successful rollback")
	// ErrFailedRollback failed rollback
	ErrFailedRollback = errors.New("failed rollback")
)

var (
	// EnvKnockOutValue value used to knock off environment variables
	EnvKnockOutValue = ""
	// ErrDeploymentChangedElsewhere the deployment was changed elsewhere
	ErrDeploymentChangedElsewhere = errors.New("the deployment was changed elsewhere")
	// ErrOtherThanPrimaryDeploymentFound service update didn't complete
	ErrOtherThanPrimaryDeploymentFound = errors.New("other than PRIMARY deployment found")
	// ErrNotRunningDesiredCount service update completed but number of containers not matching desired count
	ErrNotRunningDesiredCount = errors.New("not running the desired count")
	// ErrServiceNotFound trying to update a service that doesn't exist
	ErrServiceNotFound = errors.New("the service does not exist")
	// ErrWaitingForDrainingState the service doesn't have any target which transitioned to draining state
	ErrWaitingForDrainingState = errors.New("waiting for draining state")
	// ErrInvalidWaitUntil received an invalid wait until
	ErrInvalidWaitUntil = errors.New("invalid wait until received")
	// ErrServiceDeletedAfterUpdate service was updated and then deleted elsewhere
	ErrServiceDeletedAfterUpdate = backoff.Permanent(errors.New("the service was deleted after the update"))
	// ErrContainerInstanceNotFound the container instance was removed from the cluster elsewhere
	ErrContainerInstanceNotFound = backoff.Permanent(errors.New("container instance not found"))
	// ErrLoadBalancerNotConfigured the service doesn't have a load balancer configured
	ErrLoadBalancerNotConfigured = backoff.Permanent(errors.New("the service was deleted after the update"))
)

var WaitUntilOptionList = []string{WaitUntilPrimaryRolled, WaitUntilDrainingStarted}

Types

type ECSServiceUpdate

type ECSServiceUpdate struct {
	EcsApi           ecsiface.ECSAPI                         // ECS Api
	ElbApi           elbv2iface.ELBV2API                     // ELBV2 Api
	Cluster          string                                  // Cluster which the service is deployed to
	Service          string                                  // Name of the service
	Image            map[string]string                       // Map of container names and images
	Environment      map[string]map[string]string            // Map of container names environment variable name and value
	Secrets          map[string]map[string]string            // Map of container names environment variable name and valueFrom
	LogDriverOptions map[string]map[string]map[string]string // Map of container names log driver name log driver option and value
	LogDriverSecrets map[string]map[string]map[string]string // Map of container names log driver name log driver secret and valueFrom
	TaskRole         string                                  // Task IAM Role if TaskRoleKnockoutValue used, it is cleared
	DesiredCount     *int64                                  // If nil the service desired count is not altered
	BackOff          backoff.BackOff                         // BackOff strategy to use when validating the update
	Taskdef          string                                  // If non empty used as base task definition instead of the current task definition
	WaitUntil        *string                                 // Decide wether to wait until the service "started-draining" (only valid for services with Load Balancers attached) or until the deployment "primary-rolled" (default)
}

ECSServiceUpdate encapsulates the attributes of an ECS service update

func (*ECSServiceUpdate) Apply

func (e *ECSServiceUpdate) Apply() error

Apply the ECS Service Update

type EnforceLaunchConfig

type EnforceLaunchConfig struct {
	ECSAPI         ecs.ECS
	ASAPI          autoscaling.AutoScaling
	EC2API         ec2.EC2
	ASGName        string
	ECSClusterName string
	BackOff        backoff.BackOff
}

EnforceLaunchConfig encapsulates the attributes of a LaunchConfig enforcement

func (*EnforceLaunchConfig) Apply

func (e *EnforceLaunchConfig) Apply() error

Apply the LaunchConfig enforcement