How to use AWS SSM Session Manager Plugin

Tom Lei — Fri, 14 Jan 2022 07:12:45 +0000

AWS System Manager Session Manager has been an awesome tool and in our organization we have quickly adopted AWS System Manager Session Manager in-lieu of bastion host.

However, if you ever tried to use the StartSession API for AWS SSM on any of the AWS SDKs, you will soon find out that the SDK calls will return you something like this:

{
    "SessionId": "John-Doe-0dc5b7af96EXAMPLE",
    "StreamUrl": "wss://ssmmessages.us-east-2.amazonaws.com/v1/data-channel/John-Doe-0dc5b7af96EXAMPLE?role=publish_subscribe",
    "TokenValue": "a3f5ff34-9bc4-4d2c-a665-4d1c1EXAMPLE/39c3b3042cd2aEXAMPLE"
}

It's then left to the user to use the StreamUrl and TokenValue to establish a shell session themselves, there are various attempts to consume this response such as this one where it uses the xterm npm package to establish a session in html.

Another way to consume this response, which we will explore here today, is to use the AWS SSM Sesison Manager plugin.

In the AWS documentation, there is an optional step to install the AWS SSM Sesison Manager plugin, however, there isn't much documentation on what it does or how to use it.

It turned out that this plugin is actually an open source project on GitHub, and this tool is used to power the start-session AWS CLI command to establish shell session. The exact way to use it undocumentated, but one can check AWS CLI's source code to see and example on how to use it.

So here is the exact way to use session manager plugin to start a session, in this example, we will use the AWS NodeJS SDK V3 and TypeScript.

import { SSMClient, StartSessionCommand, StartSessionCommandInput } from "@aws-sdk/client-ssm";
import {spawn} from 'child_process'


const region = 'us-east-1';
const ec2InstanceId = 'i-123456';
const ssmDocumentName = 'custom-ssm-document-name';

/**
*  Send start-session API call and store the response
**/
const ssmClient = new SSMClient();
const startSessionParams : StartSessionCommandInput = { 
    Target: ec2InstanceId,
    DocumentName: ssmDocumentName,
}; 
const startSessionCommand = new StartSessionCommand(startSessionParams);
const startSessionResp = await ssmClient.send(startSessionCommand);


const ssmPluginArgs : string[] = [ 
    JSON.stringify(startSessionResp),
    region,
    'StartSession',
    '', // AWS CLI profile name goes here
    JSON.stringify(startSessionParams), 
    `https://ssm.${region}.amazonaws.com`
];

process.stdin.pause(); // pause stdin for the child process
const child = spawn('session-manager-plugin', ssmPluginArgs, {stdio: 'inherit'});

child.on('exit', function () {
    process.stdin.resume();
});

To illustrate this command in bash:
session-manager-plugin <start-session-response-in-json> <region> StartSession <cli-profile-name> <start-session-parameters-in-json> <ssm-endpoint>

and then it will start the shell session using the connection established by the StartSession API call.

As a caution for anyone trying to integrate this command into your own application, make sure to intercept the SIGINT signal inside your application because being able to use Ctrl + C to stop an application in your server's session is defintely nice to have.

PHP For The Impatient

Tom Lei — Fri, 25 Sep 2020 04:04:43 +0000

We are primarily a PHP shop for about half of the engineering team here at Beanworks. PHP tends to have a bad reputation out there, but with PHP 7 (and potentially PHP 8), it's really becoming a mature and powerful language while keeping its simplicity.

I always tell new engineers with no prior PHP experience that if you're able to write code in any language, you will be able to learn PHP pretty quickly.

In this article we will explore some PHP syntax and compare it to Javascript or Typescript.

I have added 🔁 icon to the ones that have identical syntax.

Basic Syntax

Variables

In PHP land, all variables have to start with a dollar sign $

PHP

$foo = 'bar';

NodeJS

let foo = 'bar';

