Contributions to this Package are very welcome! We follow a fairly standard pull request process for contributions, subject to the following guidelines:
Before starting any work, we recommend filing a GitHub issue in this repo. This is your chance to ask questions and
get feedback from the maintainers and the community before you sink a lot of time into writing (possibly the wrong)
code. If there is anything you're unsure about, just ask!
Update the documentation
We recommend updating the documentation before updating any code (see Readme Driven
Development). This ensures the documentation
stays up to date and allows you to think through the problem at a high level before you get lost in the weeds of
coding.
Update the tests
We also recommend updating the automated tests before updating any code (see Test Driven
Development). That means you add or update a test case,
verify that it's failing with a clear error message, and then make the code changes to get that test to pass. This
ensures the tests stay up to date and verify all the functionality in this Module, including whatever new
functionality you're adding in your contribution. Check out the tests folder for instructions on running the
automated tests.
Update the code
At this point, make your code changes and use your new test case to verify that everything is working. As you work,
keep in mind two things:
Backwards compatibility
Downtime
Backwards compatibility
Please make every effort to avoid unnecessary backwards incompatible changes. With Terraform code, this means:
Do not delete, rename, or change the type of input variables.
If you add an input variable, it should have a default.
Do not delete, rename, or change the type of output variables.
Do not delete or rename a module in the modules folder.
If a backwards incompatible change cannot be avoided, please make sure to call that out when you submit a pull request,
explaining why the change is absolutely necessary.
Downtime
Bear in mind that the Terraform code in this Module is used by real companies to run real infrastructure in
production, and certain types of changes could cause downtime. For example, consider the following:
If you rename a resource (e.g. aws_instance "foo" -> aws_instance "bar"), Terraform will see that as deleting
the old resource and creating a new one.
If you change certain attributes of a resource (e.g. the name of an aws_elb), the cloud provider (e.g. AWS) may
treat that as an instruction to delete the old resource and a create a new one.
Deleting certain types of resources (e.g. virtual servers, load balancers) can cause downtime, so when making code
changes, think carefully about how to avoid that. For example, can you avoid downtime by using
create_before_destroy? Or via
the terraform state command? If so, make sure to note this in our pull request. If downtime cannot be avoided,
please make sure to call that out when you submit a pull request.
Formatting and pre-commit hooks
You must run terraform fmt on the code before committing. You can configure your computer to do this automatically
using pre-commit hooks managed using pre-commit:
A description of the change, including a link to your GitHub issue.
The output of your automated test run, preferably in a GitHub Gist. We cannot run
automated tests for pull requests automatically due to security
concerns, so we need you to manually provide this
test output so we can verify that everything is working.
Any notes on backwards incompatibility or downtime.
Merge and release
The maintainers for this repo will review your code and provide feedback. If everything looks good, they will merge the
code and release a new version, which you'll be able to find in the releases page.
Questions? Ask away.
We're here to talk about our services, answer any questions, give advice, or just to chat.
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"7374d1255fd61c4b4c97b904e90f97cd7597b7ca"},{"name":"post-upgrade-test-results.sh","path":".circleci/post-upgrade-test-results.sh","sha":"a4867e8fbdc334b7a90259568ee41ea577fbe764"},{"name":"set-upgrade-test-vars.sh","path":".circleci/set-upgrade-test-vars.sh","sha":"8d961461f09584ccd42432b5d56d64db43da1a6e"}]},{"name":".github","children":[{"name":"ISSUE_TEMPLATE","children":[{"name":"bug_report.md","path":".github/ISSUE_TEMPLATE/bug_report.md","sha":"d2e87e27c601e423865ed660ec697082470ca60f"},{"name":"feature_request.md","path":".github/ISSUE_TEMPLATE/feature_request.md","sha":"023a33099be2336476930c96e17ff1ba5dc55348"}]},{"name":"pull_request_template.md","path":".github/pull_request_template.md","sha":"6b100e40e323b5b07f40ed30616277c51c9f4b9e"}]},{"name":".gitignore","path":".gitignore","sha":"fd04ff401a18d9c8595968dbbd3a9996d37b6a8b"},{"name":".pre-commit-config.yaml","path":".pre-commit-config.yaml","sha":"605d316ff7fc0ae6e303f790b71c61a2dc31337a"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"5ec6c488d1e6577b86c42b21fb2daf162c3e160a"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","sha":"c992069269419c83cb1f032fd80124cdca22fb02","toggled":true},{"name":"LICENSE.txt","path":"LICENSE.txt","sha":"f4e3d9bd4717a044ed31ad847a300eee74371a78"},{"name":"README.md","path":"README.md","sha":"28a4240bb0352e8f94eb1f07dd6b602e5858990a"},{"name":"examples","children":[{"name":"asg-instance-refresh-with-launch-template","children":[{"name":"README.md","path":"examples/asg-instance-refresh-with-launch-template/README.md","sha":"a4aee07ff69ae8b4b095168c4f8f31a5168b3437"},{"name":"main.tf","path":"examples/asg-instance-refresh-with-launch-template/main.tf","sha":"f80f629dc70caf62a2389f3a3dc488f11fd6f396"},{"name":"outputs.tf","path":"examples/asg-instance-refresh-with-launch-template/outputs.tf","sha":"c8db3c807aab3d75888c2dd039b9e81b1312a137"},{"name":"variables.tf","path":"examples/asg-instance-refresh-with-launch-template/variables.tf","sha":"d4d4c041884de1f2e31ca0d64c0f4a6031b88ea8"}]},{"name":"asg-instance-refresh","children":[{"name":"README.md","path":"examples/asg-instance-refresh/README.md","sha":"f566fae0867be0be2cecbd8ca6d20234c5cc17dc"},{"name":"with-elb","children":[{"name":"main.tf","path":"examples/asg-instance-refresh/with-elb/main.tf","sha":"13cb1ff317d66687de797feed5e0f83d8e528021"},{"name":"outputs.tf","path":"examples/asg-instance-refresh/with-elb/outputs.tf","sha":"330a02ec9378c2c9c4a1423b075384f4ae3ed241"},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/asg-instance-refresh/with-elb/user-data/user-data.sh","sha":"7b5fbe6f33805eb5356e9c49db9bd5b141b0816a"}]},{"name":"variables.tf","path":"examples/asg-instance-refresh/with-elb/variables.tf","sha":"2056963b26c09d4579a5a860075e4a7a3d7875e5"}]},{"name":"without-elb","children":[{"name":"main.tf","path":"examples/asg-instance-refresh/without-elb/main.tf","sha":"b458ffc6deb91c26382bd99c5381cc8ad2619db3"},{"name":"outputs.tf","path":"examples/asg-instance-refresh/without-elb/outputs.tf","sha":"c8db3c807aab3d75888c2dd039b9e81b1312a137"},{"name":"variables.tf","path":"examples/asg-instance-refresh/without-elb/variables.tf","sha":"42452d0ed062cf8afce3f23319bb5e81690d12a1"}]}]},{"name":"asg-rolling-deploy","children":[{"name":"README.md","path":"examples/asg-rolling-deploy/README.md","sha":"6b9a213c73ec5c5bff3b270695f9c6c749c0d642"},{"name":"with-elb","children":[{"name":"main.tf","path":"examples/asg-rolling-deploy/with-elb/main.tf","sha":"429845439e56161743cd20ec1c0688f7d65898e5"},{"name":"outputs.tf","path":"examples/asg-rolling-deploy/with-elb/outputs.tf","sha":"330a02ec9378c2c9c4a1423b075384f4ae3ed241"},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/asg-rolling-deploy/with-elb/user-data/user-data.sh","sha":"7b5fbe6f33805eb5356e9c49db9bd5b141b0816a"}]},{"name":"variables.tf","path":"examples/asg-rolling-deploy/with-elb/variables.tf","sha":"dab89e417460b5fa2676796e945acf27803c6553"}]},{"name":"without-elb","children":[{"name":"main.tf","path":"examples/asg-rolling-deploy/without-elb/main.tf","sha":"2e1ef6f1bebbbb62cecc48cc99930a8aeeaa53ac"},{"name":"outputs.tf","path":"examples/asg-rolling-deploy/without-elb/outputs.tf","sha":"c8db3c807aab3d75888c2dd039b9e81b1312a137"},{"name":"variables.tf","path":"examples/asg-rolling-deploy/without-elb/variables.tf","sha":"1d6d2ee9904841723c7e7c29d9fe5e12e7f6fd6a"}]}]},{"name":"server-group","children":[{"name":"README.md","path":"examples/server-group/README.md","sha":"10cda1da76dedb61ef2ff8ec8dc11a619d71fff9"},{"name":"ami","children":[{"name":"server.json","path":"examples/server-group/ami/server.json","sha":"01afa473255bad78f379b8bb6b6817f58b59adfe"}]},{"name":"with-alb","children":[{"name":"main.tf","path":"examples/server-group/with-alb/main.tf","sha":"6d5e6145442a965b1d743f5e4a6e3e8406372bd5"},{"name":"outputs.tf","path":"examples/server-group/with-alb/outputs.tf","sha":"3565caece2f11d61dc0b0a6ed23cc58ce7e6e61c"},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/server-group/with-alb/user-data/user-data.sh","sha":"55d5dff9d84f2e3793f6c669fd0cfa4bd65f287a"}]},{"name":"variables.tf","path":"examples/server-group/with-alb/variables.tf","sha":"dc708850a0e1169ba4101135f6a707e79bd82850"}]},{"name":"with-elb","children":[{"name":"main.tf","path":"examples/server-group/with-elb/main.tf","sha":"0de589319bf9e3acab48d7fd78021c8fc5426b8a"},{"name":"outputs.tf","path":"examples/server-group/with-elb/outputs.tf","sha":"fd38915d96770f9588e2fcc79369e64449492286"},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/server-group/with-elb/user-data/user-data.sh","sha":"3800df7ab47bf43e6253ebeb21d5900585d32b6a"}]},{"name":"variables.tf","path":"examples/server-group/with-elb/variables.tf","sha":"4eb70bfff00b837c8404d044fee311b16e0e0c73"}]},{"name":"without-load-balancer","children":[{"name":"main.tf","path":"examples/server-group/without-load-balancer/main.tf","sha":"66bf40bd0488db96cad11d4ba07ca480b4fa8f92"},{"name":"outputs.tf","path":"examples/server-group/without-load-balancer/outputs.tf","sha":"27911554f10688f23ba9f8e31eadd4409c635f97"},{"name":"user-data","children":[{"name":"user-data.sh","path":"examples/server-group/without-load-balancer/user-data/user-data.sh","sha":"55d5dff9d84f2e3793f6c669fd0cfa4bd65f287a"}]},{"name":"variables.tf","path":"examples/server-group/without-load-balancer/variables.tf","sha":"0724aa38905b313165b621e7866575e0e0abdd4b"}]}]}]},{"name":"modules","children":[{"name":"asg-instance-refresh","children":[{"name":"README.md","path":"modules/asg-instance-refresh/README.md","sha":"972cfd23e4a68b4b77839549b15392eaa1fbc0a3"},{"name":"main.tf","path":"modules/asg-instance-refresh/main.tf","sha":"a5a8f68d20d4a1197181ea24fda11a5d4fd7adbd"},{"name":"outputs.tf","path":"modules/asg-instance-refresh/outputs.tf","sha":"5225c1f98cfc9f91411d91eae7bd692168ea8f4c"},{"name":"variables.tf","path":"modules/asg-instance-refresh/variables.tf","sha":"0bfddab822b450846e5d413dd91aa3ee7b863b79"}]},{"name":"asg-rolling-deploy","children":[{"name":"README.md","path":"modules/asg-rolling-deploy/README.md","sha":"fbbc6657f0cef2493e9fdb7b42549d69e5ff4080"},{"name":"describe-autoscaling-group","children":[{"name":"README.md","path":"modules/asg-rolling-deploy/describe-autoscaling-group/README.md","sha":"30ba6d6cfb97a09deb821a9037108bbc6abcc276"},{"name":"boto3-1.20.24.zip","path":"modules/asg-rolling-deploy/describe-autoscaling-group/boto3-1.20.24.zip","sha":"b4b675780634cea8a0eb06a0b0458dbb0a39385d"},{"name":"get-desired-capacity.py","path":"modules/asg-rolling-deploy/describe-autoscaling-group/get-desired-capacity.py","sha":"a980df805a4d65e77ecd1dbba5892803415c9c5b"}]},{"name":"main.tf","path":"modules/asg-rolling-deploy/main.tf","sha":"72fd980910d7cf4846d1616be58151ce812637a4"},{"name":"outputs.tf","path":"modules/asg-rolling-deploy/outputs.tf","sha":"5225c1f98cfc9f91411d91eae7bd692168ea8f4c"},{"name":"variables.tf","path":"modules/asg-rolling-deploy/variables.tf","sha":"a599c1aa7504e2ec91932564c93d216b6fe63f62"}]},{"name":"server-group","children":[{"name":"README.md","path":"modules/server-group/README.md","sha":"10ff38cf380db99bf9e336081a59acb18c072198"},{"name":"main.tf","path":"modules/server-group/main.tf","sha":"2d882e86cfdc13b1f520df6932d03337168b7556"},{"name":"outputs.tf","path":"modules/server-group/outputs.tf","sha":"b5666cf3e0d9b85cbb9f13cb5d87f27b148c39f8"},{"name":"rolling-deploy","children":[{"name":"boto3-1.20.24.zip","path":"modules/server-group/rolling-deploy/boto3-1.20.24.zip","sha":"b4b675780634cea8a0eb06a0b0458dbb0a39385d"},{"name":"helpers.py","path":"modules/server-group/rolling-deploy/helpers.py","sha":"37ee35c8f200ceafdb9f7acf09d2ece1e6adddcb"},{"name":"rolling_deployment.py","path":"modules/server-group/rolling-deploy/rolling_deployment.py","sha":"e63f3e9a2072daf9d261b739ea9b6eddb2a95f0f"}]},{"name":"variables.tf","path":"modules/server-group/variables.tf","sha":"fdb00a4d0154c1930cbdd425c1ca06eed7898166"}]}]},{"name":"terraform-cloud-enterprise-private-module-registry-placeholder.tf","path":"terraform-cloud-enterprise-private-module-registry-placeholder.tf","sha":"ae586c0fe830819580e1009d41a9074f16e65bed"},{"name":"test","children":[{"name":"README.md","path":"test/README.md","sha":"cfa55a38cc6fbd09a311291216eb758159973629"},{"name":"asg_instance_refresh_test.go","path":"test/asg_instance_refresh_test.go","sha":"78157f674961278f1381fa9f688c87e7ffabaec4"},{"name":"asg_rolling_deploy_test.go","path":"test/asg_rolling_deploy_test.go","sha":"ca7bc5e7ac8b57f3eaee07f4f7417d1ab1e67cd3"},{"name":"go.mod","path":"test/go.mod","sha":"914dc7f51dccc6f9543903be303adef1c39239a1"},{"name":"go.sum","path":"test/go.sum","sha":"356aa577d3a974784d530acf5c50856bfe0eca4c"},{"name":"server_group_test.go","path":"test/server_group_test.go","sha":"226a95bf2bbddcddc3635db15003e9f39e1ab58d"},{"name":"test_helpers.go","path":"test/test_helpers.go","sha":"66805d579a7b57fe719de365473effd2cb34602f"},{"name":"upgrades","children":[{"name":"upgrade_test.go","path":"test/upgrades/upgrade_test.go","sha":"40101dddb57afddbca8c8fe5e329eecbfd28efb6"}]},{"name":"validation","children":[{"name":"validate_all_modules_and_examples_test.go","path":"test/validation/validate_all_modules_and_examples_test.go","sha":"74c928d0cbc2914e5cd708277bd857cb2375b660"}]}]}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"contribution-guidelines\">Contribution Guidelines</h1><div class=\"preview__body--border\"></div><p>Contributions to this Package are very welcome! We follow a fairly standard <a href=\"https://help.github.com/articles/about-pull-requests/\" class=\"preview__body--description--blue\" target=\"_blank\">pull request process</a> for contributions, subject to the following guidelines:</p>\n<ol>\n<li><a href=\"#file-a-github-issue\" class=\"preview__body--description--blue\">File a GitHub issue</a></li>\n<li><a href=\"#update-the-documentation\" class=\"preview__body--description--blue\">Update the documentation</a></li>\n<li><a href=\"#update-the-tests\" class=\"preview__body--description--blue\">Update the tests</a></li>\n<li><a href=\"#update-the-code\" class=\"preview__body--description--blue\">Update the code</a></li>\n<li><a href=\"#create-a-pull-request\" class=\"preview__body--description--blue\">Create a pull request</a></li>\n<li><a href=\"#merge-and-release\" class=\"preview__body--description--blue\">Merge and release</a></li>\n</ol>\n<h2 class=\"preview__body--subtitle\" id=\"file-a-git-hub-issue\">File a GitHub issue</h2>\n<p>Before starting any work, we recommend filing a GitHub issue in this repo. This is your chance to ask questions and\nget feedback from the maintainers and the community before you sink a lot of time into writing (possibly the wrong)\ncode. If there is anything you're unsure about, just ask!</p>\n<h2 class=\"preview__body--subtitle\" id=\"update-the-documentation\">Update the documentation</h2>\n<p>We recommend updating the documentation <em>before</em> updating any code (see <a href=\"http://tom.preston-werner.com/2010/08/23/readme-driven-development.html\" class=\"preview__body--description--blue\" target=\"_blank\">Readme Driven\nDevelopment</a>). This ensures the documentation\nstays up to date and allows you to think through the problem at a high level before you get lost in the weeds of\ncoding.</p>\n<h2 class=\"preview__body--subtitle\" id=\"update-the-tests\">Update the tests</h2>\n<p>We also recommend updating the automated tests <em>before</em> updating any code (see <a href=\"https://en.wikipedia.org/wiki/Test-driven_development\" class=\"preview__body--description--blue\" target=\"_blank\">Test Driven\nDevelopment</a>). That means you add or update a test case,\nverify that it's failing with a clear error message, and <em>then</em> make the code changes to get that test to pass. This\nensures the tests stay up to date and verify all the functionality in this Module, including whatever new\nfunctionality you're adding in your contribution. Check out the <a href=\"/repos/terraform-aws-asg/test\" class=\"preview__body--description--blue\">tests</a> folder for instructions on running the\nautomated tests.</p>\n<h2 class=\"preview__body--subtitle\" id=\"update-the-code\">Update the code</h2>\n<p>At this point, make your code changes and use your new test case to verify that everything is working. As you work,\nkeep in mind two things:</p>\n<ol>\n<li>Backwards compatibility</li>\n<li>Downtime</li>\n</ol>\n<h3 class=\"preview__body--subtitle\" id=\"backwards-compatibility\">Backwards compatibility</h3>\n<p>Please make every effort to avoid unnecessary backwards incompatible changes. With Terraform code, this means:</p>\n<ol>\n<li>Do not delete, rename, or change the type of input variables.</li>\n<li>If you add an input variable, it should have a <code>default</code>.</li>\n<li>Do not delete, rename, or change the type of output variables.</li>\n<li>Do not delete or rename a module in the <code>modules</code> folder.</li>\n</ol>\n<p>If a backwards incompatible change cannot be avoided, please make sure to call that out when you submit a pull request,\nexplaining why the change is absolutely necessary.</p>\n<h3 class=\"preview__body--subtitle\" id=\"downtime\">Downtime</h3>\n<p>Bear in mind that the Terraform code in this Module is used by real companies to run real infrastructure in\nproduction, and certain types of changes could cause downtime. For example, consider the following:</p>\n<ol>\n<li>If you rename a resource (e.g. <code>aws_instance "foo"</code> -> <code>aws_instance "bar"</code>), Terraform will see that as deleting\nthe old resource and creating a new one.</li>\n<li>If you change certain attributes of a resource (e.g. the <code>name</code> of an <code>aws_elb</code>), the cloud provider (e.g. AWS) may\ntreat that as an instruction to delete the old resource and a create a new one.</li>\n</ol>\n<p>Deleting certain types of resources (e.g. virtual servers, load balancers) can cause downtime, so when making code\nchanges, think carefully about how to avoid that. For example, can you avoid downtime by using\n<a href=\"https://www.terraform.io/docs/configuration/resources.html#create_before_destroy\" class=\"preview__body--description--blue\" target=\"_blank\">create_before_destroy</a>? Or via\nthe <code>terraform state</code> command? If so, make sure to note this in our pull request. If downtime cannot be avoided,\nplease make sure to call that out when you submit a pull request.</p>\n<h3 class=\"preview__body--subtitle\" id=\"formatting-and-pre-commit-hooks\">Formatting and pre-commit hooks</h3>\n<p>You must run <code>terraform fmt</code> on the code before committing. You can configure your computer to do this automatically\nusing pre-commit hooks managed using <a href=\"http://pre-commit.com/\" class=\"preview__body--description--blue\" target=\"_blank\">pre-commit</a>:</p>\n<ol>\n<li><a href=\"http://pre-commit.com/#install\" class=\"preview__body--description--blue\" target=\"_blank\">Install pre-commit</a>. E.g.: <code>brew install pre-commit</code>.</li>\n<li>Install the hooks: <code>pre-commit install</code>.</li>\n</ol>\n<p>That's it! Now just write your code, and every time you commit, <code>terraform fmt</code> will be run on the files you're\ncommitting.</p>\n<h2 class=\"preview__body--subtitle\" id=\"create-a-pull-request\">Create a pull request</h2>\n<p><a href=\"https://help.github.com/articles/creating-a-pull-request/\" class=\"preview__body--description--blue\" target=\"_blank\">Create a pull request</a> with your changes. Please make sure\nto include the following:</p>\n<ol>\n<li>A description of the change, including a link to your GitHub issue.</li>\n<li>The output of your automated test run, preferably in a <a href=\"https://gist.github.com/\" class=\"preview__body--description--blue\" target=\"_blank\">GitHub Gist</a>. We cannot run\nautomated tests for pull requests automatically due to <a href=\"https://circleci.com/docs/fork-pr-builds/#security-implications\" class=\"preview__body--description--blue\" target=\"_blank\">security\nconcerns</a>, so we need you to manually provide this\ntest output so we can verify that everything is working.</li>\n<li>Any notes on backwards incompatibility or downtime.</li>\n</ol>\n<h2 class=\"preview__body--subtitle\" id=\"merge-and-release\">Merge and release</h2>\n<p>The maintainers for this repo will review your code and provide feedback. If everything looks good, they will merge the\ncode and release a new version, which you'll be able to find in the <a href=\"/repos/releases\" class=\"preview__body--description--blue\">releases page</a>.</p>\n","repoName":"module-asg","repoRef":"v0.19.4","serviceDescriptor":{"serviceName":"Auto Scaling Group (stateless)","serviceRepoName":"module-asg","serviceRepoOrg":"gruntwork-io","serviceMainReadmePath":"/modules/asg-rolling-deploy","cloudProviders":["aws"],"description":"Run an Auto Scaling Group for stateless apps. Supports zero-downtime, rolling deployment, auto healing, auto scaling, and IAM Roles.","imageUrl":"auto-scaling2.png","licenseType":"subscriber","technologies":["Terraform","Python","Bash"],"compliance":[],"tags":[""]},"serviceCategoryName":"Server orchestration","fileName":"CONTRIBUTING.md","filePath":"/CONTRIBUTING.md","title":"Repo Browser: Auto Scaling Group (stateless)","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}
.circleci
.gitignore
