Skip to content

Commit 6fd2144

Browse files
eak12913eak12913
authored
🔄 [CORE-569] Add "Sample Usage" section to modules (#662)
* [CORE-569] Add "Sample Usage" section to modules This PR adds a new section into the README of the reference documentation for Gruntwork's modules. The new section displays sample terraform source code with the module's source, require and optional variables. This example can be quickly copied to get started with using the module. Each variable lists the description as a comment on top of it.
1 parent e42f236 commit 6fd2144

File tree

219 files changed

+18988
-2193
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

219 files changed

+18988
-2193
lines changed

‎docs/reference/modules/terraform-aws-asg/asg-instance-refresh/asg-instance-refresh.md

Lines changed: 141 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,16 @@ import Tabs from '@theme/Tabs';
77
import TabItem from '@theme/TabItem';
88
import VersionBadge from '../../../../../src/components/VersionBadge.tsx';
99
import { HclListItem, HclListItemDescription, HclListItemTypeDetails, HclListItemDefaultValue, HclGeneralListItem } from '../../../../../src/components/HclListItem.tsx';
10+
import { ModuleUsage } from "../../../../../src/components/ModuleUsage";
11+
12+
<VersionBadge repoTitle="Auto Scaling Group Modules" version="0.21.1" />
13+
14+
# Auto Scaling Group Module with Instance Refresh
1015

1116
<a href="https://github.com/gruntwork-io/terraform-aws-asg/tree/main/modules/asg-instance-refresh" className="link-button" title="View the source code for this module in GitHub.">View Source</a>
1217

1318
<a href="https://github.com/gruntwork-io/terraform-aws-asg/releases?q=" className="link-button" title="Release notes for only the service catalog versions which impacted this service.">Release Notes</a>
1419

15-
# Auto Scaling Group Module with Instance Refresh
16-
1720
This Terraform Module creates an Auto Scaling Group (ASG) that can do a zero-downtime rolling deployment. That means every time you update your app (e.g. publish a new AMI), all you have to do is run `terraform apply` and the new version of your app will automatically roll out across your Auto Scaling Group. Note that this module *only* creates the ASG and it's up to you to create all the other related resources, such as the launch configuration, ELB, and security groups.
1821

1922
**WARNING: Launch Configurations:** [Launch configurations](https://docs.aws.amazon.com/autoscaling/ec2/userguide/launch-configurations.html) are being phased out in favor of [Launch Templates](https://docs.aws.amazon.com/autoscaling/ec2/userguide/launch-templates.html). Before upgrading to the latest release please be sure to test and plan any changes to infrastructure that may be impacted. Please also keep in mind that AWS will remove support for Launch Configurations on Dec 31st 2023.
@@ -73,6 +76,138 @@ The Terraform [instance_refresh](https://registry.terraform.io/providers/hashico
7376
* Auto Scaling Groups support up to one active instance refresh at a time. When this resource is updated, any existing refresh is cancelled.
7477
* Depending on health check settings and group size, an instance refresh may take a long time or fail. The Terraform `instance_refresh` resource does not wait for the instance refresh to complete.
7578

79+
## Sample Usage
80+
81+
<ModuleUsage>
82+
83+
```hcl title="main.tf"
84+
85+
# ------------------------------------------------------------------------------------------------------
86+
# DEPLOY GRUNTWORK'S ASG-INSTANCE-REFRESH MODULE
87+
# ------------------------------------------------------------------------------------------------------
88+
89+
module "asg_instance_refresh" {
90+
91+
source = "git::[email protected]:gruntwork-io/terraform-aws-asg.git//modules/asg-instance-refresh?ref=v0.21.1"
92+
93+
# ----------------------------------------------------------------------------------------------------
94+
# REQUIRED VARIABLES
95+
# ----------------------------------------------------------------------------------------------------
96+
97+
# The name of the ASG.
98+
asg_name = <INPUT REQUIRED>
99+
100+
# The desired number of EC2 Instances to run in the ASG initially. Note that auto
101+
# scaling policies may change this value. If you're using auto scaling policies to
102+
# dynamically resize the cluster, you should actually leave this value as null.
103+
desired_capacity = <INPUT REQUIRED>
104+
105+
# The maximum number of EC2 Instances to run in the ASG
106+
max_size = <INPUT REQUIRED>
107+
108+
# The minimum number of EC2 Instances to run in the ASG
109+
min_size = <INPUT REQUIRED>
110+
111+
# A list of subnet ids in the VPC were the EC2 Instances should be deployed
112+
vpc_subnet_ids = <INPUT REQUIRED>
113+
114+
# ----------------------------------------------------------------------------------------------------
115+
# OPTIONAL VARIABLES
116+
# ----------------------------------------------------------------------------------------------------
117+
118+
# The number of seconds to wait after a checkpoint.
119+
checkpoint_delay = null
120+
121+
# List of percentages for each checkpoint. Values must be unique and in ascending
122+
# order. To replace all instances, the final number must be 100.
123+
checkpoint_percentages = null
124+
125+
# A list of custom tags to apply to the EC2 Instances in this ASG. Each item in
126+
# this list should be a map with the parameters key, value, and
127+
# propagate_at_launch.
128+
custom_tags = []
129+
130+
# Timeout value for deletion operations on autoscale groups.
131+
deletion_timeout = "10m"
132+
133+
# A list of metrics the ASG should enable for monitoring all instances in a group.
134+
# The allowed values are GroupMinSize, GroupMaxSize, GroupDesiredCapacity,
135+
# GroupInServiceInstances, GroupPendingInstances, GroupStandbyInstances,
136+
# GroupTerminatingInstances, GroupTotalInstances.
137+
enabled_metrics = []
138+
139+
# Time, in seconds, after an EC2 Instance comes into service before checking
140+
# health.
141+
health_check_grace_period = 300
142+
143+
# The number of seconds until a newly launched instance is configured and ready to
144+
# use.
145+
instance_warmup = null
146+
147+
# This is DEPRECATED and will be removed on Dec 31st 2023. Please switch to using
148+
# Launch Template below. The name of the Launch Configuration to use for each EC2
149+
# Instance in this ASG. This value MUST be an output of the Launch Configuration
150+
# resource itself. This ensures a new ASG is created every time the Launch
151+
# Configuration changes, rolling out your changes automatically. One of
152+
# var.launch_configuration_name or var.launch_template must be set.
153+
launch_configuration_name = null
154+
155+
# The ID and version of the Launch Template to use for each EC2 instance in this
156+
# ASG. The version value MUST be an output of the Launch Template resource itself.
157+
# This ensures that a new ASG is created every time a new Launch Template version
158+
# is created. One of var.launch_configuration_name or var.launch_template must be
159+
# set.
160+
launch_template = null
161+
162+
# A list of Elastic Load Balancer (ELB) names to associate with this ASG. If
163+
# you're using the Application Load Balancer (ALB), see var.target_group_arns.
164+
load_balancers = []
165+
166+
# Wait for this number of EC2 Instances to show up healthy in the load balancer on
167+
# creation.
168+
min_elb_capacity = 0
169+
170+
# The amount of capacity in the Auto Scaling group that must remain healthy during
171+
# an instance refresh to allow the operation to continue, as a percentage of the
172+
# desired capacity
173+
min_healthy_percentage = null
174+
175+
# The key for the tag that will be used to associate a unique identifier with this
176+
# ASG. This identifier will persist between redeploys of the ASG, even though the
177+
# underlying ASG is being deleted and replaced with a different one.
178+
tag_asg_id_key = "AsgId"
179+
180+
# A list of Application Load Balancer (ALB) target group ARNs to associate with
181+
# this ASG. If you're using the Elastic Load Balancer (ELB), see
182+
# var.load_balancers.
183+
target_group_arns = []
184+
185+
# A list of policies to decide how the instances in the auto scale group should be
186+
# terminated. The allowed values are OldestInstance, NewestInstance,
187+
# OldestLaunchConfiguration, ClosestToNextInstanceHour, Default.
188+
termination_policies = []
189+
190+
# Set of additional property names that will trigger an Instance Refresh. A
191+
# refresh will always be triggered by a change in any of launch_configuration,
192+
# launch_template, or mixed_instances_policy.
193+
triggers = null
194+
195+
# Whether or not ELB or ALB health checks should be enabled. If set to true, the
196+
# load_balancers or target_groups_arns variable should be set depending on the
197+
# load balancer type you are using. Useful for testing connectivity before health
198+
# check endpoints are available.
199+
use_elb_health_checks = true
200+
201+
# A maximum duration that Terraform should wait for the EC2 Instances to be
202+
# healthy before timing out.
203+
wait_for_capacity_timeout = "10m"
204+
205+
}
206+
207+
```
208+
209+
</ModuleUsage>
210+
76211

77212

78213

@@ -378,11 +513,11 @@ A maximum duration that Terraform should wait for the EC2 Instances to be health
378513
<!-- ##DOCS-SOURCER-START
379514
{
380515
"originalSources": [
381-
"https://github.com/gruntwork-io/terraform-aws-asg/tree/modules/asg-instance-refresh/readme.md",
382-
"https://github.com/gruntwork-io/terraform-aws-asg/tree/modules/asg-instance-refresh/variables.tf",
383-
"https://github.com/gruntwork-io/terraform-aws-asg/tree/modules/asg-instance-refresh/outputs.tf"
516+
"https://github.com/gruntwork-io/terraform-aws-asg/tree/main/modules/asg-instance-refresh/readme.md",
517+
"https://github.com/gruntwork-io/terraform-aws-asg/tree/main/modules/asg-instance-refresh/variables.tf",
518+
"https://github.com/gruntwork-io/terraform-aws-asg/tree/main/modules/asg-instance-refresh/outputs.tf"
384519
],
385520
"sourcePlugin": "module-catalog-api",
386-
"hash": "f7d92540b64ab62d025a6cd854654704"
521+
"hash": "4c0a0786d52bcbf6d8b38fab2ed1e7ed"
387522
}
388523
##DOCS-SOURCER-END -->

‎docs/reference/modules/terraform-aws-asg/asg-rolling-deploy/asg-rolling-deploy.md

Lines changed: 113 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,16 @@ import Tabs from '@theme/Tabs';
77
import TabItem from '@theme/TabItem';
88
import VersionBadge from '../../../../../src/components/VersionBadge.tsx';
99
import { HclListItem, HclListItemDescription, HclListItemTypeDetails, HclListItemDefaultValue, HclGeneralListItem } from '../../../../../src/components/HclListItem.tsx';
10+
import { ModuleUsage } from "../../../../../src/components/ModuleUsage";
11+
12+
<VersionBadge repoTitle="Auto Scaling Group Modules" version="0.21.1" />
13+
14+
# Auto Scaling Group with Rolling Deployment Module
1015

1116
<a href="https://github.com/gruntwork-io/terraform-aws-asg/tree/main/modules/asg-rolling-deploy" className="link-button" title="View the source code for this module in GitHub.">View Source</a>
1217

1318
<a href="https://github.com/gruntwork-io/terraform-aws-asg/releases?q=" className="link-button" title="Release notes for only the service catalog versions which impacted this service.">Release Notes</a>
1419

15-
# Auto Scaling Group with Rolling Deployment Module
16-
1720
This Terraform Module creates an Auto Scaling Group (ASG) that can do a zero-downtime rolling deployment. That means
1821
every time you update your app (e.g. publish a new AMI), all you have to do is run `terraform apply` and the new
1922
version of your app will automatically roll out across your Auto Scaling Group. Note that this module *only*
@@ -59,6 +62,110 @@ Note that if all we did was use `create_before_destroy`, on each redeploy, our A
5962
* If the script doesn't find an already-existing ASG, that means this is the first deploy, and we fall back to the
6063
hard-coded `desired_capacity` value.
6164

65+
## Sample Usage
66+
67+
<ModuleUsage>
68+
69+
```hcl title="main.tf"
70+
71+
# ------------------------------------------------------------------------------------------------------
72+
# DEPLOY GRUNTWORK'S ASG-ROLLING-DEPLOY MODULE
73+
# ------------------------------------------------------------------------------------------------------
74+
75+
module "asg_rolling_deploy" {
76+
77+
source = "git::[email protected]:gruntwork-io/terraform-aws-asg.git//modules/asg-rolling-deploy?ref=v0.21.1"
78+
79+
# ----------------------------------------------------------------------------------------------------
80+
# REQUIRED VARIABLES
81+
# ----------------------------------------------------------------------------------------------------
82+
83+
# The desired number of EC2 Instances to run in the ASG initially. Note that auto
84+
# scaling policies may change this value. If you're using auto scaling policies to
85+
# dynamically resize the cluster, you should actually leave this value as null.
86+
desired_capacity = <INPUT REQUIRED>
87+
88+
# The ID and version of the Launch Template to use for each EC2 instance in this
89+
# ASG. The version value MUST be an output of the Launch Template resource itself.
90+
# This ensures that a new ASG is created every time a new Launch Template version
91+
# is created.
92+
launch_template = <INPUT REQUIRED>
93+
94+
# The maximum number of EC2 Instances to run in the ASG
95+
max_size = <INPUT REQUIRED>
96+
97+
# The minimum number of EC2 Instances to run in the ASG
98+
min_size = <INPUT REQUIRED>
99+
100+
# A list of subnet ids in the VPC were the EC2 Instances should be deployed
101+
vpc_subnet_ids = <INPUT REQUIRED>
102+
103+
# ----------------------------------------------------------------------------------------------------
104+
# OPTIONAL VARIABLES
105+
# ----------------------------------------------------------------------------------------------------
106+
107+
# A list of custom tags to apply to the EC2 Instances in this ASG. Each item in
108+
# this list should be a map with the parameters key, value, and
109+
# propagate_at_launch.
110+
custom_tags = []
111+
112+
# Timeout value for deletion operations on autoscale groups.
113+
deletion_timeout = "10m"
114+
115+
# A list of metrics the ASG should enable for monitoring all instances in a group.
116+
# The allowed values are GroupMinSize, GroupMaxSize, GroupDesiredCapacity,
117+
# GroupInServiceInstances, GroupPendingInstances, GroupStandbyInstances,
118+
# GroupTerminatingInstances, GroupTotalInstances.
119+
enabled_metrics = []
120+
121+
# Time, in seconds, after an EC2 Instance comes into service before checking
122+
# health.
123+
health_check_grace_period = 300
124+
125+
# A list of Elastic Load Balancer (ELB) names to associate with this ASG. If
126+
# you're using the Application Load Balancer (ALB), see var.target_group_arns.
127+
load_balancers = []
128+
129+
# The maximum amount of time, in seconds, that an instance inside an ASG can be in
130+
# service, values must be either equal to 0 or between 604800 and 31536000
131+
# seconds.
132+
max_instance_lifetime = null
133+
134+
# Wait for this number of EC2 Instances to show up healthy in the load balancer on
135+
# creation.
136+
min_elb_capacity = 0
137+
138+
# The key for the tag that will be used to associate a unique identifier with this
139+
# ASG. This identifier will persist between redeploys of the ASG, even though the
140+
# underlying ASG is being deleted and replaced with a different one.
141+
tag_asg_id_key = "AsgId"
142+
143+
# A list of Application Load Balancer (ALB) target group ARNs to associate with
144+
# this ASG. If you're using the Elastic Load Balancer (ELB), see
145+
# var.load_balancers.
146+
target_group_arns = []
147+
148+
# A list of policies to decide how the instances in the auto scale group should be
149+
# terminated. The allowed values are OldestInstance, NewestInstance,
150+
# OldestLaunchTemplate, AllocationStrategy, ClosestToNextInstanceHour, Default.
151+
termination_policies = []
152+
153+
# Whether or not ELB or ALB health checks should be enabled. If set to true, the
154+
# load_balancers or target_groups_arns variable should be set depending on the
155+
# load balancer type you are using. Useful for testing connectivity before health
156+
# check endpoints are available.
157+
use_elb_health_checks = true
158+
159+
# A maximum duration that Terraform should wait for the EC2 Instances to be
160+
# healthy before timing out.
161+
wait_for_capacity_timeout = "10m"
162+
163+
}
164+
165+
```
166+
167+
</ModuleUsage>
168+
62169

63170

64171

@@ -304,11 +411,11 @@ A maximum duration that Terraform should wait for the EC2 Instances to be health
304411
<!-- ##DOCS-SOURCER-START
305412
{
306413
"originalSources": [
307-
"https://github.com/gruntwork-io/terraform-aws-asg/tree/modules/asg-rolling-deploy/readme.md",
308-
"https://github.com/gruntwork-io/terraform-aws-asg/tree/modules/asg-rolling-deploy/variables.tf",
309-
"https://github.com/gruntwork-io/terraform-aws-asg/tree/modules/asg-rolling-deploy/outputs.tf"
414+
"https://github.com/gruntwork-io/terraform-aws-asg/tree/main/modules/asg-rolling-deploy/readme.md",
415+
"https://github.com/gruntwork-io/terraform-aws-asg/tree/main/modules/asg-rolling-deploy/variables.tf",
416+
"https://github.com/gruntwork-io/terraform-aws-asg/tree/main/modules/asg-rolling-deploy/outputs.tf"
310417
],
311418
"sourcePlugin": "module-catalog-api",
312-
"hash": "96fac5773d033431cdef1d30813230d2"
419+
"hash": "a82e2194ca664d83b7adaeecc69c9e9c"
313420
}
314421
##DOCS-SOURCER-END -->

0 commit comments

Comments
 (0)