Template Literals

You can use variables in strings as long as the string is wrapped with double quote ("), strings wrapped with single quotes will not evaluate the variables.

PHP

$str = "My name is {$name}"

NodeJs

let str = `My name is ${name}`

Constants 🔁

PHP has real constants, they must be capitalized, but otherwise the syntax is actually the same

PHP

const FOO = 'bar';

NodeJS

const FOO = 'bar';

Arrays

PHP

$arr = ['a', 'b'];

// you can iterate using foreach
foreach ($arr as $element) {
  ...
}

NodeJS

let arr = ['a', 'b'];

// you can iterate using for ... of
for (let element of arr) {
  ...
}

Objects

In PHP land, objects are just arrays, associative arrays. Instead of using :, you need to use a double arrow =>

PHP

$myFavouriteVehicles = [
  'Toyota' => ['4Runner','Tacoma'],
  'Ford' => ['Bronco']
];

$fordVehicles = $myFavouriteVehicles['Ford'];

// you can iterate key => value using foreach
foreach ($myFavouriteVehicles as $brand => $vehicles) {
   ...
}

Javascript

let myFavouriteVehicles = {
  'Toyota': ['4Runner','Tacoma'],
  'Ford': ['Bronco']
}

let fordVehicles = myFavouriteVehicles['Bronco'];

// you can iterate key value with Object.entries
for (let [brand, vehicles] of Object.entries(myFavouriteVehicles)) {
  ...
}

Callback functions

In most of the PHP land, you still have to write call back functions like you had to in ES5 days, arrow function is only recently supported in PHP7.4

PHP 🔁

array_map(function($element) {...}, $arr);

// or in PHP 7.4+ you can use arrow function, no multi line though
array_map(fn($element) => ..., $arr)

NodeJS

arr.map(function (element) {...});

// Arrow function since ES6
arr.map(element => ...);

Classes & Inheritance

PHP's uses the same syntax extending classes and interfaces

PHP 🔁

class Foo extends Bar implements FooBarInterface

Typescript

class Foo extends Bar implements FooBarInterface

Type system

Contrary to popular beliefs, PHP does have a type system that works similar to other OOP languages, and with each new version of PHP, the type system is getting better.

PHP

public function writeLine (string content, LineWriter $writer) : string {
    return content;
}

Typescript

public writeLine( content : string, lineWriter lineWriter) : string {
    return content;
}

Invoke Methods

To invoke a method, you need to use -> instead of a dot in PHP.

PHP

$logger->log('PHP uses ->');

NodeJs

logger.log('Node uses .');

Generators 🔁

There is no special syntax in the function signature if you want to use the yield keyword

PHP

public function getLaptopBrands() : Iterator {
  yield 'Lenovo';
  yield 'Asus';
  yield 'Dell';
}

TypeScript

public function* getLaptopBrands() : IterableIterator<string> {
  yield 'Lenovo';
  yield 'Asus';
  yield 'Dell';
}

Yield from generator

In PHP you can use the yield from syntax to yield from a generator

PHP

public function getComputerBrands() : Iterator {
  yield from getLaptopBrands();
  yield from getDesktopBrands();
}

TypeScript

public function* getLaptopBrands() : IterableIterator<string> {
  yield* getLaptopBrands();
  yield* getDesktopBrands();
}

DEV Community: Tom Lei

How to use AWS SSM Session Manager Plugin

PHP For The Impatient

Basic Syntax

Variables

PHP

NodeJS

Template Literals

PHP

NodeJs

Constants 🔁

PHP

NodeJS

Arrays

PHP

NodeJS

Objects

PHP

Javascript

Callback functions

PHP 🔁

NodeJS

Classes & Inheritance

PHP 🔁

Typescript

Type system

PHP

Typescript

Invoke Methods

PHP

NodeJs

Generators 🔁

PHP

TypeScript

Yield from generator

PHP

TypeScript