Skip to main content

AWS ASG

This topic explains how to deploy new AWS Auto Scale Groups (ASGs) and instances to Amazon Elastic Compute Cloud (EC2) using Harness.

Deployment summary​

Here's a high-level summary of the setup steps and how Harness deploys ASGs.

Harness setup summary

Here's a summary of how you set up ASG deployments in Harness:

  1. Create the Harness ASG service.
    1. Add the launch template manifest file.
    2. Add the ASG configuration manifest file.
    3. Add scaling policies (optional).
    4. Add scheduled update group actions (optional).
    5. Add the user data script file (optional).
    6. Add the AMI image to use for the ASG as an artifact.
  2. Create the Harness ASG environment.
    1. Connect Harness to the AWS region where you want to deploy.
  3. Define the Harness ASG pipeline execution.
    1. Select a deployment strategy (rolling, canary, blue-green) and Harness automatically creates the steps to deploy the new ASG.
  4. Deploy the Harness pipeline.
Deployment summary

Here's a summary of how Harness deploys new ASG versions:

  1. First deployment:
    1. Harness takes the launch template and ASG configuration files you provide and creates a new ASG and its instances in your AWS account and region. Harness creates a new launch template with name same as the ASG name and that launch template is applied to the new ASG.
  2. Subsequent deployments:
    1. Harness creates a new version of the launch template.
    2. Harness uses the new version of the launch template and other configurations to update the ASG. For example, if you also increased the desired capacity (desiredCapacity) for the ASG in your ASG configuration file, Harness will create a new version of the ASG with the new desired capacity and new launch template version.
    3. Instance refresh is triggered (a rolling replacement of all or some instances in the ASG).

Notes:

  • ASG creation differs for rolling and blue green deployments:
    • For rolling, Harness updates the existing ASG with the new configuration.
    • For blue green, Harness creates a new ASG with a new revision suffix, like asg-demo__2. Once there are two ASGs (asg-demo__1 and asg-demo__2) Harness alternately updates these existing ASGs with the new configuration on each successive deployment.

AWS policy requirements​

Your AWS IAM role associated with your Harness AWS connector must have the following required policies:

Required Policies

Policy JSON:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "autoscaling:AttachLoadBalancers",
                "autoscaling:AttachLoadBalancerTargetGroups",
                "autoscaling:CreateAutoScalingGroup",
                "autoscaling:CreateOrUpdateTags",
                "autoscaling:DeleteAutoScalingGroup",
                "autoscaling:DeleteLifecycleHook",
                "autoscaling:DeletePolicy",
                "autoscaling:DeleteScheduledAction",
                "autoscaling:DeleteTags",
                "autoscaling:DescribeAutoScalingGroups",
                "autoscaling:DescribeInstanceRefreshes",
                "autoscaling:DescribeInstanceRefreshes",
                "autoscaling:DescribeLifecycleHooks",
                "autoscaling:DescribeLoadBalancers",
                "autoscaling:DescribeLoadBalancerTargetGroups",
                "autoscaling:DescribePolicies",
                "autoscaling:DescribeScheduledActions",
                "autoscaling:DescribeTags",
                "autoscaling:DetachLoadBalancers",
                "autoscaling:DetachLoadBalancerTargetGroups",
                "autoscaling:PutLifecycleHook",
                "autoscaling:PutScalingPolicy",
                "autoscaling:PutScheduledUpdateGroupAction",
                "autoscaling:SetDesiredCapacity",
                "autoscaling:StartInstanceRefresh",
                "autoscaling:UpdateAutoScalingGroup",
                "ec2:CreateLaunchTemplate",
                "ec2:CreateLaunchTemplateVersion",
                "ec2:DescribeLaunchTemplates",
                "ec2:DescribeLaunchTemplateVersions",
                "ec2:DescribeRegions",
                "ec2:DescribeImages",
                "ec2:RunInstances",
                "elasticloadbalancing:DescribeListeners",
                "elasticloadbalancing:DescribeLoadBalancers",
                "elasticloadbalancing:DescribeRules",
                "elasticloadbalancing:DescribeTargetHealth",
                "elasticloadbalancing:DescribeTargetHealth",
                "elasticloadbalancing:ModifyListener",
                "elasticloadbalancing:ModifyRule"
            ],
            "Resource": "*"
        }
    ]
}

Optionally, you can also give full access with just two policies:

AmazonEC2FullAccess and DescribeRegions
  • Policy Name: AmazonEC2FullAccess.
  • Policy ARN: arn:aws:iam::aws:policy/AmazonEC2FullAccess.
  • Description: Provides full access to Amazon EC2 via the AWS Management Console.

Policy JSON:

{  
  "Version": "2012-10-17",  
  "Statement": [  
    {  
      "Action": "ec2:*",  
      "Effect": "Allow",  
      "Resource": "*"  
    },  
    {  
      "Effect": "Allow",  
      "Action": "elasticloadbalancing:*",  
      "Resource": "*"  
    },  
    {  
      "Effect": "Allow",  
      "Action": "cloudwatch:*",  
      "Resource": "*"  
    },  
    {  
      "Effect": "Allow",  
      "Action": "autoscaling:*",  
      "Resource": "*"  
    }  
  ]  
}

Harness needs a policy with the DescribeRegions action so that it can list the available regions for you when you define your target architecture.

note

The DescribeRegions action is required for all AWS IAM roles used in Harness AWS connectors regardless of what AWS service you are using.

Create a Customer Managed Policy, add the DescribeRegions action to list those regions, and add that to any role used by the Cloud Provider.

{  
    "Version": "2012-10-17",  
    "Statement": [  
        {  
            "Sid": "VisualEditor0",  
            "Effect": "Allow",  
            "Action": "ec2:DescribeRegions",  
            "Resource": "*"  
        }  
    ]  
}
note

Currently, Harness does not support ASG deployments with an OIDC-enabled AWS connector.

Harness ASG services​

The Harness ASG service contains the following:

  • Launch template.
  • ASG configuration file.
  • ASG Additional Configuration
  • Scaling policies (optional).
  • Scheduled update group action (optional).
  • User Data script file.
  • The AMI image to use for the ASG.

Harness supports standard ASG JSON formatted files. For more information, go to Get started with Amazon EC2 Auto Scaling from AWS.

You can use remote files stored in a Git repo or the Harness File Store.

note

You can create a service when you are building the pipeline or separately in Services. In this topic, we walk through building the service separately. For more information, go to CD pipeline modeling overview.

Here's an example where the configuration files are stored in the Harness File Store.

service:
  name: svc-asg
  identifier: svcasg
  serviceDefinition:
    type: Asg
    spec:
      manifests:
        - manifest:
            identifier: launchTemplate
            type: AsgLaunchTemplate
            spec:
              store:
                type: Harness
                spec:
                  files:
                    - /asg/launchtemplate
        - manifest:
            identifier: launchConfig
            type: AsgConfiguration
            spec:
              store:
                type: Harness
                spec:
                  files:
                    - /asg/launchconfig
        - manifest:
            identifier: scalePolicy
            type: AsgScalingPolicy
            spec:
              store:
                type: Harness
                spec:
                  files:
                    - /asg/scalingPolicy.json
        - manifest:
            identifier: scheduledUpdateGroupAction
            type: AsgScheduledUpdateGroupAction
            spec:
              store:
                type: Harness
                spec:
                  files:
                    - /asg/scheduledUpdateGroupAction.json
      artifacts:
        primary:
          primaryArtifactRef: <+input>
          sources:
            - identifier: AMI-ARTIFACT
              spec:
                connectorRef: AWS_ASG_CONNECTOR
                region: us-east-1
                filters:
                  - name: ami-name
                    value: Returns local IP address at port 80
                version: Returns local IP address at port 80
              type: AmazonMachineImage
  gitOpsEnabled: false

ASG Launch Template files​

AWS does not have a dedicated public resource for Launch Template file formatting because Launch template creation is typically done using the AWS CLI, SDKs, or Management Console, which have their own syntax and methods for specifying the parameters. However, the AWS CLI create-launch-template command reference documentation provides a detailed description of the parameters that can be used when creating a launch template.

ASG Launch Template file example
{
  "LaunchTemplateData": {
    "InstanceType": "t2.micro",
    "KeyName": "vit-cd-play"
  }
}

ASG configuration files​

AWS does not have a dedicated public resource for ASG configuration file formatting because ASG creation is typically done using the AWS CLI, SDKs, or Management Console, which have their own syntax and methods for specifying the parameters.

However, the AWS CLI create-auto-scaling-group command reference documentation provides a detailed description of the parameters that can be used when creating an ASG.

ASG configuration file example
{
  "AutoScalingGroupName": "my-asg",
  "MinSize": 1,
  "MaxSize": 3,
  "DesiredCapacity": 2,
  "AvailabilityZones": ["us-west-2a", "us-west-2b"],
  "LaunchTemplate": {
    "LaunchTemplateId": "lt-0123456789abcdef0",
    "Version": "1"
  },
  "VPCZoneIdentifier": "subnet-0123456789abcdef0,subnet-0123456789abcdef1",
  "HealthCheckType": "EC2",
  "HealthCheckGracePeriod": 300,
  "Tags": [
    {
      "Key": "Environment",
      "Value": "Development",
      "PropagateAtLaunch": true
    }
  ]
}

