EC2 Library
Aryn Wiebe
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:
Setting up help for an object with methods using the MT.__index table of methods.
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 EC2customConcepts used:
for in loop to concatenate parameters for the AWS CLI command
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 EC2allocateIpConcepts 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.
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 EC2runInstanceConcepts 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.
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 EC2describeInstanceConcepts used:
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 EC2associateIPConcepts used:
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 EC2startInstanceConcepts used:
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 EC2stopInstanceConcepts used: