Bootstrapping AWS EC2 Instances
Problem Overview
To be able to do anything useful (hosting web application, create Jenkins master/node, worker node for batch processing etc.) you need to initialize or bootstrap your EC2 instance with software packages (prerequisite) required to run your application. There are a number of ways to do it which you need to know while launching a new EC2 instance either as standalone or as part of AutoScaling Group. The scenarios we are going to cover in this article are as follows:
- Run User Data when the EC2 instance is launched (first boot cycle)
- Run User Data on every restart of EC2.
- Using cfn-init script to configure EC2.
- Using SSM Document to bootstrap EC2 instance.
Scenario: User Data when the EC2 instance on first boot cycle
By default, user data scripts and cloud-init directives run only the first time when the EC2 instance is launched during the first boot cycle.
Notice that we are passing the entire script through the function Fn::Base64 which will convert the script to a Base64 string which user data needs in the CloudFormation.
You can test it by connecting to the EC2 instance created by the above stack through SSM Session Manager, and then checking the contents of /tmp/testfile.txt which shows ‘Hello World’. The output of user data can be checked by running the following command on the Session Manager console which simply shows the content of /var/log/cloud-init-output.log file.
Scenario: Run User Data on every restart of EC2
As mentioned in the last scenario, user data scripts and cloud-init directives run only the first time when the EC2 instance is launched during the first boot cycle but what if you need to run the UserData script every time the EC2 instance is restarted or in other words, you want to override the default behaviour. This is especially useful when you are making changes to UserData and don’t want to recreate the EC2 instance simply because UserData is changed. To solve this problem as explained here you can use a mime multi-part file to override how frequently user data is run in the cloud-init package.
The CloudFormation template to initialize an EC2 instance with user data on every restart is shown below. You can test it by simply rebooting the EC2 instance created by the stack of this template, then connecting through SSM Session Manager, and then checking the contents of /tmp/testfile.txt which gets ‘Hello World’ every time user data runs. As before, the output of user data can be checked by running the following command on the Session Manager console.
As expected, you can see ‘Hello World’ twice in testfile.txt, inserted the first time when the instance was launched and the second time when it was rebooted.
Scenario: Using cfn-init script to configure EC2
When using cfn-init, AWS::CloudFormation::Init needs to be in the Metadata of the resource. It helps to make complex EC2 configurations readable. The way it works is that the EC2 instance queries the CloudFormation service to get init data and once it replies then all the logs of running the cfn-init script goes to /var/log/cfn-init.log. The sequence of how cfn-init works is shown in the diagram below:
Notice that from cloud-init-output.log you can only see that cfn-init was called successfully but you can’t get any out about the script which was run by cfn-init, for that, you need to check cfn-init.log
Scenario: Using SSM Document
Using SSM Document is probably the best way to bootstrap an EC2 instance for the following reasons:
- Command history can be found for all the commands run against EC2 instances.
- If the same commands need to be run on multiple instances then all you need to do is tag those instances with a key/value and specify that key/value in the SSM Association target.
- If you need to re-run the command again then you can do that anytime by simply selecting command id and clicking ‘Run command’.
- Keeps CloudFormation template cleaner and easier to read.
- The complete output of command run and errors is saved in the S3 bucket.
CloudFormation template to bootstrap EC2 instance using SSM Document can be found below:
Final Thoughts
As you can see above, using SSM Document is probably the best way to bootstrap EC2 instance but it doesn’t get as much attention as it deserves but on the other hand user data is the worst way to bootstrap instance due to its inflexibility but everyone knows about it. This is something for AWS to focus on that how to create awareness about cool features like SSM Document bootstrapping EC2 instances.
