Sometimes you need to ensure that things are always a certain way when you deploy AWS EC2 instances. This could be things like making sure your servers are always joined to a domain when being deployed, or making sure you run an Ansible playbook every hour. The point of the AWS EC2 SSM State Manager service is to define a consistent state for your EC2 instances.

This post will use a fictional use case where I have a an EC2 instance or instances that are checking every thirty minutes to see if they should use a new image for their Apache website. The instance will check against the EC2 Simple Systems Manager Parameter Store, which we’ve discussed in a previous post, and will download the image from the S3 location retrieved from that parameter.

Get Started with State Manager

To get started with the State Manager process click “State Manager” in the EC2 dashboard on the left hand side under the “System Manager Services” heading. You should see a familiar getting started screen if you’ve never used it before like the one below.

Now if you haven’t been following along with the series, the first thing you’d want to do is to create an association document. This is an SSM document like the one we created in a previous post that copied our image from S3 to our Apache server. The link to how we setup that document can be found here: https://theithollow.com/2017/09/18/aws-ec2-simple-systems-manager-documents/

If you haven’t created a document before you’ll want to create that association document first, but since we’ve done that already during our previous post, we next need to create our association. Click the “Create an association” button to get started. The first thing you’ll need to enter is an association name. Be sure to make it something descriptive so you can understand later what the association is used for. The next thing you’ll do is select the association document. This will be the document that you created during the previous post on SSM Documents. I’ve selected the one named itHollowApache-Web1 from that post. If you have multiple revisions of that document you can specify which version should be run when the state manager executes. I’ve left the default for this example.

As you scroll down you’ll need to select the targets. Since I’m only using a single instance, i’m just manually selecting it here. To make this more useful for a dynamic environment you can specify a tag so that any new instances with that tag will automatically be associated with the state we’re creating. Probably a better choice for most environments, but this is an example.

Next, we’ll specify a schedule. You can use a cron or rate scheduler to determine how often this job will run. I’ve selected every 30 minutes. So in effect, I’ll be copying an image from Amazon S3 every thirty minutes to my Apache server.

Next, if your SSM Document had any parameters, you can specify them here as well. My parameter is just used for show so I’m leaving it blank. If you remember from the previous post I’m grabbing a parameter from the parameter store by running the SSM get-parameters command from within my EC2 instance. Lastly, you can choose to write the state association details to an S3 bucket, which I won’t for this example.

The Result

What happens in the end is that I have my EC2 instance running Apache with a default web page on the left. With the quick change to the parameter in the parameter store, I can change the default image on my Apache instance(s) and they’ll automatically update their configurations within 30 minutes throughout my entire fleet of Apache instances.

The result is shown below where the site on the left would be image1 and the site on the right is image2. All updated by changing the parameter in the parameter store within SSM.

Summary

I’m sure that you can come up with tons of great ways to use this service and this post should serve as a very basic example. I’d think that this could be incredibly useful when leveraged with things like a configuration management tool like Ansible, or if you’d rather, create your own configuration management like scripts to keep your fleet from having too much drift. Good luck and happy coding!