Sending custom notifications from PowerShell using AWS SNS

Last update: 3/9/2015

Amazon Web Services provides quite a bit of interesting and useful services, many of which you can use through a number of APIs. One that can be particularly useful for someone using PowerShell is the Simple Notification Service (SNS). It allows you to create push notification endpoints, and then send yourself or others notifications to email, Apple iOS, Amazon Kindle Fire, or other web services. If you're unfamiliar with Amazon's terminology however, it can be somewhat confusing to navigate through all the right screens. Here is a quick tutorial that will show you how to set up SNS, an API user, and then use that information to send yourself notifications.

1. Installing the SDK

Amazon provides a PowerShell SDK that you can download from [http://aws.amazon.com/powershell]( http://aws.amazon.com/powershell). It's a simple install, just go Next until the end. Once that's done, you can access it directly through the start menu by clicking on the Windows PowerShell for AWS link, or by importing the module in any PowerShell window:

Import-Module AWSPowerShell

The first time you run it, the shell will ask for the credentials of an IAM user, which is Amazon's way of handling authentication.

2. Creating an AWS IAM user

To access the API, you need to have an IAM user with the right permissions. To create one, log into the AWS console at http://aws.amazon.com/console, then under Services at the top of the screen, select IAM. There, click on Create New Users:

You can give it any name you want, and once done, you will be given an Access Key and Access Secret. You can also access those from the Security Credentials section. by clicking on Manage Access Keys:

Make sure you write them down, these are the credentials you will need to use the AWS PowerShell commands.

3. Creating a SNS topic and subscription

SNS works with topics and subscriptions. Basically, a topic defines a unique address to which you can send notifications to specific endpoints. Click on the Create New Topic button:

You can enter a topic name and description. Once created, it will show you the Topic ARN. Write it down. Next, you need to add a subscription to that topic. Click on New Subscription and select an endpoint. You can select an email address, web site, and so on:

If you pick Email for example, you can enter an email address and notifications for this topic will be sent there. Make sure you confirm your email address.

4. Assigning a policy to your user

Now that you have a SNS topic created with an endpoint attached, you need to give your IAM user access to it. Go back to IAM under the Services menu, and select the user you created previously.

Under Inline policies, click on Create User Policy:

There, you can use the Policy Generator to create your user policy. Select the SNS service, all actions, and type in your Topic ARN:

Click on Add Statement, Next Step, and then Apply Policy. Your user now has access to the SNS topic you created.

5. Sending notifications

Now that we have an SNS topic, subscription, and an API user with access to it, we can send a test notification. Go to your PowerShell window and make sure you entered your AWS credentials when prompted, or use Set-AWSCredentials to do it after importing the AWS module:

Import-Module AWSPowerShell Set-AWSCredentials -StoreAs default -AccessKey XXXXX -SecretKey ZZZZZ

Now you can send yourself a notification:

Publish-SNSMessage -TopicArn YOUR_TOPIC_ARN -Subject "Testing" -Message "This is a test" -Region us-west-2

Make sure you use the right region where you created your SNS topic. If all went well, you should receive a confirmation number and your notification should be sent. Otherwise you will get an error telling you what went wrong.

Conclusion

SNS is a great way to send yourself or team members notifications from scripts. You can use it in cases where something break, health checks fail, or in any number of situations. Do keep in mind that SNS isn't free, although it is pretty cheap. For pricing information and more about SNS check out the AWS SNS documentation.



© 2008-2017 Patrick Lambert - All resources on this site are provided under the MIT License - You can contact me at: dendory@live.ca