Skip to main content
Sign in

Creating an extended integration for AWS EC2 assets

Caroline Maguire
  • July 13, 2022 09:12
  • Updated

Let Oomnitza be your single source of truth!

You'll get complete visibility of your assets and users as data from AWS EC2 is automatically transformed into consumable information and actionable insights.

Connect Oomnitza and AWS EC2 in minutes

Get the information and insights that you need to reduce costs and the time that you spend on administration tasks such as:

  • Configurable dashboards and list views of key asset information
  • Configurable reports to share information about your assets with your colleagues and management
  • Configurable workflows that you can easily create to automate tasks such as:
    • Workflows for starting, stopping or rebooting EC2 instances
    • Workflows for getting details about EC2 instances
    • Workflows for creating, getting or deleting EC2 instance tags

Contents

  1. Adding the credentials
  2. Creating the asset integration
  3. Creating custom mappings
  4. Creating workflows
  5. Configuring AWS EC2 Presets
    1. Amazon AWS EC2 start EC2 instance
    2. Amazon AWS EC2 stop EC2 instance
    3. Amazon AWS EC2 reboot EC2 instance
    4. Amazon AWS get details of single EC2 instance
    5. Amazon AWS get instance status from EC2
    6. Amazon AWS create tag for EC2 instance
    7. Amazon AWS get tag from EC2 instance
    8. Amazon AWS delete tag from EC2 instance
    9. Amazon AWS get average CPU Load for an EC2 instance

About the integration

This integration pulls in the EC2 instances (running and stopped instances, but not terminated ones) from one AWS region into Oomnitza. In case you have multiple regions deployed with AWS, you need to create one integration per region. 

Adding the credentials

To add your AWS credentials to Oomnitza, see Adding your AWS credentials to Oomnitza.

Creating the asset integration

To configure the integration for the AWS EC2 Load, complete the following steps:

  1. In Oomnitza, click Configuration> Integrations.
  2. Click Integrations List View small_SettingsListView.svg.
  3. On the Integrations page, scroll down to the Extended section for Assets.
  4. Click NEW INTEGRATION.
  5. In the New Asset Integration sidebar, click Amazon AWS EC2 Asset Load.
  6. To integrate Oomnitza with the Amazon AWS EC2 Asset Load, click APPLY and then click NEXT twice.

On the connect page, complete the following steps to connect the integration:

  1. Enter a descriptive name for the integration such as AWS EC2 Assets. This name will be displayed on the Integrations page once the setup is complete.
  2. Select Cloud as the installation type.
  3. From the Credentials list, select the credentials from the Oomnitza vault that you added for the connection. For further information, refer to Adding AWS credentials.
  4. From the Integration Preferences list, select Create & Update. 
  5. Enter the name of the user of the integration.
  6. Enter the Region. For further information, refer to Regions, Availability Zones, and Local Zones. You can only specify one region per integration. To add another region, see Adding more regions to your integration
  7. Click Next.

Creating custom mappings

Map AWS EC2 fields to Oomnitza fields to get the user information that you need. For the field mapping, it is recommended to follow these steps:

  1. Hardcode the Oomnitza field Asset Type to Virtual Instance. To do this, click on the Asset Type field and select Virtual Instance in the dropdown list. 
  2. Hardcode the AWS Region since it is not part of the payload but will be required for the additional API block integrations mentioned in Creating workflows. You can do this by clicking in the AWS Region field and entering your region in the format mentioned in Regions, Availability Zones, and Local Zones.
  3. Map the AWS EC2 fields to Oomnitza fields and create custom mappings to map any other field that you want to add to Oomnitza. To create custom mappings do the following:
    1. Click the down arrow on the field that you want to map.
    2. Select Add new Oomnitza assets field.
    3. Change the name of the field.
    4. Click CREATE. 
  4. Map the Instance ID to the Oomnitza Serial Number field, or a similar field. Assign a sync key to the Serial Number field.
  5. Click NEXT. 

Tracking information for asset loads 

When the integration is run, you can track the name of the credentials that were used and the source of the data. To do this, you map the following fields to Oomnitza:   

  • Connect: Credentials
  • Connect: Region

Custom mappings

AMI Launch Index
Architecture
Availability Zone
CPU Core Count
Capacity Reservation Perference
DNS Name
EBS Optimized
ENA Support
Enclave Options Enabled
Hibernation Options Configured
Hypervisor
IP Address
Image ID
Instance ID
Instance Name
Instance State
Instance State Code
Instance Type
Key Name
Launch Time
Monitoring State
Owner ID
Placement Group Name
Private DNS Name
Private IP Address
Product Codes
Reason
Region
Reservation ID
Root Device Name

blue_link.svg Learn more about mapping

When you've completed mapping AWS EC2 fields to Oomnitza fields, click NEXT.   

Schedule

By default, data is streamed to Oomnitza once every day.

