README.md in capistrano-asg-rolling-0.4.1 vs README.md in capistrano-asg-rolling-0.5.0

@@ -14,30 +14,27 @@
 - Create new Launch Template versions for the new AMIs.
 - Trigger Instance Refresh on the Auto Scaling Group(s) to perform a rolling update.
 - Delete any outdated Launch Template versions, AMIs and snapshots created by previous deployments.
 - Terminate the no longer needed instances.
 
-## Caveats
+## Important
 
-#### Instance refresh limitations
+### Instance refresh
 
-Please be aware of the limitations of using instance refresh, in particular "Instances terminated before launch": https://docs.aws.amazon.com/autoscaling/ec2/userguide/asg-instance-refresh.html#instance-refresh-limitations
+To better understand how Instance Refresh replaces instances, make sure to read the documentation:
+https://docs.aws.amazon.com/autoscaling/ec2/userguide/instance-refresh-overview.html
 
-#### Launch Templates
+### Launch Templates
 
 This gem depends on Auto Scaling Groups with Launch Templates. Using an Auto Scaling Group with a Launch Configuration is not supported, and will raise an `Capistrano::ASG::Rolling::NoLaunchTemplate`.
 
 Instance refresh uses the desired configuration to update the Launch Template version of the Auto Scaling Group after a succesful deployment. Setting the Launch Template version to `Latest` on the Auto Scaling Group is not needed.
 
-#### Experimental
+### Experimental
 
-This gem is experimental, it works for our configuration / use case, but might not for yours.
+Please note that this gem works well for our configuration / use case, but it might not fit yours. Any feedback using GitHub issues / pull requests, is much appreciated.
 
-The configuration options are not considered stable and might be changed or removed in future releases.
-
-The gem could have a better / fancier name.
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -131,20 +128,25 @@
 # config/deploy/<stage>.rb
 autoscale 'app-autoscale-group', rolling: true    # default: use rolling deployment
 autoscale 'web-autoscale-group', rolling: false   # override: use normal deployment
 ```
 
-### Deploy with a custom percentage of minimum healthy instances during the instance refresh
+### Deploy with custom percentage of minimum/maximum healthy instances during the instance refresh
 
-The instance refresh is triggered by default with a requirement of 100% minimum healthy instances. ie. One instance is replaced at a time, and must be healthy and in-service before the next is replaced. This can mean that instance refreshes take a long time to complete, especially with larger numbers of instances with large warmup values. Reducing this value allows more instances to be terminated and new instances to be brought up at once during the instance refresh. eg. a value of 0 would terminate all instances in the autoscaling group and replace them at once.
+The instance refresh is triggered without specifying a value for the minimum / maximum healthy percentages. This means that either the default
+values will be used (minimum: 90%, maximum: 100%) or the percentages set in the instance maintenance policy for the Auto Scaling Group.
+You can tune both the minimum and maximum values to have more control about the desired capacity that must be healthy to proceed with replacing instances.
 
-You can configure the minimum healthy percentage per autoscaling group using the `healthy_percentage` option:
+For example: reducing the minimum healthy percentage allows more instances to be terminated and new instances to be brought up at once during the instance refresh. eg. a value of 0 would terminate all instances in the autoscaling group and replace them at once.
 
+You can configure the minimum healthy percentage per autoscaling group using the `min_healthy_percentage` option, and the maximum healthy percentage using the `max_healthy_percentage` option. Please note that if you specify `max_healthy_percentage`, you must also specify `min_healthy_percentage`.
+
 ```ruby
 # config/deploy/<stage>.rb
-autoscale 'app-autoscale-group', user: 'deployer'                           # default: use standard deployment with 100% minimum healthy instances
-autoscale 'web-autoscale-group', user: 'deployer', healthy_percentage: 75   # override: allow 25% of instances to be terminated and replaced at once
+autoscale 'app-autoscale-group',                                                           # use default percentages or percentages set in the instance maintenance policy
+autoscale 'web-autoscale-group', min_healthy_percentage: 75                                # allow 25% of instances to be terminated and replaced at once
+autoscale 'web-autoscale-group', min_healthy_percentage: 100, max_healthy_percentage: 110  # allow for 10% above desired capacity during instance refresh
 ```
 
 ### Custom stage
 
 The rolling configuration of the stage has a side-effect: any Capistrano tasks you run, will also launch instances per Auto Scaling Group.
@@ -170,10 +172,50 @@
 autoscale 'web-autoscale-group', rolling: true, user: 'deployer'
 ```
 
 With these two stages, you can run any tasks with `cap production <task name>` and rolling deployments with `cap production_rolling deploy`.
 
+## Useful commands
+
+### Test deployment
+
+Do a test deployment: run the deploy task, but do not trigger the update ASG task and do not automatically terminate instances.
+
+```bash
+cap <stage> rolling:deploy_test
+```
+
+### Launch instances
+
+Just launch instance(s) defined in the Auto Scale Group(s) launch template.
+This instance is not attached to the Auto Scale Group and needs to be terminated manually.
+
+```bash
+cap <stage> rolling:launch_instances
+```
+
+### Create AMI of instance in ASG
+
+Pick an instance in the Auto Scale Group(s), put it into standby and stop it.
+Then create an AMI and a new launch template. Then start the instance and put it into service again.
+
+```bash
+cap <stage> rolling:create_ami
+```
+
+## Filtering
+
+You can filter any command to run on a specific Auto Scale Group by using the parameter `asg_name`.
+
+For example, the command:
+
+```bash
+cap <stage> deploy asg_name=app-autoscale-group
+```
+
+Will do a deployment only on the Auto Scale Group with the name `app-autoscale-group`.
+
 ## IAM policy
 
 The following IAM permissions are required:
 
 ```json
@@ -183,10 +225,11 @@
         {
             "Effect": "Allow",
             "Action": [
                 "autoscaling:DescribeAutoScalingGroups",
                 "autoscaling:DescribeAutoScalingInstances",
+                "autoscaling:DescribeInstanceRefreshes",
                 "autoscaling:EnterStandby",
                 "autoscaling:ExitStandby",
                 "autoscaling:StartInstanceRefresh",
                 "ec2:CreateImage",
                 "ec2:CreateLaunchTemplateVersion",
@@ -196,9 +239,10 @@
                 "ec2:DeregisterImage",
                 "ec2:DescribeImages",
                 "ec2:DescribeInstances",
                 "ec2:DescribeLaunchTemplateVersions",
                 "ec2:RunInstances",
+                "ec2:StartInstances",
                 "ec2:StopInstances",
                 "ec2:TerminateInstances"
             ],
             "Resource": "*"
         }