AWS ASG Deployment

deploy kmagent across an auto scaling group with zero manual per instance work configure once in the launch template, every instance (existing + future scale outs) gets the agent automatically prerequisites aws cli configured with appropriate permissions an existing asg with a launch template iam instance profile attached to your asg instances ssm agent running on instances (default on amazon linux / ubuntu amis) step 1 store api key in ssm parameter store never hardcode secrets in user data use ssm parameter store with encryption aws ssm put parameter \\ \ name "/kloudmate/api key" \\ \ value "your actual km api key" \\ \ type securestring \\ \ region ap south 1 step 2 iam permissions ensure your asg's iam instance profile has permission to read the ssm parameter { "version" "2012 10 17", "statement" \[ { "effect" "allow", "action" "ssm\ getparameter", "resource" "arn\ aws\ ssm\ ap south 1\ your account id\ parameter/kloudmate/ " } ] } if using ssm run command (step 5, option b), also add { "effect" "allow", "action" \[ "ssm\ sendcommand", "ssm\ listcommandinvocations" ], "resource" " " } step 3 create the user data script save this as userdata sh \#!/bin/bash set euo pipefail \# \# fetch api key from ssm (imdsv2 compatible) \# region=$(curl sf http //169 254 169 254/latest/meta data/placement/region) token=$(curl sf x put "http //169 254 169 254/latest/api/token" \\ h "x aws ec2 metadata token ttl seconds 60") km api key=$(aws ssm get parameter \\ \ name "/kloudmate/api key" \\ \ with decryption \\ \ query "parameter value" \\ \ output text \\ \ region "$region") \# \# install kmagent \# curl fssl https //raw\ githubusercontent com/kloudmate/km agent/main/install sh \\ \| bash s \\ \ api key "$km api key" \\ \ colector endpoint "https //otel kloudmate com" \# \# verify \# if systemctl is active quiet kmagent; then echo "\[kloudmate] agent installed and running" else echo "\[kloudmate] error agent failed to start" journalctl u kmagent no pager n 20 exit 1 fi step 4 apply user data to launch template via aws cli # create a new launch template version with user data aws ec2 create launch template version \\ \ launch template name your template name \\ \ source version '$latest' \\ \ launch template data '{ "userdata" "'$(base64 w0 userdata sh)'" }' \# point asg to use the latest version aws autoscaling update auto scaling group \\ \ auto scaling group name your asg name \\ \ launch template "launchtemplatename=your template name,version=\\$latest" via aws console go to ec2 → launch templates → your template click actions → modify template (create new version) scroll to advanced details → user data paste the contents of userdata sh click create template version go to auto scaling groups → your asg click edit → launch template → version → latest save step 5 roll out to existing instances the new user data only executes on newly launched instances to deploy on your existing 50 instances, choose one of the following option a instance refresh rolling replace terminates and replaces instances in batches each new instance boots with the updated user data and gets kmagent automatically aws autoscaling start instance refresh \\ \ auto scaling group name your asg name \\ \ preferences '{ "minhealthypercentage" 90, "maxhealthypercentage" 110, "instancewarmup" 120 }' how it works keeps 90% of instances healthy at all times replaces 5 instances at a time (for a fleet of 50) each batch waits for health checks to pass before proceeding total rollout time 20 30 minutes depending on health check config monitor progress aws autoscaling describe instance refreshes \\ \ auto scaling group name your asg name option b ssm run command in place install, no downtime installs the agent on running instances without replacing them fastest path to full coverage aws ssm send command \\ \ targets "key=tag\ aws\ autoscaling\ groupname,values=your asg name" \\ \ document name "aws runshellscript" \\ \ parameters 'commands=\[ "region=$(curl sf http //169 254 169 254/latest/meta data/placement/region)", "token=$(curl sf x put http //169 254 169 254/latest/api/token h x aws ec2 metadata token ttl seconds 60)", "km api key=$(aws ssm get parameter name /kloudmate/api key with decryption query parameter value output text region $region)", "curl fssl https //raw\ githubusercontent com/kloudmate/km agent/main/install sh | bash s api key $km api key collector endpoint https //otel kloudmate com" ]' \\ \ max concurrency "10" \\ \ max errors "5" \\ \ comment "install kmagent on asg fleet" how it works runs on 10 instances at a time ( max concurrency 10) all 50 instances done in 5 batches stops if more than 5 instances fail ( max errors 5) zero downtime — no instance restarts required monitor progress \# get command id from send command output, then aws ssm list command invocations \\ \ command id "command id" \\ \ details \\ \ query "commandinvocations\[] {instance\ instanceid,status\ status}" \\ \ output table which option to choose? criteria option a (instance refresh) option b (ssm run command) downtime brief per instance (rolling) none speed 20 30 min 5 10 min instance state fresh instances existing instances preserved risk lower (clean slate) slightly higher (in place) use when you want clean rollout you need it now recommended approach use option b for the immediate install on all 50 instances today, and the launch template user data ensures every future instance is covered automatically verification after deployment, verify the agent is running across your fleet \# check all instances via ssm aws ssm send command \\ \ targets "key=tag\ aws\ autoscaling\ groupname,values=your asg name" \\ \ document name "aws runshellscript" \\ \ parameters 'commands=\["systemctl status kmagent | head 5"]' \\ \ max concurrency "50" \\ \ output text \# or ssh into any instance and check systemctl status kmagent journalctl u kmagent f # follow logs curl s http //localhost 13133 # health check endpoint troubleshooting issue cause fix unable to locate credentials iam instance profile missing or no ssm permissions attach iam role with ssm\ getparameter to your launch template command not found aws aws cli not installed on instance add yum install y aws cli or apt install y awscli before the ssm call in user data kmagent failed to start port conflict or config error check journalctl u kmagent n 50 on the instance ssm command stuck in pending ssm agent not running ensure amazon ssm agent is installed and running instance refresh stuck health check failing on new instances check your asg health check grace period and target group settings