You can configure the schedule to meet your needs such as changing the interval or changing the time so that the data is streamed when your system isn't busy.

  1. Configure your schedule.
  2. Click FINISH.

Result

A new tile is created for the integration on the Integrations page. 

What to do next

If you want to see what information is collected now, click the tile on the Integrations page and click RUN NOW.

If you want to change the integration settings, you can click a navigation link on the page, such as 4 Mappings, and edit the settings.

edit-integration.svg 

Adding more regions to your integration

Once the integration is created, you can add more regions to your integration. To add another region, complete the following steps:

  1. In Oomnitza, click Configuration > Integrations.
  2. Click Integrations List View small_SettingsListView.svg.
  3. On the Integrations page, scroll down to the Extended section for Assets and select your integration.
  4. Click the plus sign on the AWS logo and repeat the steps to connect the integration.

Tip
To view the information that is collected about your mobile assets, click Assets. 

Creating workflows

To reduce your workload and automate complex and repetitive tasks, you can create workflows with the API block by following the steps in Creating asset workflows with the API block When creating the user workflows with the API block for AWS EC2, the following specific configuration is required:

Tip
This integration only provides you with a list of active assets (running and stopped EC2 instances), but not ones that have already been deleted. If you want to further reduce the list to only show instances that are recently active or in-use, you can create a workflow to archive items that have not been updated in a while.

For further information on workflows see:
small_blue_link.svg Understanding workflows
small_blue_link.svg Workflow block overview
small_blue_link.svg Configuring AWS EC2 Presets

Configuring AWS EC2 Presets

Amazon AWS EC2 start EC2 instance

This Amazon AWS EC2 Start EC2 instance preset allows you to start an existing EC2 instance. 

This preset requires the AWS fields Connect:Region and Instance ID to be mapped to the Oomnitza fields AWS Region and Serial Number, respectively.

If these fields are mapped differently in your implementation, you need to update your API workflow block to the correct Oomnitza fields. To do this, complete the following steps:

  1. In the API block window, click the Advanced Mode button located in the upper right of the window.
  2. Select the Information tab. Update the aws_region field to the field name in Oomnitza. The field name should be in lower case, and spaces replaced with an underscore, example new_aws_region.
  3. Select the Body tab. Update the serial_number field to the field name in Oomnitza. The field name should be in lower case, and spaces replaced with an underscore.

Amazon AWS EC2 stop EC2 instance

This Amazon AWS EC2 Stop EC2 instance preset allows you to stop an already existing EC2 instance. The mapping requirements mentioned in Amazon AWS EC2 Start EC2 instance also apply to this preset. 

Amazon AWS EC2 reboot EC2 instance

This Amazon AWS EC2 Reboot EC2 instance reboot preset allows you to reboot an already existing EC2 instance. The mapping requirements mentioned in Amazon AWS EC2 Start EC2 instance also apply to this preset. 

Amazon AWS get details of single EC2 instance

This Amazon AWS get details of single EC2 instance preset allows you to get the details of a single EC2 instance. As mentioned in Amazon AWS EC2 Start EC2 instance, you need to have the fields aws_region and serial_number defined within Oomnitza.

By using this preset, and updating the following in the Response section, you can get the values from the response and parse them to attributes of your Asset in Oomnitza. To do this, complete the following steps:

  1. In the API block window, click the Advanced Mode button located in the upper right of the window.
  2. Select the Response tab.
  3. Enter the below code snippet in the Response field.
{% set temp = response['DescribeInstancesResponse']['reservationSet']['item']['instancesSet']['item']['instanceState']['name'] %}{% if 'name' in temp %}{{[temp]}}{% else %}{{temp}}{% endif %}

The above response provides you with the status of the EC2 instance, such as Running or Stopped. When developing your own response mapping, it is a good idea to look at the complete response by parsing it into a long text attribute. In this way, finding the proper statement will be much easier.

Amazon AWS get instance status from EC2

The Amazon AWS get instance status from EC2 preset allows you to retrieve the status of your EC2 instances. By using this preset, and updating the following in the Response section, you can pull EC2 system status into the mapped field in Oomnitza. To do this, complete the following steps:

  1. In the API block window, click the Advanced Mode button located in the upper right of the window.
  2. Select the Response tab.
  3. Enter the below code snippet in the Response field.
{% if response['DescribeInstanceStatusResponse']['instanceStatusSet'] %} {% set instanceState = response['DescribeInstanceStatusResponse']['instanceStatusSet']['item']['instanceStatus']['status']%} {% set systemStatus = response['DescribeInstanceStatusResponse']['instanceStatusSet']['item']['systemStatus']['status']%} {% if instanceState == 'ok' and systemStatus == 'ok' %} 2/2 check passed {% elif systemStatus == 'not-applicable' %} {% else %} {{systemStatus}} {% endif %} {% else %} {% endif %}

Tagging an instance

