Amazon EC2 Run Command Components and Concepts
As you get started with Amazon EC2 Run Command, you'll benefit from understanding the components and concepts of this feature.
| Component/Concept | Details |
|---|---|
| Amazon EC2 Simple Systems Manager (SSM) | Run Command is a component of SSM. Run Command uses the SSM API. For more information, see Amazon EC2 Simple Systems Manager API Reference. |
| Servers and VMs in Your Hybrid Environment | Amazon EC2 Run Command lets you remotely and securely manage on-premises servers and virtual machines (VMs) and VMs from other cloud providers. By setting up Run Command in this way, you create a consistent and secure way to remotely manage your on-premises and cloud workloads using the same tools or scripts. After you configure a server or VM in your hybrid environment for Run Command it is called a managed instance and is listed in the EC2 console like your other EC2 instances. For more information, see Setting Up Run Command in Hybrid Environments. |
| Commands | You can configure managed instances by sending commands from your local machine. You don't need to log on locally to configure your machines. You can send commands using one of the following: the Command History page of the Amazon EC2 console, AWS Tools for Windows PowerShell, the AWS Command Line Interface (AWS CLI), the SSM API, or Amazon SDKs. For more information, see SSM AWS Tools for Windows PowerShell Reference, SSM AWS CLI Reference, and the AWS SDKs. |
| SSM Documents | An SSM document defines the plugins to run and the parameters to use when a command executes on a machine. When you execute a command, you specify the SSM document that Run Command uses. Run Command includes pre-defined documents that enable you to quickly perform common tasks on a machine. You can also create your own SSM documents. The first time you execute a command from a new SSM document, the system stores the document with your AWS account. For more information, see Creating SSM Documents. |
| SSM Agent | The SSM agent is AWS software that you install on your EC2 instances and servers and VMs in your hybrid environment. The agent processes Run Command requests and configures your machine as specified in the request. For more information, see Installing the SSM Agent. |
| IAM Roles and Polices | AWS user accounts and instances must be configured with AWS Identity and Access Management (IAM) roles and trust policies that enable them to communicate with the SSM API. For more information, see Delegating Access to Amazon EC2 Run Command. |
How It Works
After you verify prerequisites for your instances, you send a command from your local machine. The SSM service verifies the integrity of the command and any parameters and then forwards the request to the Amazon EC2 messaging service. The SSM agent running each instance (or EC2Config service on EC2 Windows instances) communicates with the EC2 messaging service to retrieve commands. The agent processes the command, configures the instance as specified, and logs the output and results.
Note
The agent attempts to execute each command once. You can send multiple commands at the same time.
The system manages the queuing, execution, cancellation, and reporting of each command. However, the order of command execution is not guaranteed. By default, Run Command uses throttle limits to ensure that no more than 60 commands are issued per minute per instance. If an instance is not running or is unresponsive when you execute a command, the system queues the command and attempts to run it when the instance is responsive. By default, the system will queue a command and attempt to run it for up to 31 days after request. For more information about command status, see Monitoring Commands.
Run Command reports the status and results of each command for each instance, server, or VM. Run Command stores the command history for 30 days. The information is also stored in AWS CloudTrail and remains available until you delete the data. For more information, see Auditing API Calls in the Amazon EC2 Simple Systems Manager API Reference.
More about SSM Documents
After you configure Run Command prerequisites, you determine what type of configuration change you want to make on your instance and which SSM document will enable you to make that change. Run Command includes pre-defined SSM documents that enable you to quickly execute commands on instances. The commands available to you depend on the permissions your administrator specified for you. Any command that begins with AWS-* uses a pre-defined SSM document provided by AWS. A developer or administrator can create additional documents and provision these for you based on your permissions. For more information, see Creating SSM Documents.
Important
Only trusted administrators should be allowed to use AWS pre-configured documents. The commands or scripts specified in SSM documents run with administrative privilege on your instances because the Amazon SSM agent runs as root. If a user has permission to execute any of the pre-defined SSM documents (any document that begins with AWS-*), then that user also has administrator access to the instance. For all other users, you should create restrictive documents and share them with specific users. For more information about restricting access to Run Command, see Delegating Access to Amazon EC2 Run Command.
Run Command includes the following pre-configured SSM documents.
Amazon Pre-configured SSM documents for Linux
| Name | Description |
|---|---|
|
AWS-RunShellScript |
Run shell scripts |
|
AWS-UpdateSSMAgent |
Update the Amazon SSM agent |
You can select a document from a list in the Amazon EC2 console or use a list documents command to view a
list a commands available to you in either the AWS CLI or AWS Tools for Windows PowerShell.
