{"id":13689735,"url":"https://github.com/trajano/terraform-docker-swarm-aws","last_synced_at":"2025-08-09T08:29:23.855Z","repository":{"id":33533495,"uuid":"139270418","full_name":"trajano/terraform-docker-swarm-aws","owner":"trajano","description":"Terraform script to set up a Docker Swarm on AWS","archived":false,"fork":false,"pushed_at":"2024-06-18T02:25:34.000Z","size":360,"stargazers_count":45,"open_issues_count":5,"forks_count":27,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-09T04:24:29.323Z","etag":null,"topics":["aws","docker","docker-swarm","terraform","terraform-module"],"latest_commit_sha":null,"homepage":"https://registry.terraform.io/modules/trajano/swarm-aws/docker/","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trajano.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","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":"2018-06-30T18:15:03.000Z","updated_at":"2024-10-14T08:48:34.000Z","dependencies_parsed_at":"2023-11-28T00:25:31.297Z","dependency_job_id":"a0fddd2c-4c8d-4cee-aeb1-700310fdca29","html_url":"https://github.com/trajano/terraform-docker-swarm-aws","commit_stats":null,"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trajano%2Fterraform-docker-swarm-aws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trajano%2Fterraform-docker-swarm-aws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trajano%2Fterraform-docker-swarm-aws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trajano%2Fterraform-docker-swarm-aws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trajano","download_url":"https://codeload.github.com/trajano/terraform-docker-swarm-aws/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230174960,"owners_count":18184923,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","docker","docker-swarm","terraform","terraform-module"],"created_at":"2024-08-02T16:00:23.701Z","updated_at":"2025-08-09T08:29:23.839Z","avatar_url":"https://github.com/trajano.png","language":"HCL","funding_links":[],"categories":["HCL","Community Tools"],"sub_categories":["Cluster Management"],"readme":"# AWS Docker Swarm Terraform Module\n\nThis is a Terraform configuration that sets up a Docker Swarm on an existing VPC with a configurable amount of managers and worker nodes. The swarm is configured to have [SSH daemon access][ssh-daemon] enabled by default with [EC2 instance monitoring](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/mon-scripts.html).\n\n## Terraformed layout\n\nIn the VPC there will be 2 x _number of availability zones in region_ subnets created. Each EC2 instance will be placed in an subnet in a round-robin fashion.\n\nThere are no elastic IPs allocated in the module in order to prevent using up the elastic IP allocation for the VPC. It is up to the caller to set that up.\n\n## Prerequisites\n\nThe `aws` provider is configured in your TF file.\n\nAWS permissions to do the following:\n\n- Manage EC2 resource\n- Security Groups\n- IAM permissions\n- SNS\n- Cloudwatch Alarms\n\nThe `examples/iam-policies` shows the policy JSONs that are used.\n\nFor earlier versions of the module, *S3 Create and Access* was required to store the tokens.  Tags are used in the current releases to save on S3 costs.  This method is has been depreacted and removed as of v6.0.0.\n\n## Limitations\n\n- Maximum of 240 docker managers.\n- Maximum of 240 docker workers.\n- Only one VPC and therefore only one AWS region.\n- The VPC must have to following properties\n  - The VPC should have access to the Internet\n  - The DNS hostnames support must be enabled (otherwise the node list won't work too well)\n  - VPC must have a CIDR block mask of `/16`.\n\n## Example\n\nThe `examples/simple` folder shows an example of how to use this module.\n\n## Cloud Config merging\n\nThe default merge rules of cloud-config is used which may yield unexpected results (see [cloudconfig merge behaviours](https://jen20.com/2015/10/04/cloudconfig-merging.html)) if you are changing existing keys. To bring back the merge behaviour from 1.2 add\n\n    merge_how: \"list(append)+dict(recurse_array)+str()\"\n\n## Upgrading the swarm\n\nThough `yum update` can simply update the software, it may be required to update things that are outside such as updates to the module itself, `cloud_config_extra` information or AMI updates.  For this to work, you need to have at least 3 managers otherwise you'd lose raft consensus and have to rebuild the swarm from scratch.\n\n### Example of how to upgrade a 3 manager swawrm\n\nUpgrading a 3 manager swarm needs to be done one at a time to prevent raft consensus loss.\n\n1. Make `manager0` leave the swarm by executing `ssh \u003cusername\u003e@\u003cmanager0\u003e sudo /root/bin/leave-swarm.sh`\n2. Taint `manager0` from the command line `terraform taint module.docker-swarm.aws_instance.managers[0]`\n3. Rebuild `manager0` from the command line `terraform apply`\n4. Wait until `manager0` rejoins the swarm by checking `docker node ls`\n5. Make `manager1` leave the swarm by executing  `ssh \u003cusername\u003e@\u003cmanager1\u003e sudo /root/bin/leave-swarm.sh`\n6. Taint `manager1` from the command line `terraform taint module.docker-swarm.aws_instance.managers[1]`\n7. Rebuild `manager1` from the command line `terraform apply`\n8. Wait until `manager1` rejoins the swarm by checking `docker node ls`\n9. Make `manager2` leave the swarm by executing `ssh \u003cusername\u003e@\u003cmanager2\u003e sudo /root/bin/leave-swarm.sh`\n10. Taint `manager2` from the command line `terraform taint module.docker-swarm.aws_instance.managers[2]`\n11. Rebuild `manager2` from the command line `terraform apply`\n12. Wait until `manager2` rejoins the swarm by checking `docker node ls`\n13. Prune the nodes that are down and are drained `ssh \u003cusername\u003e@\u003cmanager0\u003e sudo /root/bin/prune-nodes.sh`\n\n### Upgrading the worker nodes\n\nA future relase of this would utilize auto-scaling for now this needs to be done manually\n\n1. Drain and remove the worker node(s) from the swarm using `ssh \u003cusername\u003e@\u003cmanager0\u003e sudo /root/bin/rm-workers.sh \u003cnodename[s]\u003e`\n2. Taint the workers that are removed from the command line `terraform taint module.docker-swarm.aws_instance.workers[#]`\n3. Rebuild the workers from the command line `terraform apply`\n\n## Other tips\n\n- Don't use Terraform to provision your containers, just let it build the infrastructure and add the hooks to connect it to your build system.\n- To use a different version of Docker create a custom cloud config with\n\n      packages:\n      - [docker, 18.03.1ce-2.amzn2]\n      - haveged\n      - python2-boto3\n      - yum-cron\n      - ec2-instance-connect\n      - perl-Switch\n      - perl-DateTime\n      - perl-Sys-Syslog\n      - perl-LWP-Protocol-https\n      - perl-Digest-SHA.x86_64\n\n- Add additional SSH users using `sudo /root/bin/add-docker-user.sh \u003cusername\u003e \u003cssh key string\u003e`.  Note this creates users in such a way that it only allows the use of `docker context`\n- The servers are built with ElasticSearch and Redis containers in mind and the following documents specify the changes that are implemented as part of Terraform:\n  - [ElasticSearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-prod-prerequisites)\n  - [Redis](https://redis.io/topics/faq#background-saving-fails-with-a-fork-error-under-linux-even-if-i-have-a-lot-of-free-ram)\n\n[ssh-daemon]: https://github.com/docker/cli/pull/1014\n[haveged]: http://issihosts.com/haveged/\n[ec2-instance-connect]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Connect-using-EC2-Instance-Connect.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrajano%2Fterraform-docker-swarm-aws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrajano%2Fterraform-docker-swarm-aws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrajano%2Fterraform-docker-swarm-aws/lists"}