Amazon EC2 InstanceManager Extension User Guide Version 1. · 2018-12-18 · Amazon EC2 Instance Manager Extension User Guide 3 3. Go to Import/Export > Import. 4. Click Choose File

Amazon EC2 Instance Manager Extension User Guide Version 1.

Amazon EC2 Instance Manager Extension User Guide

1

Software Change Log ................................................................................................................... 2 Introduction and Installation .......................................................................................................... 2

About the Amazon EC2 Instance Manager Extension ................................................................ 2

The EC2 Instance Manager allows you to connect your AWS account to ThingWorx, for the purposes of managing (launching, terminating, starting, stopping, and getting images) EC2 instances directly through the ThingWorx Platform ................................................................................................................. 2 The Amazon EC2 Instance Manager Extension allows you to create an EC2Instance Thing in ThingWorx. The Thing houses the configuration information to a configured AWS console, and provides various services for managing the EC2 instances in your console. ............................................................. 2

Installing the Amazon EC2 Instance Manager Extension ........................................................... 2

Configuration and Usage ............................................................................................................... 4

Configuration ............................................................................................................................. 4 Usage ........................................................................................................................................ 6

Troubleshooting .......................................................................................................................... 10 Compatibility ............................................................................................................................... 11 Document Revision History ......................................................................................................... 11


2

Software Change Log

Version Release Date Changes

1.0 11/13/2015 Initial Release

Introduction and Installation Extensibility is a core aspect of the architecture and design of ThingWorx. Partners, third parties, and users, as well as ThingWorx can easily add new functionality into the system in a seamless manner. Extensions can be Service (function/method) libraries, Connector Templates, Widgets, and more. This document provides installation and usage instructions for the Amazon EC2 Instance Manager Extension, created by ThingWorx.

Note that use of this extension requires an active Amazon AWS account with the ability to create EC2 instances. For more information, refer to https://aws.amazon.com to get started with your account.

About the Amazon EC2 Instance Manager Extension The EC2 Instance Manager allows you to connect your AWS account to ThingWorx, for the purposes of managing (launching, terminating, starting, stopping, and getting images) EC2 instances directly through the ThingWorx Platform. The Amazon EC2 Instance Manager Extension allows you to create an EC2Instance Thing in ThingWorx. The Thing houses the configuration information to a configured AWS console, and provides various services for managing the EC2 instances in your console.

Installing the Amazon EC2 Instance Manager Extension

1. From a web browser, launch ThingWorx.

2. Log into ThingWorx as an administrator.


3

3. Go to Import/Export > Import.

4. Click Choose File and select “AmazonEC2InstanceManager_Ext ension.zip”

5. Click Import.

Note: If an Import Successful message does not display, contact your ThingWorx System Administrator.

6. Click Yes to refresh Composer after importing the final extension.


4

Configuration and Usage Usage of the Amazon EC2 Instance Manager Extension requires the creation and configuration of an AmazonEC2 Thing in ThingWorx. This extension provides an “AmazonEC2Template” Thing Template, which should be used to create EC2 Instance Manager “Things”. The AmazonEC2Console Thing Shape provides the following services to inherited entities for managing the instances on a given AWS account:

• CreateImage

• EstablishAuthorization

• GetImages

• GetInstances

• LaunchImage

• LaunchInstance

• PopulateZones

• StartInstances

• StopInstances

• TerminateInstances

These services are explained in greater detail in the Usage section.

Configuration Once an Amazon EC2 Thing has been created from the AmazonEC2Template, it must be configured to connect to an AWS EC2 account console.

• Within the ThingWorx Composer, open up your newly-created AmazonEC2 Thing • Navigate to the Configuration section


5

• Under the connection settings, enter valid information for each of the connection parameters.

To obtain your AccessKey and SecretKey, you’ll need to navigate to the Security Credentials section of your AWS account console. This page will have a url similar to the following (use your instance region): https://console.aws.amazon.com/iam/home?region=us-east-1#security_credential

Here, look for the “Create New Access Key” button, under the Access Keys (Access Key ID and Secret Access Key) section, and click it to obtain a new set of access keys.

After clicking the button, you should get a pop-up notification that your access keys have been created. You may copy and paste the keys, or download a “Key File” for storing them locally first.


6

Now, return to your Amazon EC2 Thing, and on the Configuration page, edit the “SecretKey” and “AccessKey” to reflect your information. You may make the “regionLimit” field equal to the maximum number of instances you would want active on your account at any given time. This parameter will set a limit for the number of instances that may be started by this extension. If you were to meet or exceed this limit, the extension would not terminate an instance, but it would instead prevent any more from being activated. Set this to a low number, such as 5 (or another number to suit your preference).

Usage The Amazon EC2 Instance Manager Extension can be used by invoking any one of the following services:

• CloneInstance: Clones an existing EC2 Instance

• CreateImage: Creates a new disk image from the selected instance.

• EstablishAuthorization: Obtains configuration data. Access key and secret key are important parameters to obtain authorization to a user's EC2 instance. Region limit sets a limit to the number of total instances that can run in each region.

• GetImages: Retrieves an InfoTable of all images in a given region.

• GetInstanceInfo: Retrieves information about the given instance

• GetInstances: Returns an InfoTable list of all instances in a given region, along with their properties.

• GetInstanceTypes: Returns a list of all instance types supported by EC2

• GetKeyPairs: Returns key pairs defined for the specified region

• LaunchImage: Launches an instance from the selected image.

• LaunchInstance: Launches a selected instance. Returns true if the selected instance was successfully launched.


7

• PopulateZones: Returns an InfoTable list of aws zones and regions.

• StartInstance: Starts the selected instance. This will not launch a new instance.

• StartInstances: Starts the selected instances. This will not launch a new instance.

• StopInstance: Stops the selected instance, but does not terminate it.

• StopInstances: Stops the selected instances, but does not terminate them.

• TerminateInstance: Terminates the selected instance.

• TerminateInstances: Terminates the selected instance(s). Returns true if at least one instance was successfully terminated.

To begin, after configuring and saving your EC2Instance Thing, you should run the “EstablishAuthorization” service to confirm a proper connection to the AWS cloud under your account. If the service resolves successfully, it will return a value of “True”. You may run this service by using the “Test” button next to the service on your EC2Instance Thing (see below).

You may use the extension by running any of the services available to you via either the Test button, another service or subscription, or a mashup.


8

A test console mashup, named ConsoleMashup, is included in this extension. It will have imported along with the other entities in this Extension. In order to use this Mashup, you’ll need to connect your Test Thing to the Mashup’s “Entity” property. You’ll also need to set the ConsoleMashup as the “Home Mashup” on your Thing. Set that property on the “General Information” section of your Thing.

Save the entity. Next, open the AWSConsoleMashup for editing. Next, click on the “Workspace” tab on the left, and then click on the “Mashup” entity (should be at the very top of the tree).

Following this, click on the “Entity” property in the Mashup Properties at the lower-left side of the screen.


9

Here, choose your EC2Instance Thing that you have configured to connect to your AWS console. Save the Mashup, and then view it to test its functionality.

You may use the extension by calling any of these services; either via testing, or through the provided test mashup. It is important that the configuration of your Thing is set up with the proper credentials.

You can verify the operation of the services by confirming a change on your AWS console. Starting/Stopping/Terminating and getting images will take time, but the change should be reflected immediately, with a “pending” status, as follows:


10

Created Images will appear with the name given as input under the “AMIs” section of the Amazon Console, after a short delay. Be sure to select an instance and enter a valid name before clicking “Create Image”, or the service will fail.

For more help getting the extension to work, refer to the troubleshooting section of this document.

Troubleshooting

Problem Solution My entity and services cannot connect to my Amazon AWS console, or they will not run.

1. The first thing to verify is that your accesskey and secretkey are correct. If they are, and they still do not work, create a new key, and then change the configuration on your thing.

2. Verify that the accessKey and secretKey are also root keys. If they do not have root access, they will not allow a connection with this Extension.

3. If you are trying to get a list of instances, verify that you are doing so for a region which does in fact have instances on it. Otherwise, the service will return null.

The “GetInstances” service returns an error, and does not execute.

1. Check the ThingWorx Script and Application logs (from the Composer, they are in the top-right under the “Monitoring” drop-down) to narrow down a solution to your problem.

2. Verify that you are using ThingWorx version 6.5.0 or later.

3. Verify that your configuration is correct. Stopped instances will not start. 1. Check to make sure that your

“regionLimit” (in the configuration section) is not reached. Try increasing this number, and then try again.

2. Check the Script Logs for further assistance in diagnosing your issue.


11

The Mashup does not show any regions from the drop-down box to select a region, even though I have verified that my Extension is connected to AWS.

1. Try viewing the mashup through the “Home Mashup” option connected to your Thing:

2. Ensure that the Mashup is configured

with your appropriate entity selected under the “Entity” property (refer to page 8 of this guide).

3. Check the Script and Application logs.

Compatibility This guide has been tested for compatibility with the following ThingWorx platform and operating system:

ThingWorx Platform Version ThingWorx 6.6.0

OS Windows 7, Service Pack 1

Document Revision History

Revision Date Version Description of Change December 22, 2015 1.0 Initial Release

Documents

Amazon EC2 InstanceManager Extension User Guide Version 1. · 2018-12-18 · Amazon EC2 Instance Manager Extension User Guide 3 3. Go to Import/Export > Import. 4. Click Choose File