Amazon Web Services (AWS) EC2 Integrations

Oomnitza's AWS EC2 Integrations allow you to ingest the ec2 instances within a given AWS region as well as trigger certain actions to control these instances within AWS.

Following Integrations are available for AWS ec2:

Authentication

AWS's REST API uses its own unique authentication (AWS). For more information on AWS Authentication and creating AWS credentials, see our article here: https://oomnitza.zendesk.com/hc/en-us/articles/360059591413#h_01EQ1E8WFXQVK4D0HDEKB7ENR8 . You will use this authentication for all integrations mentioned here.

Load list of ec2 instances for a given region

Extended Connector allows organizations to pull device information from AWS for ec2 instances and populate it in Oomnitza. More info in AWS can be found here: https://aws.amazon.com/ 

blobid0.png

Setup

Details on setting up Oomnitza Extended Connectors can be found in Oomnitza's Articles on Connector Setup.

After selecting this integration from the list of Asset integrations, you will first have to provide some general information about this, including a name, installation type, credentials and so on. Please note that due to the AWS specific authentication we currently only support AWS integration with the cloud based connector installation. For the region field, please specify the AWS region from where you want to read the list of ec2 instances. Possible values for this include: us-west-1, us-west-2 and eu-central-1. For a complete list, please refer to your AWS account details.

Note: In addition to the standard fields entered during setup, you'll also need your AWS Region (e.g. us-west-2, eu-central-1). To pull information on EC2 instances in multiple regions, please set up multiple child connectors. To do so, finish your main connector where you specify the field mapping and then click on the plus sign in the AWS logo on Settings page to create a child connector which allows you to specify different accounts or regions then on the child connector - connect page.

 

Standard Field Mappings

Selecting Next will bring you to the Mapping screen. Here you can define the field mappings between AWS and Oomnitza, hardcode certain fields on the Oomnitza side, edit the general connector behavior, add additional fields to the AWS side which may have been added in a later version of the REST API from AWS and lastly also add additional fields to the Oomnitza data model for assets.

For the field mapping, it may be a good idea to "hard-code" the asset type to something like "Virtual Instance" on the right side. Another field you may want to hard-code is the AWS Region since this is not part of the payload but will be required for the additional API block integrations mentioned below. You can derive the AWS region by either hardcoding it within the connector itself or by triggering a workflow upon creation of a new AWS ec2 instance in Oomnitza by deriving it from the availability zone within an update block. As sync key, we usually recommend to map the Instance ID with the Serial Number field in Oomnitza.

The following fields can be mapped from AWS using Oomnitza's User Interface. For more information on creating Extended Connector Mappings, please see our article on Mapping Extended Connectors.

  • 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

Custom Mappings

Additional fields may be available through AWS. For details on how to retrieve them, please reach out to support@oomnitza.com or see our article on Mapping Extended Connectors.

Please keep in mind that integrations like this one will only provide you the list of active assets (that is running and stopped ec2 instances), but not ones that have been deleted already. You might want to set up a workflow to eventually archive instances that have not been updated in a while to only have the list of active instances within Oomnitza.

 

Load list of EBS volumes for a given region

This asset load allows you to load the list of AWS EBS (Elastic Block Storage) volumes from AWS into Oomnitza. This is useful to find out which EBSs are connected to which ec2 instances and to also find orphaned EBS volumes that are no longer needed and could get deleted to safe money on your AWS bill. 

After selecting this integration from the list of Asset integrations, you will first have to provide some general information about this, including a name, installation type, credentials and so on. Please note that due to the AWS specific authentication we currently only support AWS integration with the cloud based connector installation. For the region field, please specify the AWS region from where you want to read the list of ec2 instances. Possible values for this include: us-west-1, us-west-2 and eu-central-1. For a complete list, please refer to your AWS account details.

Note: In addition to the standard fields entered during setup, you'll also need your AWS Region (e.g. us-west-2, eu-central-1). To pull information on EC2 instances in multiple regions, please set up multiple child connectors. To do so, finish your main connector where you specify the field mapping and then click on the plus sign in the AWS logo on Settings page to create a child connector which allows you to specify different accounts or regions then on the child connector - connect page.

Standard Field Mappings

Selecting Next will bring you to the Mapping screen. Here you can define the field mappings between AWS EBS and Oomnitza. The following fields are available for EBS volumes:

  • Attach status
  • Attached since
  • Availability Zone
  • Connector Sync Time
  • Creation Time
  • Delete on Termination?
  • Encrypted?
  • Mapped device/path
  • Multi attach enabled?
  • Primary Instance - the first instance that this volume is mapped to. In case of multi instnaces, we only show the first one
  • Region - the AWS region of this volume
  • Size (in GB)
  • Status
  • Volume ID - this should get mapped to Serial Number or another unique identifier
  • Volume Name
  • Volume Type

Please keep in mind that integrations like this one will only provide you the list of active items (that is in-use or available volumes), but not ones that have been deleted already. You might want to set up a workflow to eventually archive items that have not been updated in a while to only have the list of active items within Oomnitza.

 

Start an instance

The API preset "Amazon AWS start ec2 instance" allows you to start an already existing ec2 instance. To leverage the standard API block, you need to select the proper AWS credential. Also this preset requires to have the AWS region within the field aws_region as well as the Instance ID within the field serial_number. Here both fieldnames refer to the technical field names of these object attributes. In case this information is available within different fields in your implementation, you can use the advanced mode to adjust the API preset accordingly.

 

Stop an instance

The API preset "Amazon AWS stop ec2 instance" allows you to stop an already existing ec2 instance. Otherwise the same items apply as already mentioned above in start instance.

 

Reboot an instance

The API preset "Amazon AWS reboot ec2 instance" allows you to reboot an already existing ec2 instance. Otherwise the same items apply as already mentioned above in start instance.

 

Get details of single ec2 instance

The API preset "Amazon AWS get details of single ec2 instance" allows you to get the details of a single ec2 instance. Again you need to use a proper AWS credential and have the fields aws_region and serial_number defined within Oomnitza. With this block, you need to leverage the response mapping via the Advanced Mode to get the values from the response and parse them to attributes of your Asset in Oomnitza. Like e.g. the statement 

{% set temp = response['DescribeInstancesResponse']['reservationSet']['item']['instancesSet']['item']['instanceState']['name'] %}{% if 'name' in temp %}{{[temp]}}{% else %}{{temp}}{% endif %}

will get you the status of the ec2 instance, like Running, Stopped and so on. You can find more attributes and details within the AWS documentation mentioned below. Also 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. This way finding the proper statement will be much easier.

 

Get details of an ec2 instance status

The Amazon AWS System Status ec2 API preset allows you to retrieve the status of your EC2 instances. By using this preset, and including the following mapping in the Response section, you can pull ec2 system status into the mapped field in Oomnitza.

{% 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 of an instance

Within AWS you have the option to tag any resources. Tagging in this case means a name/value pair that allows you to store any information and you can store up to 50 tags per resource in AWS. To enable tagging from within Oomnitza, you need to identify which attributes from Oomnitza should map to which tags in AWS. One possible example would be to map a field with drop down values to a tag in AWS, like a field in Oomnitza called Usage with values Customer, Internal, DevOps, Development, Testing can be mapped to a tag. Here the tag would be called usage and the values for this tag would map to the drop down values of this field in Oomnitza. To accommodate the tagging of ec2 instances use case, we created 2 sample presets that you may use to adjust it to your specific requirements.

Preset 1: Amazon AWS create tag for ec2 instance

This preset allows you to create and update tags in AWS from within Oomnitza. When you specify an existing tag, the value is overwritten with the new value. To leverage this preset, you should select it from the list of available ones and go to advanced mode. There, select the proper authorization and also ensure that the field aws_region contains the value for the AWS region and the field Serial Number contains the resource ID in AWS. Then on the parameter tab, you can specify which tag you want to create in AWS. You do that by adjusting the value of the parameter Tag.1.Key to like Usage. After that you map the value for this tag to the parameter Tag.1.Value with an existing field in Oomnitza, like {{aws_instance_usage}}. In general we recommend this field to be a drop down field. In case you want to create multiple tags at the same time, you can add additional parameters by using parameters like Tag.2.Key and Tag.2.Value and so on. Response mapping is not needed for this preset since the answer will only include a confirmation of the tags that have been created.

Preset 2: Amazon AWS get tag from ec2 instance

Using this preset allows you to read the tags for a given instance from AWS and store it within an attribute of the asset. The API actually provides a list of tags which you might want to filter to only one which you would then update Oomnitza with. Alternatively you can store all tags within a text field in Oomnitza. To leverage this preset, you should select it from the list of available ones and go to advanced mode. There, select the proper authorization and also ensure that the field aws_region contains the value for the AWS region and the field Serial Number contains the resource ID in AWS. Within the response mapping tab, you then need to specify which field should be mapped by e.g. using following statement there:

{% 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 out the tag named Usage and provide the value for this tag only, which you may 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 within Oomnitza also in case you map these tags to a drop down with value list, you should make sure that all these values exist in Oomnitza or alternatively switch this attribute to free text or drop down without value list. You would use this API preset for a daily data sync between AWS and Oomnitza to read all current tags from AWS.

Preset 3: Amazon AWS delete tag from EC2 instance

This 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 navigate to the Params tab. From their, 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}}

 

Get Average CPU Load for an EC2 instance

This preset allows you to load the average CPU for a given period (in hours). You can define the length of such period in hours and also how many periods you would like to look back from today. In case you look back at more than 1 period, the response mapping allows you to only show the maximum average CPU for the given ec2 instance. An example would be to look at the average CPU load for a 12 hour period and look back 14 such periods which would be 1 week. You can then map the response as the maximum average CPU load for any 12 hour period. Let's say this value is below 10% this might indicate an instance you should review since you might be able to reduce it's size or even find out that this instance is not used any more.

This preset uses 2 asset attributes: aws_region and serial_number. In case your AWS region is stored in a different attribute you may have to adjust the preset in advanced mode to replace the field aws_region in the URL for the request. The serial_number represents the ID for the instance and again in case you have the instanceId in a different field, you have to adjust the field serial_number in the request body to the field you are using.

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 and you can find a complete list available at https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Operations.html . We will continue to add the most valuable ones as presets, but you can always start with of of the existing presets and then go to Advanced Mode to easily change it to any of the supported actions by AWS.

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk