Administrators who work with Microsoft Azure have often found that it is more efficient to use PowerShell for Azure virtual machine management than to use the Azure Portal. Not to be outdone, Amazon has created a similar mechanism for Amazon EC2. This mechanism, which Amazon refers to as Run Command is supported for all versions of Windows Server and for many of the more popular Linux builds. Run Command can be used to not only run PowerShell cmdlets, but also to execute Shell scripts on Linux servers.
Although Amazon Run Command does a good job of letting administrators run commands against cloud based resources, it works a little bit differently than what you might expect. In an Azure environment, an administrator is able to open a PowerShell window on a local machine, import an Azure specific module, connect to the organization’s Azure subscription, and then perform whatever task needs to be completed. The whole process takes place using native PowerShell.
The disadvantage to using Amazon’s Run Command is that it does not use a native PowerShell environment. Of course the flip side to this is that because you will not be working within a PowerShell window, you are not limited to solely using PowerShell cmdlets. Amazon’s Run Command actually presents you with a dialog box in which you can enter commands to be run against remote resources.
So with that said, let’s take a look at how to use Run Command. The first thing that you need to know is that Run Command is not currently supported for all regions. Right now the only supported regions are US East (N. Virginia), US West (Oregon), and Europe (Ireland). In addition, there are several other prerequisites that you must adhere to.
First, you must make sure that your virtual machines are running a supported operating system and the latest version of the SSM agent. All Windows Server versions are supported, but not every Linux distribution is supported. The supported Linux builds include:
- Amazon Linux (64-bit) 2015.09, 2015.03, 2014.09, 2014.03
- Ubuntu Server (64-bit) 14.04 LTS, 12.04 LTS
- Red Hat Enterprise Linux (RHEL 64-bit) 7.x
An IAM server role is also required for all instances that will be processing commands. A separate role is also required for users who wish to execute commands. Any IAM roles that are used by Run Command must have permission policies that allow the IAM roles to communicate with SSM APIs. It is generally recommended that you use SSM managed policies, but you can create your own custom IAM policies if necessary.
The last firm requirement is that your EC2 instances must have outbound Internet access. These instances do not have to support inbound Internet connectivity, but they must support outbound Internet connectivity.
There is one optional prerequisite. Although not technically required, it is a good idea to have an S3 bucket. Remember what I said about Run Command not using a native PowerShell window? Well, the interface that Amazon uses can display command output, but only the first 2500 characters of the output are displayed. Admittedly, that sounds like a lot, but from the beginning of this article up to this point right here there have already been roughly about 3255 characters. This means that 2500 characters would represent less than one page of typed text. Some PowerShell cmdlets can return far more text than this, and a bucket allows you to capture the full output as opposed to having the output truncated.
Amazon Run Command works differently depending on whether you are using the Amazon EC2 console or the Amazon CLI interface. For the sake of this article, I want to briefly describe how you might use Run Command through the Amazon EC2 console.
To use Run Command, the first thing that you will need to do (logically enough) is to click on the Run a Command button. When you do, the EC2 console will display the Run a Command dialog box. This dialog box asks you to choose a command document. In other words, you can’t simply enter the command that you want to run, you have to choose the command document that includes information about the command that you intend to run. Suppose for instance that your goal was to run a Shell Script. To do so, you would choose the command document named AWS-RunShellScript.
The next thing that you will need to do is to click on the Select Instances button and then choose the instances at which you want to direct the command that you are going to be running. In some cases, the list of instances might be incomplete. If that happens, then the first thing that you should do is to refresh the console to see if the missing instances show up. If that does not work, then it could be that the missing instances do not fully meet the requirements. Check the instance to make sure that it is running a supported operating system and that it has the latest version of the SSM agent installed.
After you select the desired instances, it is time to enter some information that is specific to the command that you plan to run. There are four fields that you will initially want to populate. The first of these fields is the most obvious – Commands. This is where you enter the command or commands that you want to execute on the target instances.
The second field that you must populate is the working directory. In other words, under what path do you want to run the command?
The third thing that you have to enter is the execution timeout. This is the number of seconds that Run Command should wait to hear from an instance before it considers the instance to be unreachable.
The fourth field is the Comment field. It is a good idea to enter a short comment explaining what the command does or why you are running the command.
Earlier I mentioned that you have the option of using an S3 bucket. If you do opt to use a bucket, then you should enter the bucket name and an S3 Key Prefix. You can think of the S3 Key Prefix as being like a sub folder. You can create sub folders for various classes of commands.
When you have finished entering all of the required information, click Run. When the command completes, you can click View Results to see what happened. The results may initially only show a status, response code, start and finish time, etc. for the command. If you need more detailed information, you can get it by clicking on the View Output button. This will show you the actual command output. Remember that only the first 2500 characters of output are displayed. If the output is truncated then you can always use your S3 bucket to view the full output.
Conclusion
The Amazon Run Command feature gives you the ability to run PowerShell cmdlets and Shell Scripts against Amazon EC2 instances. Although the interface used for doing so may not be immediately intuitive, Amazon does make it relatively easy to enter commands and view the results.