Within AWS you have the option to tag resources. Tagging in this case means a name/value pair that allows you to store any information. You can store up to 50 tags per resource in AWS. To enable tagging from within Oomnitza, you need to identify which attributes you should map from Oomnitza to tags in AWS. One possible example would be to map a dropdown list in Oomnitza called Usage with values Customer, Internal, DevOps, Development and Testing to a tag in AWS. There are four sample presets that you can use to tag an EC2 instance.

Amazon AWS create tag for EC2 instance

This Amazon AWS create tag for EC2 instance allows you to create and update tags in AWS from Oomnitza. When you specify an existing tag, the value is overwritten with the new value. To leverage this preset, complete the following steps:

  1. Ensure that the fields aws_region and serial_number are defined within Oomnitza, as mentioned in Amazon AWS EC2 Start EC2 instance.
  2. In the API block window, click the Advanced Mode button located in the upper right of the window.
  3. Select the Params tab.
  4. By default, Tag.1.Key and Tag.1.Value have already been mapped.
  5. To add new tags, enter a new key name and value, i.e. Tag.2.Key and Tag.2.Value. Tag.2.Value should be an existing field in Oomnitza, like {{aws_instance_usage}}. In general we recommend this field to be a drop down field.

Amazon AWS get tag from EC2 instance

This Amazon AWS get tag from EC2 instance preset allows you to read the tags from AWS instance and store it in an attribute. The API provides a list of tags that you can store in a dropdown list Oomnitza. Alternatively you can store all tags in a text field in Oomnitza.

To leverage this preset, complete the following steps:

  1. Ensure that the fields aws_region and serial_number are defined within Oomnitza, as mentioned in Amazon AWS EC2 Start EC2 instance.
  2. In the API block window, click the Advanced Mode button located in the upper right of the window.
  3. Select the Response tab.
  4. Enter the below code snippet in the Response field.
{% set temp = response['DescribeTagsResponse']['tagSet']['item']%}{%if (temp is defined) and temp%}{{ temp | selectattr('key', 'eq', 'Usage') | map(attribute='value') | join('') }}{% endif %}

This statement will filter and return values relating to the Usage tag, which you can then pass on to an attribute in Oomnitza like aws_instance_usage.

Using this approach you would have to specify one response mapping for each tag you want to map to Oomnitza. If you map tags to a dropdown list with value list, you should make sure that all these values exist in Oomnitza or alternatively switch this attribute to free text or a dropdown without value list. You could use this preset daily to sync data between AWS and Oomnitza and read all current tags from AWS.

Amazon AWS delete tag from EC2 instance

This Amazon AWS delete tag from EC2 instance preset allows you to delete tags from EC2 instances. In order to remove tags, you must have the Tag Key of the tag you wish to delete, either taken directly from AWS, or using either of the above workflows. To set your workflow to delete a specific tag, apply the Amazon AWS delete tag from EC2 instance to your API block, then complete the following steps:

  1. In the API block window, click the Advanced Mode button located in the upper right of the window.
  2. Navigate to the Params tab. From there, specify the tag to delete in the "Tag.1.Key" value field, for example: 
    Tag.1.Key = stack
    Alternatively, you can set the param to reference a metadata field in Oomnitza, such as: 
    Tag.1.Key = {{tag_1_key}}

Amazon AWS get average CPU Load for an EC2 instance

This Amazon AWS get average CPU Load for an EC2 instance preset allows you to get the average CPU Load during a specified monitoring period. You can define the length of the monitoring period in hours and define the number of monitoring periods. Once this criteria is defined, the response mapping will return the maximum average CPU for the EC2 instance for each monitoring period until the number of monitoring periods is reached. For example, if you have a monitoring period of 12 hours and have set 14 monitoring periods, you would get the average CPU load every 12 hours until the monitoring period of 14 (or one week) is reached. You can map the response as the maximum average CPU load for a 12 hour period. This information can help you reduce costs. For example, if you find that the maximum average CPU of an instance is under 10%, you may need to review this instance to find out if it is still in use.

When using this preset, ensure that the fields aws_region and serial_number are defined within Oomnitza, as mentioned in Amazon AWS EC2 Start EC2 instance.

Note
Please keep in mind that this preset uses the AWS monitoring APIs and there may be additional charges for using this API within AWS. Please contact AWS for details on this.

Additional instance operations

There are plenty of additional actions available to control your EC2 instances. You can find a complete list at Amazon Elastic Cloud API Reference. We will continue to add the most valuable ones as presets, but for now, you can always start with any of the existing presets and go to Advanced Mode to easily change it to any of the supported actions by AWS.

Unleash the power of Oomnitza

To get valuable actionable insights that help you manage your assets, learn how to:

      • Configure dashboards for your users and software
      • Configure custom reports about your users and software
      • Create workflows to automate tasks

See small_blue_link.svg Getting started for more information.

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk