EC2 AWS CLI Adapter

Need some help? Contact us:

The EC2 AWS CLI adapter is a simple component which can be used to automate EC2 interactions such as managing IPs, getting EC2 instance descriptions and running instances. We use it ourselves to streamline deploying our EC2 instances.

This component assumes you have an AWS EC2 Instance Launch Template setup to use. If you don’t have one, you can follow the AWS instructions to create a Launch Template.

Follow the steps below to set it up this component in your IguanaX environment:

You will need to install IguanaX and AWS CLI on your machine

Refer to our documentation IguanaX Installation and AWS CLI if you have not installed them.

Use +FROM URL to import the EC2 AWS CLI Adapter

You can use this url:

git@bitbucket.org:interfaceware/ec2awscli.git

This adapter is built as a Library, so you can also create your own component and simply import the EC2 Library into your project. See Import Library.

Review and update the Custom Fields to your configurations

There are two custom fields to set:

ltemplate: AWS EC2 Instance Launch Template ID (ex. lt-0123456789abcdef0) will be used to programmatically run an EC2 instance. You can find this value in your AWS Console > Services > EC2 > Instance > Launch Templates.
resultsout: File directory location to store temporary result files. You can leave this as is or change to a directory of your choice.

These are a component’s Custom Fields.

Under IMPLEMENTATION, click Edit, Make a Copy and Edit to enter the Translator and see it in action!

In main.lua, update the functions and try out the different EC2 methods by uncommenting the sample function calls. Continue on reading this doc for examples of each method.

Try Allocating an Elastic IP

Uncomment sampleAllocateIp() and see the results in your AWS Console. Go to EC2 > Network & Security > Elastic IPs.

Note the Allocation ID value. We’ll use this later when we associate this IP.

Run a new EC2 instance using a launch template

Go to the sampleRunInstance function and replace the parameters with your launchTemplate ID, Name and optional CNAME. Uncomment sampleRunInstance() to launch a new instance using your launch template.

You can also access your launchTemplate ID in your custom fields!

See the results in your AWS Console in EC2 > Instances. Copy the Instance ID for the next call.

Get EC2 instance details using describeInstance

In sampleDescribeInstance(), replace the Instance ID with your value and uncomment sampleDescribeInstance() in main to run the function. With this command, you can retrieve details of one or more instances by providing a list of Instance IDs

The result will look something like this sample:

{
    “Reservations”: [
        {
            “Groups”: [],
            “Instances”: [
                {
                    “AmiLaunchIndex”: 0,
                    “ImageId”: “ami-00903e1945998682a”,
                    “InstanceId”: “i-0c3eeb68afc0672c6",
                    “InstanceType”: “t2.micro”,
                    “KeyName”: “mykey”,
                    “LaunchTime”: “2023-12-17T19:50:10+00:00",
                    “Monitoring”: {
                        “State”: “disabled”
                    },
                    “Placement”: {
                        “AvailabilityZone”: “us-east-1”,
                        “GroupName”: “”,
                        “Tenancy”: “default”
                    },
                    “PrivateDnsName”: “ip-172-31-36-128.ec2.internal”,
                    “PrivateIpAddress”: “172.31.36.128",
                    “ProductCodes”: [],
                    “PublicDnsName”: “ec2-52-207-82-96.compute-1.amazonaws.com”,
                    “PublicIpAddress”: “52.207.82.96”,
.
.
.

Now associate your IP address with your EC2 instance

Paste in your InstanceID and AllocationID from the Elastic IP we created earlier. Uncomment sampleAssociateIp() in main to run the function.

See the results in your AWS Console in EC2 > Instances.

Stop and Start your EC2 instance

Finally, use the sampleStopInstance() and sampleStartInstance() functions to change the instance state by changing the Instance ID parameter. See the instance state change in your AWS Console in EC2 > Instances.

This adapter can easily be extended by your team to meet your workflow needs by adding new method functions. You can reference the AWS CLI EC2 API documentation.

Take a look at How the EC2 AWS CLI Adapter works if you want more information on the core concepts used in building and adapting this component.