Skip to main content

EC2 Library

The EC2 Library is an importable library you can use in your projects to interact with the AWS CLI EC2 API to setup and manage your instances. This library is used by the EC2 AWS CLI Adapter.

There are additional methods which can be added to the client - checkout the AWS CLI EC2 API docs for all the available methods.

When importing into your project, only the client needs to be required in order to set up the client and access the various methods.

require "EC2.EC2client"

How it works:​

Use the Translator's built in help to review how to use each function:

EC2client creates the adapter framework using a metatable

EC2client creates the EC2 AWS CLI adapter framework.

EC2 modules are defined in a metatable as methods and set to the S object. The instance details passed to EC2client are assigned to the new S table to be used by the methods.

local MT={}   
   
MT.__index = {}   
MT.__index.allocateIp       = require ’EC2.EC2allocateIp’   
MT.__index.associateIp      = require ’EC2.EC2associateIP’   
MT.__index.runInstance      = require ’EC2.EC2runInstance’   
MT.__index.describeInstance = require ’EC2.EC2describeInstance’   
MT.__index.custom           = require ’EC2.EC2custom’   
MT.__index.startInstance    = require ’EC2.EC2startInstance’   
MT.__index.stopInstance     = require ’EC2.EC2stopInstance’   
   
help.map{dir=’EC2/help’,methods=MT.__index}   
   
function EC2client(T)   
   S= {}   
   setmetatable(S, MT)   
   S.instance   = T.instance   
   S.ip         = T.ip   
   S.out        = T.out   
   S.params     = T.params   
   S.result     = T.result   
   S.notify     = T.notify   
   return S   
end

Concepts used:

EC2custom takes in any parameters to form and execute an AWS CLI command

EC2custom is a helper function designed to form and execute AWS CLI commands .

EC2custom is passed the command and parameters prepared by the EC2 method functions. The passed parameter values are strung together to be appended to the command.

The command is executed and results are written to the “resultsout” directory defined in the custom fields.

local function concatenateParams(C)   
   local p = ’ ’   
   for k, v in pairs(C.params) do   
      p = p..’ ’..v   
   end   
  return p   
end   
   
local function EC2custom(T, C)   
   if C.params then   
      T.params = concatenateParams(C)   
      C.command = C.command..’ ’..T.params   
   end   
   local P = io.popen(C.command..’ > ’..T.out, "w")   
   P:close()   
end   
   
return EC2custom

Concepts used:

EC2allocateIp prepares the command and parameters to execute an IP allocation

EC2allocateIp specifies the required command for AWS CLI and passes the command to EC2custom to execute.

The newly allocated IP address is read from the results directory and the cleanupEnv() function is called to reset the client parameters and remove the file from the shared results directory, for the other results to write to.

local function cleanupEnv(T)   
   os.remove(T.out)   
   T.params = nil   
end   
   
local function EC2allocateIp(T)   
   local C   = {}   
   C.command = ’aws ec2 allocate–address’   
   
   T:custom(C)   
   T.ip = FILread(T.out) or nil   
   cleanupEnv(T)   
end   
   
return EC2allocateIp

Concepts used:

EC2runInstance spins up and starts an AWS EC2 instance using a launch template

EC2runInstance is passed the client object T and arguments required to execute the command. It requires a launch template ID to spin up a new EC2 instance.

Before calling EC2custom to execute the command, EC2runInstance performs a series of tasks to prepare the command and parameters:

  1. validateParams() - Validates the input parameters by checking if a table of input parameters exists, getting the launch template from the arguments or custom fields and checking for an input name, setting a default if not provided.

  2. ts() - prepares an instance tag command using the provided iName and checks to append the CNAME to the tag if the iCname parameter was given.

Once all the parameters are prepared, they are added to the command table, C, to be passed to EC2custom.

The instance name is read from the results directory and the cleanupEnv() function is called to reset the client parameters and remove the file from the shared results directory, for the other results to write to.

local function cleanupEnv(T)   
   os.remove(T.out)   
   T.params = nil   
end   
   
local tsName  = ’--tag–specifications "ResourceType=instance,Tags=[{Key=Name,Value=’   
local tsCname = ’},{Key=CName,Value=’   
   
local function ts(C, iName, iCname)   
   C.params.tagSpecifications = tsName..iName   
   if iCname then   
      C.params.tagSpecifications = C.params.tagSpecifications..tsCname..iCname   
   end   
   return C.params.tagSpecifications..’}]"’   
end   
   
