{"id":20471784,"url":"https://github.com/signiant/ecs-cluster-scaledown","last_synced_at":"2026-04-18T05:31:01.847Z","repository":{"id":93380923,"uuid":"110286284","full_name":"Signiant/ecs-cluster-scaledown","owner":"Signiant","description":"Automatically manually Scale down ECS cluster","archived":false,"fork":false,"pushed_at":"2025-08-19T20:57:46.000Z","size":47,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-19T22:31:52.376Z","etag":null,"topics":["aws","ecs","hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Signiant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-10T19:46:17.000Z","updated_at":"2025-08-19T20:57:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"76a7c352-a87a-432c-a508-14933eb25c39","html_url":"https://github.com/Signiant/ecs-cluster-scaledown","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Signiant/ecs-cluster-scaledown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Signiant%2Fecs-cluster-scaledown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Signiant%2Fecs-cluster-scaledown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Signiant%2Fecs-cluster-scaledown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Signiant%2Fecs-cluster-scaledown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Signiant","download_url":"https://codeload.github.com/Signiant/ecs-cluster-scaledown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Signiant%2Fecs-cluster-scaledown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31957533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","ecs","hacktoberfest"],"created_at":"2024-11-15T14:17:13.907Z","updated_at":"2026-04-18T05:31:01.840Z","avatar_url":"https://github.com/Signiant.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ecs-cluster-scaledown\nScale down a given ECS cluster by a given count\n\n# Purpose\nAt times it may be desirable to enabled autoscaling of an ECS cluster in only one direction - up. Reasons\nfor this might include having long running tasks that are indeterministic in duration which don't lend\nthemselves to being scaled down easily or in the usual manner. Of course the downside to a cluster that\nis only enabled to scale up is that the cluster can end up being significantly over provisioned, \ndepending on how the autoscaling is configured.\n\nWhile manually scaling the cluster down is possible, it's certainly a pain. Obviously the solution is\nto automate the process. This solution will perform the following steps to scale down an ECS cluster:\n* check for any instances in a DRAINING state and attempt to remove them from the cluster (see below)\n* get a list of the ACTIVE instances in the given cluster, and order them by load (number of tasks)\n* put X number of instances into a DRAINING state\n* attempt to remove them from the cluster (see below)\n\nNote: When attempting to remove instances from the cluster, the following conditions need to be met:\n* no running tasks on the instance OR\n* only tasks matching the ignore list running on the instance\n\nIf the above conditions are met, then the following happens:\n* terminate the instance(s) and decrement the desired count in the autoscaling group\n \nAlternatively, an instance ID can be specified to be selectively removed from the cluster. Note that this\ninstance MUST be in a DRAINING state already.\n\n# Solutions\nTwo separate solutions are provided here. You can run this in a docker container (and hence schedule it as an ECS\ntask) or you can run it as a lambda (and schedule the lambda run)\n\n## Lambda based\n\n### Usage\nThis tool was developed with the idea of it being run periodically. This can be accomplished using a lambda that\nis scheduled to be invoked on a periodic basis - that way if an instance wasn't able to be immediately removed from\nthe cluster (due to running tasks on that instance), the instance would get removed in a subsequent run of the tool.\n\nIncluded here is a sample samconfig.yaml file that can be filled in with appropriate values. If you would like to\noperate on more than one cluster (eg. multiple regions) then you can modify the template.yaml and add more events\nsimilar to the exiting `ScheduleUsEast1` event\n\nOnce all values have been filled in, you can build and deploy the lambda as follows:\n\n```bash\ncd lambda\nsam build \u0026\u0026 sam deploy --config-env prod --profile \u003caws_cli_profile_name\u003e\n```\n\n\n## Docker based\n### Prerequisites\n* Docker must be installed\n* Either an AWS role (if running on EC2) or an access key/secret key\n\n### Usage\n\nThis tool was developed with the idea of it being run periodically (as an ECS scheduled task, although \ngenerally speaking, a simple cron job would also work) - that way if an instance wasn't able to be\nimmediately removed from the cluster (due to running tasks on that instance), the instance would get\nremoved in a subsequent run of the tool.\n\nThe easiest way to run the tool is from docker (because docker rocks).\nYou will need to pass in variables specific to the ECS task you want to affect\n\n```bash\nusage: ecs_cluster_scaledown.py [-h] [--aws-access-key-id AWS_ACCESS_KEY]\n                                [--aws-secret-access-key AWS_SECRET_KEY]\n                                --cluster-name CLUSTER_NAME [--count COUNT]\n                                [--instance-ids INSTANCE_IDS [INSTANCE_IDS ...]]\n                                [--ignore-list IGNORE_LIST [IGNORE_LIST ...]]\n                                [--alarm-name ALARM_NAME] --region REGION\n                                [--profile PROFILE] [--verbose] [--dryrun]\n\necs_cluster_scaledown\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --aws-access-key-id AWS_ACCESS_KEY\n                        AWS Access Key ID\n  --aws-secret-access-key AWS_SECRET_KEY\n                        AWS Secret Access Key\n  --cluster-name CLUSTER_NAME\n                        Cluster name\n  --count COUNT         Number of instances to remove [1]\n  --instance-ids INSTANCE_IDS [INSTANCE_IDS ...]\n                        Instance ID(s) to be removed\n  --ignore-list IGNORE_LIST [IGNORE_LIST ...]\n                        Tasks to be ignored when determining running tasks\n  --alarm-name ALARM_NAME\n                        Alarm name to check if scale down should be attempted\n  --region REGION       The AWS region the cluster is in\n  --profile PROFILE     The name of an aws cli profile to use.\n  --verbose             Turn on DEBUG logging\n  --dryrun              Do a dryrun - no changes will be performed\n```\n\n### Examples\n\n```bash\ndocker pull signiant/ecs-cluster-scaledown\n```\n\n```bash\ndocker run \\\n   signiant/ecs-cluster-scaledown \\\n       --cluster-name test-cluster \\\n       --count 2 \\\n       --region us-east-1 \\\n       --dryrun\n```\n\nIn this example, the arguments after the image name are\n\n* --cluster-name \u003cECS cluster name\u003e\n* --count \u003cNumber of instances to scale down by\u003e\n* --region \u003cAWS region\u003e\n* --dryrun (don't actually scale down - display only)\n\nIn the above example, we tell the task to scale down the cluster by 2 instances. Note that no AWS\naccess key or secret access key, or even an AWS profile are provided - in this case the task was run\nas a scheduled task in an ECS cluster using an IAM Role, hence they weren't needed.\n\nTo use an AWS access key/secret key rather than a role:\n\n```bash\ndocker run \\\n  -e AWS_ACCESS_KEY_ID=XXXXXX \\\n  -e AWS_SECRET_ACCESS_KEY=XXXXX \\\n  signiant/ecs-cluster-scaledown \\\n        --cluster-name test-cluster \\\n        --region us-east-1 \\\n        --alarm-name 'Cluster blart scale down'\n```\n\nIn the above example, we tell the task to scale down the cluster by 1 instance (no --count argument was\ngiven, so it uses the default of 1). The first thing the task will do is check the StateValue of the given\nalarm to make sure it is in 'ALARM' state before proceeding - if it isn't, the task exits immediately.\n\n```bash\ndocker run \\\n  signiant/ecs-cluster-scaledown \\\n        --cluster-name test-cluster \\\n        --region us-east-1 \\\n        --ignore-list LogspoutTask\n```\n\nIn the above example, we tell the task to scale down the cluster by 1 instance (no --count argument was\ngiven, so it uses the default of 1). In this case no alarm is given, so a cluster scale down will be \nalways be attempted. (Note that the autoscaling group associated with this cluster is always queried for\nthe minimum size and a scale down will only be attempted provided it will not result in the cluster size\nfalling below the minimum) In this case an ignore list is also provided - any tasks matching items in the\ngiven ignore list will be ignored when checking instances for running tasks.\n\n```bash\ndocker run \\\n  signiant/ecs-cluster-scaledown \\\n        --cluster-name test-cluster \\\n        --region us-east-1 \\\n        --instance-ids i-0x1x2x3x4x5x6x7x8 i-0x2x3x4x5x6x7x8x9 i-3x4x5x6x7x8x9x0x1\n```\n\nIn the above example, we tell the task to scale down the cluster by the given instances. Note that \ninstances will be removed in the order they are listed.\n\nNOTE: To clear out any instances in a DRAINING state *without* scaling down the cluster, provide a count\nof 0, eg:\n\n```bash\ndocker run \\\n  signiant/ecs-cluster-scaledown \\\n        --cluster-name test-cluster \\\n        --region us-east-1 \\\n        --ignore-list LogspoutTask\n        -- count 0\n```\n\n\n# Warnings / Known Issues\n\nCurrent only handles clusters that contain instances in a maximum of 2 availability zones.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsigniant%2Fecs-cluster-scaledown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsigniant%2Fecs-cluster-scaledown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsigniant%2Fecs-cluster-scaledown/lists"}