ASG Additional Configuration​

note

Currently, ASG Additional Configuration is behind the feature flag CDS_ASG_ENABLE_METRICS. Please contact Harness support to enable this feature.

Enabling Metrics in ASG

You can use the ASG Additional Configuration to configure your ASG Metrics. Store the metrics JSON file in any filestore of your choice and reference the file in the configuration.

Steps to Configure ASG Metrics:

  1. Click on Add ASG Additional Configuration.
  2. Specify the ASG Additional Configuration Store. You can store your configuration file in the following repositories:
    • Git
    • GitHub
    • GitLab
    • Bitbucket
    • Harness Code Repository
  3. In Manifest Details tab, provide the name of the manifest in Manifest Identifier and the File/Folder Path of the manifest. Click Submit to save the configuration.

In the Metrics Configuration, there is a boolean variable enableMetrics:

enableMetrics:

  • Set enableMetrics to true to enable all the metrics defined in the metricsCollection.
  • Set enableMetrics to false to disable the metrics defined in the metricsCollection.

metricsCollection The metricsCollection is a collection that specifies the metrics to be included in the manifest.

ASG metrics configuration file example

Here is a sample JSON to show the metrics configuration

{
  "metrics": {
    "enableMetrices": true,
    "metricsCollection": [
      {
        "metric": "GroupDesiredCapacity",
        "granularity": "1Minute"
      },
      .
      .
      .
    ]
  }
}

Upon successful pipeline execution, the metrics will be retrieved from the specified file. Once the fetch is complete, the metrics will be enabled in your AWS account, along with all configurations defined in the metricsCollection.

Additionally, you can configure Metrics in the Overrides to modify the manifest. To override the manifest, navigate to Overrides, select Manifest from the dropdown, and choose ASG Additional Configuration. This allows you to override the manifest specified in the service.

User Data​

You can add standard AWS AMI user data to enter configuration scripts and directives that your AWS instance will run upon launch.

The resulting User Data container corresponds to the AWS Launch Instance wizard's Advanced Details > User data container.

The user data can be added using the Harness File Store or any Git provider.

  • What can I add in user data? You can enter the same shell scripts and cloud-init directives that AWS will accept through its own UI. For details about scripting requirements, formatting, and options, see Amazon's EC2 User Data and Shell Scripts documentation. When Harness creates a new instance, it will apply your defined user data.
  • Permissions for your user data: If your user data is going to perform actions that require permissions, ensure that the IAM role assigned to the Harness Delegate(s) has the required roles and policies.

Scaling Policy​

Add a scaling policy to apply to the ASG that Harness will create during deployment.

You can use standard AWS scaling policies formatted in JSON. For example:

{
  "policyName": "demoPolicy",
  "adjustmentType":"PercentChangeInCapacity",
  "scalingAdjustment":30
}

The scaling policy can be added using the Harness File Store or any Git provider.

Scheduled Update Group Action​

You can schedule scaling using a standard AWS scheduled action formatted in JSON. For example:

{
  "scheduledActionName": "scheduledActionName1",
  "startTime": "2030-03-31T08:00:00Z",
  "desiredCapacity": 2
}

The scaling policy can be added using the Harness File Store or any Git provider.

AMI artifacts​

Review the following information about the AMI artifacts you select in your ASG service.

Only private AMIs are supported​

When you add an AMI artifact you must use a private AMI. Public AMIs from the AMI Catalog are not supported at this time.

In the AWS console, in EC2, private AMIs are listed in Images > AMIs.

Artifact AMI overrides config files AMIs​

You can specify an AMI in the launch template used in the Harness service, but it will be overridden by the AMI specified in the Harness service Artifacts section.

The AMI specified in the Harness service Artifacts section is the same as selecting an AMI in the Create launch template wizard in the AWS console or ImageId in in the create-launch-template CLI command.

Using service variables in config file​

Service variables are a powerful way to template your services or make them more dynamic.

In the Variables section of the service, you can add service variables and then reference them in any of the ASG configuration files you added to the service.

For example, you could create a variable named desiredCapacity and set its value as a fixed value, runtime input, or expression.

service variable

Next, in your ASG configuration file, you could reference the variable like this (see <+serviceVariables.desiredCapacity>):

{
  "autoScalingGroupName": "lovish2-asg",
  "minSize": 1,
  "maxSize": 3,
  "desiredCapacity": <+serviceVariables.desiredCapacity>,
  "tags": [{"key": "key7", "value":  "value7"}, {"key": "key2", "value":  "value2"}],
  "availabilityZones": ["us-east-1a", "us-east-1b"]
}

Now, when you add that service to a pipeline, you will be prompted to enter a value for this variable in the pipeline Services tab. The value you provide is then used as the desiredCapacity in your ASG configuration.

Harness ASG environments​

The Harness ASG environment is where you specify production and non-production environment settings.

You also add a infrastructure definition to define the region where you want to deploy the ASG.

note

You can create an environment when you are building the pipeline or separately in Environments. In this topic, we walk through building the environment separately. For more information, go to CD pipeline modeling overview.

Here's a YAML example of an ASG environment.

environment:
  name: ASG
  identifier: ASG
  description: ""
  tags: {}
  type: Production
  orgIdentifier: default
  projectIdentifier: myProject
  variables: []

Define the infrastructure​

You define the target infrastructure for your deployment in the Environment settings of the pipeline stage. You can define an environment separately and select it in the stage, or create the environment within the stage Environment tab.

There are two methods of specifying the deployment target infrastructure:

  • Pre-existing: the target infrastructure already exists and you simply need to provide the required settings.
  • Dynamically provisioned: the target infrastructure will be dynamically provisioned on-the-fly as part of the deployment process.

For details on Harness provisioning, go to Provisioning overview.

Pre-existing ASG infrastructure​

To define the target ASG region, you add an infrastructure definition to a Harness environment. The infrastructure definition uses a Harness AWS connector and a region setting to define the deployment target.

You can use the same AWS connector you used when adding the AMI artifact in the Harness service. Ensure the AWS IAM user in the AWS connector credentials meets the AWS policy requirements.

Here's a YAML example of an ASG infrastructure definition.

infrastructureDefinition:
  name: asg-infra
  identifier: asginfra
  description: ""
  tags: {}
  orgIdentifier: default
  projectIdentifier: DoNotDelete_IvanBalan
  environmentRef: ASG
  deploymentType: Asg
  type: Asg
  spec:
    connectorRef: AWS_ASG_CONNECTOR
    region: us-east-1
  allowSimultaneousDeployments: false

Dynamically provisioned ASG infrastructure​

Here's a summary of the steps to dynamically provision the target infrastructure for a deployment:

  1. Add dynamic provisioning to the CD stage:

    1. In a Harness Deploy stage, in Environment, enable the option Provision your target infrastructure dynamically during the execution of your Pipeline.

    2. Select the type of provisioner that you want to use.

      Harness automatically adds the provisioner steps for the provisioner type you selected.

    3. Configure the provisioner steps to run your provisioning scripts.

    4. Select or create a Harness infrastructure in Environment.

  2. Map the provisioner outputs to the Infrastructure Definition:
    1. In the Harness infrastructure, enable the option Map Dynamically Provisioned Infrastructure.
    2. Map the provisioning script/template outputs to the required infrastructure settings.

Supported provisioners​

The following provisioners are supported for Lambda deployments:

  • Terraform
  • Terragrunt
  • Terraform Cloud
  • CloudFormation
  • Shell Script

Adding dynamic provisioning to the stage​

To add dynamic provisioning to a Harness pipeline Deploy stage, do the following:

  1. In a Harness Deploy stage, in Environment, enable the option Provision your target infrastructure dynamically during the execution of your Pipeline.

  2. Select the type of provisioner that you want to use.

    Harness automatically adds the necessary provisioner steps.

  3. Set up the provisioner steps to run your provisioning scripts.

For documentation on each of the required steps for the provisioner you selected, go to the following topics:

Mapping provisioner output​

Once you set up dynamic provisioning in the stage, you must map outputs from your provisioning script/template to specific settings in the Harness Infrastructure Definition used in the stage.

  1. In the same CD Deploy stage where you enabled dynamic provisioning, select or create (New Infrastructure) a Harness infrastructure.

  2. In the Harness infrastructure, in Select Infrastructure Type, select AWS if it is not already selected.

  3. Enable the option Map Dynamically Provisioned Infrastructure.

    A Provisioner setting is added and configured as a runtime input.

  4. Map the provisioning script/template outputs to the required infrastructure settings.

To provision the target deployment infrastructure, Harness needs specific infrastructure information from your provisioning script. You provide this information by mapping specific Infrastructure Definition settings in Harness to outputs from your template/script.

For ASG, Harness needs the following settings mapped to outputs:

  • Base ASG: The base ASG is not used in the deployment. It is simply cloned in order for Harness to create a new ASG. Harness will use this existing ASG as a template, but it will not resize it all. The newly created ASG will have unique name, Min and Max instances, and Desired Capacity.

In the Harness Infrastructure Definition, in Base ASG, select the ASG to use as the base ASG.

Harness ASG pipelines​

Once you have the service and environment created, you can create the pipeline.

note

You can create a service and environment when you are building the pipeline or separately in Services and Environments. In this topic, we walk through building these separately. For more information, go to CD pipeline modeling overview.

The pipeline models the release process using execution steps, triggers, and other settings. For more information, go to CD pipeline modeling overview.

Here's a pipeline with a service, environment, and ASG Rolling Deploy and ASG Rolling Rollback steps:

pipeline:
  projectIdentifier: CD_Docs
  orgIdentifier: default
  tags: {}
  stages:
    - stage:
        name: DeployRolling
        identifier: Deploy
        description: ""
        type: Deployment
        spec:
          deploymentType: Asg
          service:
            serviceRef: svcasg
            serviceInputs:
              serviceDefinition:
                type: Asg
                spec:
                  artifacts:
                    primary:
                      primaryArtifactRef: <+input>
                      sources: <+input>
                  variables:
                    - name: desiredCapacity
                      type: String
                      value: <+input>
          environment:
            environmentRef: ASG
            deployToAll: false
            infrastructureDefinitions:
              - identifier: asginfra
          execution:
            steps:
              - step:
                  name: ASG Rolling Deploy
                  identifier: AsgRollingDeploy
                  type: AsgRollingDeploy
                  timeout: 10m
                  spec:
                    useAlreadyRunningInstances: false
                    skipMatching: true
            rollbackSteps:
              - step:
                  type: AsgRollingRollback
                  name: ASG Rolling Rollback
                  identifier: ASG_Rolling_Rollback
                  spec: {}
                  timeout: 10m
        tags: {}
        failureStrategies:
          - onFailure:
              errors:
                - AllErrors
              action:
                type: StageRollback
  identifier: ASGROLLING
  name: ASG-ROLLING

ASG pipeline execution strategies​

Harness ASG deployments support the following deployment strategies:

  • Rolling
  • Canary
  • Blue Green

Rolling​

The first ASG rolling deployment will deploy a new ASG with the number of desired instances you have defined in your ASG configuration file in the Harness service used in the pipeline. Any other configuration files in the service are also applied.

Subsequent deployments will deploy a new version of the same ASG with any changes you have made in the Harness service configuration files (launch template, ASG configuration, etc.). This is the same as using the Edit buttons in the AWS console and creating a new version of the ASG.

Here's a flowchart that explains how Harness performs rolling deployments:

Rolling deployments flowchart

ASG rolling flowchart

The Rolling Deploy step has the following options:

  • ASG Name: Enter a name for the ASG that Harness will create.
  • Same as already running Instances or Fixed:
    • Select Fixed to enforce a Max, Min, and Desired number of instances.Select Same as already running Instances to use scaling settings on the last ASG deployed by this Harness pipeline. If this is the first deployment and you select Same as already running Instances, Harness uses a default of Min 0, Desired 6, and Max 10. Harness does not use the Min, Max, and Desired settings of the base ASG.
  • Minimum Healthy Percentage (optional)
    • The percentage of the desired capacity of the ASG that must pass the group's health checks before the refresh can continue. For more information, go to Health checks for Auto Scaling instances from AWS. If not specified, harness sets the default value for this field as 90% during rolling deployment and 100% during rollback.
  • Maximum Healthy Percentage (optional)
    • The percentage of the desired capacity of the ASG that your ASG can increase to when replacing instances. For more information, go to Instance refresh core concepts from AWS. If not specified, harness sets the default value for this field as 110% during rolling deployment and 200% during rollback.
  • Instance Warmup (optional)
  • Skip Matching
    • Choose whether AWS Auto Scaling skips replacing instances that match the desired configuration. If no desired configuration is specified, then it skips replacing instances that have the same launch template and instance types that the ASG was using before the instance refresh started. For more information, go to Use an instance refresh with skip matching from AWS.
YAML example
          execution:
            steps:
              - step:
                  name: ASG Rolling Deploy
                  identifier: AsgRollingDeploy
                  type: AsgRollingDeploy
                  timeout: 10m
                  spec:
                    useAlreadyRunningInstances: false
                    skipMatching: true

Deployment logs​

Here's an example of the log from a successful deployment.

ASG Rolling Deploy log example
Deploy

Starting Rolling Deployment
Creating new version for launchTemplate demo-asg2
Created new version for launchTemplate demo-asg2
Getting Asg demo-asg2
Creating Asg demo-asg2
Waiting for Asg demo-asg2 to reach steady state
Polling every 20 seconds
Getting Asg demo-asg2
Getting Asg demo-asg2
0/2 instances are healthy
Getting Asg demo-asg2
2/2 instances are healthy
Created Asg demo-asg2 successfully
Getting Asg demo-asg2
Modifying scaling policies of Asg demo-asg2
Getting ScalingPolicies for Asg demo-asg2
No policies found which are currently attached with autoscaling group: [demo-asg2] to detach
No scaling policy provided which is needed be attached to autoscaling group: demo-asg2
Modified scaling policies of Asg demo-asg2 successfully
Modifying scheduled actions of autoscaling group demo-asg2
Getting ScheduledUpdateGroupActions for Asg demo-asg2
No scheduled actions found which are currently attached with autoscaling group: [demo-asg2] to detach
Attached scheduled action with name: scheduledActionName1
Modified scheduled actions of autoscaling group demo-asg2 successfully
Starting Instance Refresh for Asg demo-asg2
Waiting for Instance Refresh for Asg demo-asg2 to reach steady state
Polling every 20 seconds
Percentage completed: 0
Waiting for remaining instances to be available. For example: i-03e47024515f6d45a has insufficient data to evaluate its health with Amazon EC2.
Percentage completed: 0
Waiting for remaining instances to be available. For example: i-03e47024515f6d45a has insufficient data to evaluate its health with Amazon EC2.
Percentage completed: 0
Waiting for remaining instances to be available. For example: i-03e47024515f6d45a has insufficient data to evaluate its health with Amazon EC2.
Percentage completed: 0
Waiting for remaining instances to be available. For example: i-03e47024515f6d45a has insufficient data to evaluate its health with Amazon EC2.
Percentage completed: 100
Instance Refresh for Asg demo-asg2 ended successfully
Rolling Deployment Finished Successfully

Canary​

The ASG canary deployment uses two step groups:

  1. Canary Deployment:
    1. ASG Canary Deploy step: deploys a new ASG version with the name of your ASG and the extension __Canary. The canary ASG version can use the desiredCapacity in your ASG configuration file or you can set it in the Instances setting in the ASG Canary Deploy step.
    2. ASG Canary Delete step: deletes the canary ASG.
  2. Primary Deployment:
    1. ASG Rolling Deploy step:
      1. The first deployment will deploy a new ASG with the number of desired instances you have defined in your ASG configuration file in the Harness service used in the pipeline. Any other configuration files in the service are also applied.
      2. Subsequent deployments will deploy a new version of the same ASG with any changes you have made in the Harness service configuration files (launch template, ASG configuration, etc.). This is the same as using the Edit buttons in the AWS console and creating a new version of the ASG.

Here's what the two step groups look like:

ASG canary step groups

The ASG Canary Deploy step deploys a new ASG with the name of your ASG and the extension __Canary.

In the ASG Canary Deploy step, in Instances, you can specify how many instances to use in this temporary ASG.

The Instances replaces the desiredCapacity in your ASG configuration file.

ASG Canary Deploy step log example
Getting Asg demo-asg2__Canary
Creating launchTemplate demo-asg2__Canary
Created launchTemplate demo-asg2__Canary successfully
Getting Asg demo-asg2__Canary
Creating Asg demo-asg2__Canary
Waiting for Asg demo-asg2__Canary to reach steady state
Polling every 20 seconds
Getting Asg demo-asg2__Canary
Getting Asg demo-asg2__Canary
0/1 instances are healthy
Getting Asg demo-asg2__Canary
1/1 instances are healthy
Created Asg demo-asg2__Canary successfully
Getting Asg demo-asg2__Canary
Deployment Finished Successfully

Canary phased deployment​

You can create a multi-phase workflow that progressively deploy your new instances to a new ASG incrementally using the ASG Phased Deploy step when creating a Canary deployment.

When you select the Canary execution strategy for your pipeline, make sure to select the Add Multi Phase Canary Steps to enable phased deployment.

ASG phased execution

A phased deployment uses two step groups:

  1. A Canary phase containing steps that define your ASG, deploy a percentage or partial count of the ASG's instances, and verify this partial deployment. You can add more Canary phases that expand the partial deployment.
  2. A Primary phase that deploys your image to the full count of instances defined in your ASG.

ASG phased deploy

Here're the steps we build:

ASG Setup:

This step will remove older non-used ASGs, and create new a new ASG with zero instances and desired launch template configuration. In this step, you can specify how many EC2 instances to launch in the ASG that Harness deploys at the end of the workflow. You can also specify the resizing order and steady state timeout of the instances.

The instance can be Fixed Instances and Same as already running instances. If you select same as already running instances, then Harness fetches the minimum, maximum, and desired capacity of current live ASG and use that for configuring this step.

There are two resize options:

  • Resize New First: Select to resize new ASG first and then downsize older ASG.
  • Downsize Old First: Select to downsize older ASG first and then resize new ASG.

ASG Setup step config

Here's a sample ASG Setup step YAML for the Fixed Instances option:

              - step:
                  type: AsgSetup
                  name: AsgSetup_1
                  identifier: AsgSetup_1
                  spec:
                    asgName: abcd
                    instances:
                      type: CurrentRunning
                    resizeStrategy: "resize_new_first"
                  timeout: 10m

Here's a sample ASG Setup step YAML for the Same as already running instances option:

          - step:
              type: AsgSetup
              name: AsgSetup_1
              identifier: AsgSetup_1
              spec:
                asgName: abcd
                instances:
                  type: Fixed
                  spec:
                    desired: 2
                    max: 3
                    min: 1
                resizeStrategy: "downsize_old_first"
              timeout: 10m

ASG Phased Deploy:

In this step, you can specify the percentage or count of instances to deploy in this phase. When you add additional Canary phases, each phase automatically includes an ASG Phase Deploy, which you must configure with the count or percentage of instances you want deployed in that phase.

This step will resize the new ASG to desired instance, and then downsize the older ASG to desired instance. For example, increase the instance count of new ASG by 1, then decrease the instance count of older ASG by 1.

Here's a sample ASG Phased Deploy step YAML:

              - step:
                  type: AsgPhasedDeploy
                  name: AsgPhasedDeployStep_1
                  identifier: AsgPhasedDeployStep_1
                  spec:
                    instanceSelection:
                      type: Count
                      spec:
                        count: 1
                  timeout: 10m

ASG Rollback:

This step will rollback to the initial setup (setup before ASG setup was created). Here, the new ASG is deleted and the old ASG is up-sized to its pre-deployment instance count.

Here's a sample ASG Rollback step YAML:

          - step:
              name: Asg Rollback
              identifier: AsgRollback
              type: AsgRollback
              timeout: 10m
              spec: {} 

Blue Green​

An ASG Blue Green deployment uses two steps:

  1. ASG Blue Green Deploy step:
    1. You specify the production and stage listener ports and rules to use.
    2. The new ASG is deployed to the stage target group.
  2. ASG Blue Green Swap Services step:
    1. Harness modifies the ELB prod listener to forward requests to target groups associated with each new ASG version.
    2. Harness swaps all traffic from stage to production listeners and ports.
    3. Harness modifies the ELB stage listener to forward requests to target groups associated with old ASG version.

The first ASG deployed is given a suffix using the format [app_name]__1, like asgdemo__1. The second ASG deployed is given the suffix [app_name]__2.

Every subsequent deployment will simply create new versions of these ASGs instead of creating new ASGs. So the third deployment will create a new version of ASG [app_name]__1, route prod traffic to it, and route stage traffic to ASG [app_name]__2.

Here's a flowchart that explains how Harness performs Blue Green deployments:

Blue Green deployments flowchart

blue green flowchart map

AWS Requirements​

In addition to the requirements of the Harness ASG service and environment, an ASG Blue Green deployment requires you to set up the following resources up within AWS:

  • A security group that allows inbound access to your Application Load Balancer's listener ports. SG for ALB listener
  • A pair of target groups, typically staging (Stage) and production (Prod) both with the instance target type.
  • An Application Load Balancer (ALB) with one listener rule for both your target groups. listener rule

Let's take a look at the first two deployments.

First Blue Green deployment​

The first Blue Green deployment follows these steps:

  1. ASG Blue Green Deploy step:
    1. Checks that listener ARN and listener rule ARN are valid.
    2. Fetches target groups' ARN.
    3. Creates launch template and ASG using the format [app_name]__1, like asgdemo__1.
    4. Sets the tag BG_VERSION=BLUE on new ASG.
  2. ASG Blue Green Swap step:
    1. Not used as there is only one ASG at this point.

Second Blue Green deployment​

At the start, the second Blue Green deployment will only have one prod ASG (the one deployed in the first Blue Green deployment).

Harness will create a new ASG with the suffix __2 and swap prod traffic to it.

The second Blue Green deployment follows these steps:

  1. ASG Blue Green Deploy step:
    1. Checks that listener ARN and listener rule ARN are valid.
    2. Fetches target groups' ARN.
    3. Creates launch template and new ASG using the format [app_name]__2, like asgdemo__2.
    4. Sets the tag BG_VERSION=GREEN on new ASG, for example, asgdemo__2.
  2. ASG Blue Green Swap step swaps target groups and updates tags:
    1. Modifies the ELB prod listener to forward requests to target groups associated with new autoscaling group.
    2. Modifies the ELB stage listener to forward requests to target groups associated with the old autoscaling group.
    3. Updates tags of the autoscaling groups.

Now there are two ASGs being used: a prod and a stage ASG. Subsequent deployments will create a new versions of these ASGs and swap prod traffic to the new ASG version from the previous ASG.

Blue Green deployment steps:

The ASG Blue Green Deploy step has the following settings:

  • ASG Name: Enter a name for the ASG that Harness will create.

  • Same as already running Instances or Fixed:

    • Select Fixed to enforce a Max, Min, and Desired number of instances.Select Same as already running Instances to use scaling settings on the last ASG deployed by this Harness pipeline. If this is the first deployment and you select Same as already running Instances, Harness uses a default of Min 0, Desired 6, and Max 10. Harness does not use the Min, Max, and Desired settings of the base ASG.

  • Load Balancer: select the load balancer(s) to use.

  • Prod Listener: provide the ARN for the listener to be used for prod traffic. (e.g. arn:aws:elasticloadbalancing:us-east-2:999999999999:listener/app/[lbname]]/[lbref]/[listenerref]])

  • Prod Listener Rule ARN: provide the ARN for the listener rule to be used for prod traffic. (e.g. arn:aws:elasticloadbalancing:us-east-2:999999999999:listener/app/[lbname]]/[lbref]/[listenerref]/[ruleref]])

  • Stage Listener: provide the ARN for the listener to be used for staging traffic. (e.g. arn:aws:elasticloadbalancing:us-east-2:999999999999:listener/app/[lbname]]/[lbref]/[listenerref]])

  • Stage Listener Rule ARN: provide the ARN for the listener rule to be used for staging traffic. (e.g. arn:aws:elasticloadbalancing:us-east-2:999999999999:listener/app/[lbname]]/[lbref]/[listenerref]/[ruleref]])

    important

    There is only one listener rule for both target groups (stage and prod), and one listener ARN for a listener rule. Go to AWS requirements for more information.

Harness fetches these AWS settings using the Harness AWS connector you have set up in the Infrastructure Definition in the Environment section of the stage.

Blue Green traffic shift options​

There are two options for traffic-shifting with blue green deployments: instant and incremental.

Blue/Green with Instant Traffic Shift Summary​

In this strategy, you specify production and stage listener ports and rules to use in the ASG Blue Green Deploy step. Next, the ASG Swap Services step swaps all traffic from stage to production.

A Blue/Green deployment reliably deploys your ASGs by maintaining new and old versions of ASGs. The ASGs run behind an Application Load Balancer (ALB) using two listeners, stage and prod. These listeners forward respectively to two target groups, stage and prod, where the new and old ASGs are run.

In the first stage of deployment, the new ASG is attached to the stage target group:

first stage

Blue/Green deployments are achieved by swapping routes between the target groups—always attaching the new ASG first to the stage target group, and then to the prod target group:

second stage

Blue/Green with Incremental Traffic Shift Summary​

Here's a demo video of Blue Green with incremental traffic shift summary:

This deployment method lets you add ASG Shift Traffic steps to incrementally shift traffic from the Target Group used by the previous ASG to the Target Group used by the new ASG you are deploying.

With this strategy, you are not shifting traffic from stage and production environments. You are shifting traffic incrementally for a production environment. In this way, it is similar to a Canary strategy.

However, in a Canary deployment, the percentage of traffic that goes to the new ASG is determined by the number of instances (for example, 25% of 4 instances) or the forwarding policy of the load balancer.

With this Incremental Traffic Shift strategy, you are controlling the percentage of traffic sent to the new ASG. For example, 25% of all traffic.

To use incremental traffic shift, do the following:

  1. In the ASG Blue Green Deploy step, in ASG Load Balancer, select Use Shift Traffic.
  2. Next, add multiple ASG Traffic Shift steps. Typically, users can add Approval step between the ASG Traffic Shift step as checks.
  3. In the first ASG Traffic Shift step, in New Autoscaling Group Weight, enter the percentage of traffic you want shifted from the previous ASG to the new ASG you are deploying.
  4. Continue setting any subsequent ASG Traffic Shift steps.

The Downsize Old ASG at 0% weight setting should only be selected for the ASG Traffic Weight step that shifts traffic to 100% in its New Autoscaling Group Weight setting.

When this setting is enabled, the old ASG is downsized.

Advanced settings for all steps​

In the Advanced settings of all step, you can use the following options:

Notes​

AWS has the following limitations to keep in mind:

  • You are limited to creating 5000 launch templates per region and 10000 versions per launch template. For more information, go to Launch an instance from a launch template from AWS.
  • ASGs per region: 500.
  • Launch configurations per region: 200.

FAQs​

For frequently asked questions about AWS deployments in Harness, go to AWS deployment FAQs.