Targets requests

Target requests handle creation, configuration, validation, rediscovery, and deletion of targets on your Turbonomic appliance.

Pagination for targets requests

When you request target entities, the API uses pagination to return subsets of the data. You should always use pagination when available to make sure you get your data in manageable chunks. To paginate returned data, the limit, orderBy, and cursor parameters control how the APIs paginate their data.

If you do not specify a limit for the GET /targets/<targetId>/entities request, the API will paginate the data to a default limit of records. If your script makes this request without setting a limit, you should be sure it checks for a pagination cursor in the returned data.

For general information about pagination, see Pagination in the Turbonomic API.

Getting targets

For a list of targets, the API returns an array of TargetApiDTO objects. Each TargetApiDTO object will contain the validation status, target type and category, and input field names and values. To get a single target, include the UUID of the target in the request.

This request takes the following parameters:

environment_type

Returns only targets in the specified environment type. [ Cloud, Hybrid, Onprem ]

Examples:

  • All Targets: GET https://10.10.10.10/api/v3/targets

  • Single Target: GET https://10.10.10.10/api/v3/targets/__xwWYAE33eku7PbzHdETIA

Response: A single entry in an array of targets. Notice that the password field is secret, so the response does not contain the password value.

[
  {
  "uuid":"__xwWYAE33eku7PbzHdETIA",
  "category":"Hypervisor",
  "type":"vCenter",
  "status":"Validated",
  "lastValidated":"2018-06-26T14:25:08-04:00",
  "inputFields":[
    {
      "displayName":"Address",
      "name":"address",
      "value":"vsphere-demo.mycorp.com",
      "isMandatory":true,
      "isSecret":false,
      "valueType":"STRING",
      "description":"IP or address of vCenter Server",
      "verificationRegex":".*"
    },
    {
      "displayName":"Username",
      "name":"username",
      "value":"corp\\my.user",
      "isMandatory":true,
      "isSecret":false,
      "valueType":"STRING",
      "description":"User name to use to connect to a target",
      "verificationRegex":".*"
    },
    {
      "displayName":"Password",
      "name":"password",
      "isMandatory":true,
      "isSecret":true,
      "valueType":"STRING",
      "description":"Password to use to connect to a target",
      "verificationRegex":".*"
    }
  ]

Adding a target

Adds a target to your Turbonomic installation. You must pass a completed TargetApiDTO object as an inputDTO. For more information about the required fields of the TargetApiDTO for the target you want to add, execute the /targets/specs utility request.

Example: POST https://10.10.10.10/api/v3/targets

Example inputDTO:

{
  "category":"Hypervisor",
  "inputFields":[
    {
      "name":"username",
      "value":"corp\\my.name"
    },
    {
      "name":"password",
      "value":"Octopath"
    },
    {
      "name":"nameOrAddress",
      "value":"10.10.10.10"
    }
  ],
  "type":"vCenter"
}

Rediscover or validate all targets

Manually triggers a full rediscovery or validation of all targets in your environment. This is often done to immediately see multiple changes that would normally not be reflected until a daily full discovery is performed, such as displaying updated Orchestrator workflows.

This call takes the following parameters:

  • validate

    When true, validates all targets in your environment

  • rediscover

    When true, performs a full rediscovery on all targets in your environment

Examples:

  • Rediscovery:

    POST https://10.10.10.10/api/v3/targets?validate=true

  • Validation:

    POST https://10.10.10.10/api/v3/targets?rediscover=true

Rediscover or Validate A Single Target

Manually triggers a full rediscovery or validation of a single target in your environment. This is often done to immediately see a change that would normally not be reflected until a daily full discovery is performed, such as displaying updated Orchestrator workflows.

This call takes the following parameters:

  • validate

    When true, validates the specified target

  • rediscover

    When true, performs a full rediscovery on the specified target

Examples:

  • Rediscovery: https://10.10.10.10/api/v3/targets/__xwWYAE33eku7PbzHdETIA?rediscover=true

  • Validation: https://10.10.10.10/api/v3/targets/__xwWYAE33eku7PbzHdETIA?validate=true

Response: The TargetApiDTO object of the specified target:

{
  "uuid":"__xwWYAE3EeiNKPbzHdETIA",
  "category":"Hypervisor",
  "inputFields":[
    ...
  ],
  "lastValidated":"2018-06-27T21:45:56-04:00",
  "status":"Validated",
  "type":"vCenter"
}

Editing target input fields

Edits the input fields of an existing target, and accepts the modified TargetApiDTO as input.

Note: You can GET the target first using the GET /targets/specs to see the fields required for that target. Note that you must pass all input fields in the modified TargetApiDTO object.

Example: PUT https://10.10.10.10/api/v3/targets/_HgzQ4CdCEeaUWYEyo3vsyw

Example input, editing the username for a single target:

[
  {
    "uuid":"_HgzQ4CdCEeaUWYEyo3vsyw",
    "category":"Hypervisor",
    "type":"vCenter",
    "status":"Validated",
    "lastValidated":1474575346109,
    "inputFields":[
      {
        "displayName":"Address",
        "name":"address",
        "value":"vsphere.mycorp.com",
        "isMandatory":true,
        "isSecret":false,
        "valueType":"STRING"
      },
      {
        "displayName":"Username",
        "name":"username",
        "value":"corp\\my.name.changed",
        "isMandatory":true,
        "isSecret":false,
        "valueType":"STRING"
      },
      {
        "displayName":"Password",
        "name":"password",
        "value":"Octopath",
        "isMandatory":true,
        "isSecret":true
      }
    ]
  }
]

Deleting a target

Deletes the specified target and removes all entities managed by that target. This will also remove any pending actions related to the deleted target.

Example: DELETE https://10.10.10.10/api/v3/targets/__xwWYAE3EeiNKPbzHdETIA

Response: A successful deletion request returns a Response Code of 200.

Actions for a specified target

Referenced Endpoint: Actions

These requests get full or filtered lists of actions per target for use in reports, or to find a particular action.

Note: Once you have the action UUID, you can use requests from the actions endpoint to post changes to that action.

Getting an Unfiltered Array of Actions

Gets a list of current actions in your environment associated to entities discovered by the specified target.

Example: GET https://10.10.10.10/api/v3/targets/__xwWYAE3EeiNKPbzHdETIA/actions

Getting a Filtered Array of Actions

Gets a filtered list of actions discovered by a single target. Pass an inputDTO containing one or more of the following criteria:

  • actionModeList

    • DISABLED:

      Do not recommend or perform the action. When you disable an action, the user interface will no longer display actions of that type.

    • RECOMMENDED:

      Recommend the action so a user can execute it via the given hypervisor or by other external means

    • MANUAL:

      Recommend the action, and provide the option to execute that action through the Turbonomic user interface or an /actions API request.

    • AUTOMATED:

      You have directed Turbonomic to execute the action automatically.

    • COLLECTION (UNUSED):

      Legacy action mode, no longer used.

  • actionStateList

    • DISABLED:

      An action whose policy has been disabled.

    • RECOMMEND:

      An action that cannot be automated due to policy settings or must be executed outside the system, such as the purchase of hardware.

    • PENDING_ACCEPT:

      When the action mode is set to manual, a recommended action that has not been accepted or cleared.

    • ACCEPTED:

      An action that has been accepted, but is not yet in progress.

    • IN_PROGRESS:

      An action that is being executed.

    • SUCCEEDED:

      An action that was accepted and completed successfully.

    • FAILED:

      An action that was accepted and did not complete successfully.

    • REJECTED:

      When the action mode is set to manual, an action that has been rejected by the user.

    • CLEARED:

      When the action mode is set to manual, an action that is no longer recommended by the market.

    • ACCOUNTING:

      For cloud entities, an action to resize in order to use a different instance template.

    • QUEUED:

      When more than 10 actions are to be executed for a single target, Turbonomic will place the 11th and all subsequent actions into a QUEUED state, and they will execute as the previous actions complete.

  • actionTypeList

    • START:

      Start an entity, and add it to the Turbonomic market.

    • MOVE:

      Move an entity from one provider to another. For example, moving a VM between hosts, or a datastore between disk arrays.

    • SUSPEND:

      Suspend the entity to exclude its capacity from your environment. Suspend does not remove the entity from your environment, but the market does not include the entity in its analysis. Based on market conditions, analysis can recommend restarting suspended entities, which includes them in market analysis once again.

    • ADD PROVIDER:

      This is equivalent to the START action, but for storage entities.

    • CHANGE:

      Move a virtual machine's storage between datastores.

    • PROVISION:

      Add capacity to your environment.

    • RECONFIGURE:

      Analysis recommends this when a VM is not able to correct a misconfiguration via another type of action. For example, analysis can recommend a RECONFIGURE action when a placement policy requires a VM to move to a host on a particular cluster, but cross-cluster moves are not permitted.

    • DELETE:

      This is equivalent to the SUSPEND action, but for storage entities.

    • RESERVE_ON_PM:

      When using the reservation functionality, this is the action to reserve the resources of a VM on a particular host.

    • RESERVE_ON_DS:

      When using the reservation functionality, this is the action to reserve the resources of a VM on a particular datastore.

    • RESIZE_FOR_EFFICIENCY:

      A resize that reduces the capacity of a commodity, such as vCPU, or vMEM.

    • RESIZE_FOR_PERFORMANCE:

      A resize that increases the capacity of a commodity, such as vCPU, or vMEM.

  • cleared

    Default: false.

    When true, actions that were removed from the action list before being executed will be returned.

  • costType

    • Saving

      An action that will decrease cloud spending.

    • Investment

      An action that will increase cloud spending.

  • cumulative

    Default: false.

    When true, shows the savings for each action in a scope as a cumulative total, rather than showing the savings for individual actions.

  • environmentType

    • ONPREM:

      Returns only actions related to entities that are part of your on-prem environment.

    • CLOUD:

      Returns only actions related to entities that are part of your cloud environment.

  • groupBy

    You may group the actions returned by the following criteria: [actionModes, actionStates, actionTypes, risk, riskSeverity, riskSubCategory]

  • hasReservedInstance

    Default: false.

    When true, only actions that are related to reserved instances will be returned.

  • relatedEntityTypes

    Returns only actions related to entities of these types within the scope. For example, if your scope is a virtual datacenter and you specify VirtualMachine as a related entity type, the request will include only those actions related to VMs in the specified virtual datacenter.

    Choose from the following entity types: [ Datacenter, PhysicalMachine, VirtualMachine, Storage, Application, Chassis, DiskArray, IOModule, StorageControl, Switch, VirtualDataCenter, VPod, DPod, Container, Database, DatabaseServerContainer, LogicalPool ]

  • riskSeverityList

    Returns only actions of the given severities: [ Unknown, Normal, Minor, Major, Critical ]

  • riskSubCategoryList

  • returns only actions of the given subcategories: [ Performance Assurance, Efficiency Improvement, Prevention, Compliance ]

Example: POST https://10.10.10.10/api/v3/targets/__xwWYAE3EeiNKPbzHdETIA/actions

Example inputDto, filtering for actions that are pending acceptance: 
{
  "actionStateList":[
    "PENDING_ACCEPT"
  ]
}

Response: An array of actions applicable to the specified target that are in the PENDING_ACCEPT state. 

[
  {
    "links":[
      {
        "rel":"self",
        "href":"https://10.10.10.10/api/v3/actions/_uictIJuHEeics6ASgJ-kdg"
      },
      {
        "rel":"self",
        "href":"https://10.10.10.10/api/v3/actions/2204259249360"
      }
    ],
    "uuid":"_uictIJuHEeics6ASgJ-kdg",
    "createTime":"2018-08-08T23:53:08-04:00",
    "actionType":"RIGHT_SIZE",
    "actionState":"PENDING_ACCEPT",
    "actionMode":"MANUAL",
    "details":"Scale down VMem for VirtualMachine btc-1 from 8 GB to 7 GB",
    "importance":0,
    "target":{
      "uuid":"4223dcd6-0b28-6ae6-1066-689912ced3a1",
      "displayName":"btc-1",
      "className":"VirtualMachine",
      "aspects":{
        "virtualMachineAspect":{
          "os":"Other Linux (64-bit)",
          "connectedNetworks":[
            {
              "uuid":"74c91ba4fa390030f47f91e6e1ee77ff7b4db353",
              "displayName":"VM Network"
            }
          ],
          "numVCPUs":1,
          "ebsOptimized":false
        }
      },
      "environmentType":"ONPREM"
    },
    "currentEntity":{
      "uuid":"_ui4yAZuHEeics6ASgJ-kdg",
      "className":"VMem"
    },
    "newEntity":{
      "uuid":"_ui4yA5uHEeics6ASgJ-kdg",
      "className":"VMem"
    },
    "currentValue":"8388608.0",
    "newValue":"7340032.0",
    "resizeToValue":"7340032.0",
    "risk":{
      "uuid":"_ujB78ZuHEeics6ASgJ-kdg",
      "subCategory":"Efficiency Improvement",
      "description":"Underutilized VMem in Virtual Machine 'btc-1'",
      "severity":"MINOR",
      "reasonCommodity":"VMem",
      "importance":0
    },
    "stats":[
      {
        "name":"costPrice",
        "filters":[
          {
            "type":"savingsType",
            "value":"savings"
          }
        ],
        "units":"$",
        "value":50
      }
    ],
    "actionID":2204259249360
  },
  ...
  }
]

Entities for a specified target

Referenced Endpoint: Entities

Gets a list of entities discovered by the specified target. This is used most often for reporting, dashboard, or inventory purposes.

Getting An Array of Entities

Gets a list of all entities discovered by the specified target. An entity is any device in your environment that Turbonomic manages, such as applications, physical machines, VMs, storage, and datacenters.

Example:GET https://10.10.10.10/api/v3/targets/__xwWYAE3EeiNKPbzHdETIA/actions

Response: An array of EntityApiDTO objects belonging to a vCenter target:

[
  {
    "links":[
      {
        "rel":"self",
        "href":"https://10.10.10.10/api/v3/entities/vsphere-mycorp.com-ResourcePool-resgroup-8?include_aspects=false"
      }
    ],
    "uuid":"vsphere-mycorp.com-ResourcePool-resgroup-8",
    "displayName":"Resources-Cluster1",
    "className":"VirtualDataCenter",
    "priceIndex":1e-12,
    "state":"ACTIVE",
    "severity":"Normal",
    "discoveredBy":{
      "uuid":"__xwWYAE3EeiNKPbzHdETIA",
      "displayName":"vsphere-mycorp.com",
      "type":"vCenter"
    },
    "remoteId":"resgroup-8",
    "environmentType":"ONPREM"
  },
  {
    "links":[
      {
        "rel":"self",
        "href":"https://10.10.10.10/api/v3/entities/vsphere-mycorp.com-GuestLoad-421ddc94-8d0c-504a-62f5-493802e96d0a?include_aspects=false"
      }
    ],
    "uuid":"vsphere-mycorp.com-GuestLoad-421ddc94-8d0c-504a-62f5-493802e96d0a",
    "displayName":"GuestLoad[Nexus1000V]",
    "className":"Application",
    "priceIndex":1,
    "state":"ACTIVE",
    "severity":"Normal",
    "discoveredBy":{
      "uuid":"__xwWYAE3EeiNKPbzHdETIA",
      "displayName":"vsphere-mycorp.com",
      "type":"vCenter"
    },
    "remoteId":"vm-51",
    "environmentType":"ONPREM"
  },
  ...
  }
]