@fnet/aws-ssm-commander

This project is designed to streamline command execution on AWS EC2 instances using AWS Systems Manager (SSM). It allows users to either send a command to a specific instance or find the instance via a CloudFormation stack output, simplifying the process of managing EC2 resources directly from the command line.

How It Works

Simply put, the project verifies your AWS identity, identifies the target EC2 instance either directly or through CloudFormation, and executes the specified command on the instance via the SSM service. The tool waits for the command to execute and then returns the result, making the task of remote management straightforward.

Key Features

• AWS Identity Verification: Confirms and logs the user's AWS account information.
• Instance Identification: Retrieves the EC2 instance ID from AWS CloudFormation stack outputs if not provided directly.
• Command Execution: Uses AWS SSM to run commands on your EC2 instances.
• Polling for Results: Regularly checks and retrieves the command execution results.

Conclusion

The @fnet/aws-ssm-commander is a simple, effective way to manage and execute commands on AWS EC2 instances without the need for direct SSH access. By leveraging CloudFormation and SSM, it provides a flexible approach to managing AWS resources, particularly useful for those looking to automate tasks or manage instances programmatically.

Developer Guide for @fnet/aws-ssm-commander

Overview

The @fnet/aws-ssm-commander library provides a convenient way for developers to execute shell commands on AWS EC2 instances via AWS Systems Manager (SSM). This can be particularly useful for automation tasks, configuration management, and managing instances remotely without direct SSH access. The library abstracts the complexity of retrieving instance information from CloudFormation and executing commands through SSM.

Installation

To install the @fnet/aws-ssm-commander library, use either npm or yarn:

npm install @fnet/aws-ssm-commander

or

yarn add @fnet/aws-ssm-commander

Usage

The library exports a single asynchronous function, making it straightforward to use. You'll need to provide AWS credentials and permissions that allow access to STS, SSM, and optionally CloudFormation, depending on your use case.

Below is a step-by-step example of how to use the library to execute a command on an EC2 instance:

Examples

Executing a Command on an EC2 Instance

Suppose you want to run a shell command on an EC2 instance identified by a CloudFormation stack output. Here's how you can achieve that:

import executeSSMCommand from '@fnet/aws-ssm-commander';

(async () => {
  try {
    const output = await executeSSMCommand({
      stackName: 'my-cloudformation-stack', // Name of your CloudFormation stack
      command: 'echo "Hello, World!"', // Command to run on the instance
      region: 'us-west-2', // AWS region
      verbose: true // Optional logging for visibility
    });

    console.log('Command Output:', output);
  } catch (error) {
    console.error('Error executing command:', error.message);
  }
})();

Directly Using an Instance ID

If you already know the instance ID and don't need to look it up from a CloudFormation stack, you can directly specify it:

import executeSSMCommand from '@fnet/aws-ssm-commander';

(async () => {
  try {
    const output = await executeSSMCommand({
      instanceId: 'i-0abcd1234efgh5678', // Direct EC2 instance ID
      command: ['uptime', 'df -h'], // Array of commands to run
      region: 'us-east-1' // AWS region
    });

    console.log('Command Outputs:', output);
  } catch (error) {
    console.error('Error executing command:', error.message);
  }
})();

Acknowledgement

This library is powered by AWS SDK clients for STS, SSM, and CloudFormation, making it essential to ensure that AWS permissions are correctly configured for these services.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  env:
    type: object
    description: AWS credentials configuration.
    oneOf:
      - properties:
          AWS_PROFILE:
            type: string
            description: AWS Profile Name.
        required:
          - AWS_PROFILE
      - properties:
          AWS_ACCESS_KEY_ID:
            type: string
            description: AWS Access Key ID.
          AWS_SECRET_ACCESS_KEY:
            type: string
            description: AWS Secret Access Key.
          AWS_SESSION_TOKEN:
            type: string
            description: AWS Session Token.
        required:
          - AWS_ACCESS_KEY_ID
          - AWS_SECRET_ACCESS_KEY
  instanceId:
    type: string
    description: The EC2 instance ID (if provided, skips CloudFormation lookup).
  stackName:
    type: string
    description: The name of the CloudFormation stack (used if instanceId is not provided).
  outputKey:
    type: string
    description: The CloudFormation output key to locate the InstanceID.
    default: InstanceID
  command:
    oneOf:
      - type: string
        description: A single command to execute on the EC2 instance.
      - type: array
        items:
          type: string
        description: An array of commands to execute on the EC2 instance.
  region:
    type: string
    description: The AWS region.
  parameters:
    type: array
    items:
      type: string
    description: Optional parameters for the command.
    default: []
  pollingInterval:
    type: number
    description: The interval in milliseconds to poll for command status.
    default: 5000
required:
  - command
  - region
allOf:
  - if:
      not:
        properties:
          instanceId:
            type: string
    then:
      required:
        - stackName