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
Use1:
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-servicethere is no need to create individual AWS CodePipeline pipelines per service update-aws-ecs-serviceallow 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-serviceonly invokesUpdateServicewhich is an async callaws ecs wait services-stableis not linked to the ECS Deployment Entity2 returned byUpdateServiceupdate-aws-ecs-serviceprovides 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-stablecommands after theterraform applycommandCaveat 1:
waitevaluates 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 stableCaveat 2:
waitdoes not handle service deployment rollback -
Why not just do
curl|httpiecommands after theterraform applycommand 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|httpieis executed, this is not always the case, some services are internal or not reachable from every locationCaveat 2: Works only for HTTP services that provide a "version" endpoint
update-aws-ecs-service compared to AWS CodeDeploy
TBC3.
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
Documentation
¶
Index ¶
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}
Functions ¶
This section is empty.
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
Source Files
Directories