local function validateParams(args)   
   if not args or type(args) ~= ’table’ then   
      return   
   end   
   args.launchTemplate = args.launchTemplate or component.fields().ltemplate   
   if not args.launchTemplate then   
      return   
   end   
   args.iName = args.iName or ’H_’..tostring(os.time())   
   return args   
end   
   
local function EC2runInstance(T, args)   
   args = validateParams(args)   
   if not args then   
      return   
   end   
   args.launchTemplate = args.launchTemplate or component.fields().ltemplate   
   args.iName          = args.iName or ’H_’..tostring(os.time())   
   local C                    = {}   
   C.command                  = ’aws ec2 run–instances’   
   C.params                   = {}   
   C.params.launchTemplate    = ’ --launch–template LaunchTemplateId=’..args.launchTemplate   
   C.params.tagSpecifications = ts(C, args.iName, args.iCname)   
   
   T:custom(C)   
   T.instance = FILread(T.out) or nil   
   cleanupEnv(T)   
end   
   
return EC2runInstance

Concepts used:

EC2describeInstance gets a detailed JSON string describing a list of instances

EC2describeInstance is passed the client object T and arguments required to execute the command.

EC2describeInstance requires a single or list of instance IDs to query for instance details. It first, checks if the required input instance ID parameter is provided and then specifies the required command for AWS CLI for EC2custom to execute.

The instance detail JSON response is read from the results directory and the cleanupEnv() function is called to reset the client parameters and remove the file from the shared results directory, for the other results to write to.

local function cleanupEnv(T)   
   os.remove(T.out)   
   T.params = nil   
end   
   
local function EC2describeInstance(T, instanceId)   
   if not instanceId then   
      return   
   end   
   local C             = {}   
   C.command           = ’aws ec2 describe–instances’   
   C.params            = {}   
   C.params.instanceId = ’ --instance–ids’..’ ’..instanceId   
   
   T:custom(C)   
   T.instance = FILread(T.out) or nil   
   cleanupEnv(T)   
end   
   
return EC2describeInstance

Concepts used:

EC2associateIp associates an Elastic IP with an EC2 instance

EC2associateIp specifies the required command for AWS CLI and passes the command to EC2custom to execute.

The instance is read from the results directory and the cleanupEnv() function is called to reset the client parameters and remove the file from the shared results directory, for the other results to write to.

local function cleanupEnv(T)   
   os.remove(T.out)   
   T.params = nil   
end   
   
local function EC2associateIP(T, args)   
   local C               = {}   
   C.command             = ’aws ec2 associate–address’   
   C.params              = {}   
   C.params.instanceId   = ’ --instance–id’..’ ’..args.InstanceId   
   C.params.allocationId = ’ --allocation–id’..’ ’..args.AllocationId   
   
   T:custom(C)   
   T.instance = FILread(T.out) or nil   
   cleanupEnv(T)   
end   
   
return EC2associateIP

Concepts used:

EC2startInstance starts an EC2 instance that has previously been stopped

EC2startInstance checks for a passed instance ID and specifies the required command for AWS CLI to be passed to EC2custom to execute.

The instance is read from the results directory and the cleanupEnv() function is called to reset the client parameters and remove the file from the shared results directory, for the other results to write to.

local function cleanupEnv(T)   
   os.remove(T.out)   
   T.params = nil   
end   
   
local function EC2startInstance(T, instanceId)   
   if not instanceId then   
      return   
   end   
   local C             = {}   
   C.command           = ’aws ec2 start–instances’   
   C.params            = {}   
   C.params.instanceId = ’ --instance–ids’..’ ’..instanceId   
   
   T:custom(C)   
   T.instance = FILread(T.out) or nil   
   cleanupEnv(T)   
end   
   
return EC2startInstance

Concepts used:

EC2stopInstance stops an EC2 instance that is running

EC2stopInstance checks for a passed instance ID and specifies the required command for AWS CLI to be passed to EC2custom to execute.

The instance is read from the results directory and the cleanupEnv() function is called to reset the client parameters and remove the file from the shared results directory, for the other results to write to.

local function cleanupEnv(T)   
   os.remove(T.out)   
   T.params = nil   
end   
   
local function EC2stopInstance(T, instanceId)   
   if not instanceId then   
      return   
   end   
   local C             = {}   
   C.command           = ’aws ec2 stop–instances’   
   C.params            = {}   
   C.params.instanceId = ’ --instance–ids’..’ ’..instanceId   
   
   T:custom(C)   
   T.instance = FILread(T.out) or nil   
   cleanupEnv(T)   
end   
   
return EC2stopInstance

Concepts used: