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 Systems Manager (Systems Manager) | Run Command is a component of Systems Manager. Run Command uses the Systems Manager API. For more information, see Amazon EC2 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 Systems Manager 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 instances. You can send commands using one of the following: the Amazon EC2 console, AWS Tools for Windows PowerShell, the AWS Command Line Interface (AWS CLI), the Systems Manager API, or Amazon SDKs. For more information, see Systems Manager AWS Tools for Windows PowerShell Reference, Systems Manager AWS CLI Reference, and the AWS SDKs. |
| Systems Manager Documents | A Systems Manager 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 Systems Manager 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 Systems Manager documents. The first time you execute a command from a new Systems Manager document, the system stores the document with your AWS account. For more information, see Creating Systems Manager 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 Systems Manager API. For more information, see Configuring Access to Systems Manager. |
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.
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 Command Status and Monitoring.
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 Systems Manager API Reference.
More about Systems Manager Documents
After you configure Run Command prerequisites, you determine what type of configuration change you want to make on your instance and which Systems Manager document will enable you to make that change. Run Command includes pre-defined Systems Manager 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 Systems Manager 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 Systems Manager Documents.
Important
Only trusted administrators should be allowed to use Systems Manager pre-configured documents shown in this topic. The commands or scripts specified in Systems Manager documents run with administrative privilege on your instances. If a user has permission to execute any of the pre-defined Systems Manager 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 Configuring Access to Systems Manager.
Run Command includes the following pre-configured Systems Manager 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.
