Turbonomic

 View Only

Understanding Turbonomic APIs for External Integrations

By JYOTI RANI posted Thu September 29, 2022 07:05 AM

  

IBM Turbonomic is an Application Resource management solution to continuously assure application performance at lowest cost. Turbonomic provides a rich set of APIs for integration with external tools/solutions.  These are useful to extend features/functionalities of Turbonomic to third party tools like FinOps, Sustainability tools, or other Enterprise applications.

Turbonomic swagger documentation can be accessed at https://<Your_Turbonomic_IP>/swagger/external/index.html by replacing <Your_Turbonomic_IP> with IP/hostname of your Turbonomic instance, for instance  https://nginx-turbonomic.apps.luke.coc-ibm.com/swagger/external/index.html

In this Blog, we will walk through an end to end scenario to fetch Entities (e.g. VMs, Containers, Databases etc.), Supply chain/Statistics/Metrics for specific Entity, related actions and how to execute the action using Turbonomic APIs.

Authenticating with Turbonomic API

Please refer cookbook in the Turbonomic documentation to understand authentication with Turbonomic API.

Entry point to Turbonomic Entities
GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/entities

There are multiple ways to fetch Entities (VMs, Databases, Containers, Business Applications etc.) data in Turbonomic, this is analogous to how we browse to Entities from Turbonomic UI through supply chain, groups, or search UI as listed below:

Entry point to Entities Analogy to Turbonomic UI APIs
Market Using supply chain to drill down to an Entity or Plans in Turbonomic
https://nginx-turbonomic.apps.luke.coc-ibm.com:443/api/v3/markets/{uuid}/entities?ascending=true
Group When we create Groups of entities based on certain criteria and use that as entry point to the entity https://nginx-turbonomic.apps.luke.coc-ibm.com:443/api/v3/groups/{uuid}/entities
Search When we navigate to the entity through Search in Turbonomic UI https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/search?types={entity_types}
Tags (If applicable to the entity) Search by tags https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/tags/{key}/entities


Lets start with Market

GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/markets

Turbonomic supply chain represents the market based analysis, representing each entity as buyer and seller in the market. There are two types of markets:
1. Real time market - You can use the real-time market to access entities and get current or historical data about them. This market should always be in the RUNNING state and should never be stopped
2. Plan market - Its a snapshot of the real-time market, created by specifying the scope which defines what all entities needs to be part of the plan market. This is created via 'Plans' in Turbonomic

Sample response:


Lets work with the Real time market and now pick the uuid of the market to fetch the entities in the market.
Entities in the market: GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/markets/777777/entities?ascending=true
Response will return all entities in the market along with Uuid and other details of each entity.

Entities By Groups
GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/groups


Group is a collection of entities such as physical machines, containers, clusters, or even other groups that Turbonomic can work with as a unit. You can use the groups API to list all the groups and then picking the Uuid of the specific group to fetch all entities in the group.
Entities in group: GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/groups/285764387903186/entities
Response will return all entities in the group along with Uuid and other details of each entity.

Entities by search
Search is a powerful way of fetching the required information. Search endpoint documentation highlights all the possible criteria available to search various entity types in Turbonomic e.g. by VirtualMachine, Database, DataCenter, Group, Container etc.

Listing below few example search queries:

Search for all Virtual Machines in Cloud https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/search?types=VirtualMachine&entity_types=VirtualMachines&environment_type=CLOUD&order_by=NAME&ascending=true
Search for all Business Accounts in Cloud https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/search?environment_type=CLOUD&types=BusinessAccount
Search for all Virtual Machines in specific business account (Business Account Uuid 74567243254496) https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/search?environment_type=CLOUD&scopes=74567243254496&entity_types=VirtualMachine&types=VirtualMachine


Response will return the entities matching the search criteria along with Uuid and other details of each entity. Please refer docs for more details on search endpoint.

Entities by Tags
GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/tags/


Turbonomic discovers the Tags from the managed environment and tags are useful way of identifying resources uniquely. You can list all the discovered tags from the above API call and then list the entities related to the specific tag.
Entities with tag: https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/tags/CQW/entities
Response will return all entities tagged with the specified 'CQW' tag along with Uuid and other details of each entity.

Fetching Single Entity details
Now that we have covered how to get list of entities, we will cover how to fetch further details of a specific entity like Container, VM, database, Business Application etc.

Statistics
GET Statistics: https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/stats

Statistics are pieces of information that Turbonomic discovers while continuously analyzing your environment e.g. Transaction, Response time, CPU/Memory utilization etc. based on entity type. The above endpoint lists the entry points to get Uuid based statistics which includes stats by Uuid, Entity Uuid or Group Uuid. Depending upon the type of entity, one of the entry points can be used to get the entity stats.

For an example Business Application entity with entity Uuid  '74567240470947', statistics can be fetched with any of the below APIs:

GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/entities/74567240470947/stats
GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/stats/74567240470947

Sample response:


Refer docs for more details on statistics endpoint.

Supply chain
GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/supplychains?uuids={entity_uuid}

Gets the full supply chain for the specified entity. If the specified entity is a Business Application, then https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/supplychains?uuids=74567240470947 will return the sample response as below:

Each element in the supply chain response has a depth, that refers to the distance in the supply chain from the entity called.

Actions
Entry points for Actions, GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/actions

Given the entity Uuid, list of actions can be fetched with the above entry points. Actions for the example Business application entity with Uuid '74567240470947' can be fetched with the below API:

GET https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/entities/74567240470947/actions


These actions can be filtered based on action modes (Automatic, manual etc.), State (accepted, rejected, disabled etc.), type (start, stop, scale etc.) etc. Refer docs for complete list of available filter options.

Execute the Actions
Now that we have fetched the statistics and related actions for entity, lets look at the APIs to execute/apply the action using Turbonomic automation.

Accept an action (execute)
POST https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/actions/{action_uuid}?accept=true
Reject an action
POST https://nginx-turbonomic.apps.luke.coc-ibm.com/api/v3/actions/{action_uuid}?accept=false

Conclusion

In this article, we have explored how Turbonomic APIs can be used to fetch Markets, Entities, Tags, Search, Supply chain, Statistics and Actions for Entities and how to execute Turbo actions through APIs. Though the possibilities are endless with Turbonomic APIs and are not limited to just the APIs discussed in this blog. You can work with Policies, Topologies, Templates, Settings, Reserved instances, Licenses etc. all through the rich set of APIs which makes it easy to extend Turbonomic functionality to external tools/solutions.

2 comments
165 views

Permalink

Comments

Thu May 04, 2023 08:55 AM

Thanks @Jason Shaw I've made the updates as per your inputs. Thanks for pointing out.

Thu May 04, 2023 08:00 AM

Great blog  @JYOTI RANI !  Just a few updates needed as some of the links to the documentation do not work anymore.  

Link to swagger should be: https://www.ibm.com/docs/en/tarm/latest?topic=reference-turbonomic-rest-api-swagger-documentation#guidestruc_intro_swagger

Link to cookbook should be: https://www.ibm.com/docs/en/tarm/latest?topic=cookbook-authenticating-api

A little tip, replace the Turbonomic version in the URL with the word "latest" and it will always re-direct to the latest version of the documentation instead of a static version as you have in your current blog that do not work anymore.