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 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:

Meta tables
Setting up help for an object with methods using the MT.__index table of methods.
Using a table as a function argument

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:

Function scope
for in loop to concatenate parameters for the AWS CLI command
io.popen()
Closing File Connections

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.

Concepts used:

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:

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.
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.

Concepts used:

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.

Concepts used: