Jump to

• Request
• Response

List Instances for an Instance

get

/api/v2/instances/{id}/peers/

Make a GET request to this resource to retrieve a list of instances associated with the selected instance.

The resulting data structure contains:

{
    "count": 99,
    "next": null,
    "previous": null,
    "results": [
        ...
    ]
}

The count field indicates the total number of instances found for the given query. The next and previous fields provides links to additional results if there are more than will fit on a single page. The results list contains zero or more instance records.

Results

Each instance data structure includes the following fields:

• id: Database ID for this instance. (integer)
• hostname: (string)
• type: Data type for this instance. (choice)
• url: URL for this instance. (string)
• related: Data structure with URLs of related resources. (object)
• summary_fields: Data structure with name/description for related resources. The output for some objects may be limited for performance reasons. (object)
• uuid: (string)
• created: Timestamp when this instance was created. (datetime)
• modified: Timestamp when this instance was last modified. (datetime)
• last_seen: Last time instance ran its heartbeat task for main cluster nodes. Last known connection to receptor mesh for execution nodes. (datetime)
• health_check_started: The last time a health check was initiated on this instance. (datetime)
• health_check_pending: (field)
• last_health_check: Last time a health check was ran on this instance to refresh cpu, memory, and capacity. (datetime)
• errors: Any error details from the last health check. (string)
• capacity_adjustment: (decimal)
• version: (string)
• capacity: (integer)
• consumed_capacity: (field)
• percent_capacity_remaining: (field)
• jobs_running: Count of jobs in the running or waiting state that are targeted for this instance (integer)
• jobs_total: Count of all jobs that target this instance (integer)
• cpu: (decimal)
• memory: Total system memory of this instance in bytes. (integer)
• cpu_capacity: (integer)
• mem_capacity: (integer)
• enabled: (boolean)
• managed_by_policy: (boolean)
• node_type: Role that this node plays in the mesh. (choice)
  • control: Control plane node
  • execution: Execution plane node
  • hybrid: Controller and execution
  • hop: Message-passing node, no execution capability
• node_state: Indicates the current life cycle stage of this instance. (choice)
  • provisioning: Provisioning
  • provision-fail: Provisioning Failure
  • installed: Installed
  • ready: Ready
  • unavailable: Unavailable
  • deprovisioning: De-provisioning
  • deprovision-fail: De-provisioning Failure
• ip_address: (string)
• listener_port: Port that Receptor will listen for incoming connections on. (integer)
• peers: (field)
• peers_from_control_nodes: If True, control plane cluster nodes should automatically peer to it. (boolean)

Sorting

To specify that instances are returned in a particular order, use the order_by query string parameter on the GET request.

?order_by=name

Prefix the field name with a dash - to sort in reverse:

?order_by=-name

Multiple sorting fields may be specified by separating the field names with a comma ,:

?order_by=name,some_other_field

Pagination

Use the page_size query string parameter to change the number of results returned for each request. Use the page query string parameter to retrieve a particular page of results.

?page_size=100&page=2

The previous and next links returned with the results will set these query string parameters automatically.

Searching

Use the search query string parameter to perform a case-insensitive search within all designated text fields of a model.

?search=findme

(Added in Ansible Tower 3.1.0) Search across related fields:

?related__search=findme

Request

Supported Media Types

• application/json

Path Parameters

• id(required): string

Query Parameters

• page: integer
  A page number within the paginated result set.
• page_size: integer
  Number of results to return per page.
• search: string
  A search term.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Body ()

Root Schema : schema

Type: object

Show Source

• count(required): integer
• next: string(uri)
• previous: string(uri)
• results(required): array results

{
    "properties":{
        "count":{
            "type":"integer"
        },
        "next":{
            "format":"uri",
            "type":"string",
            "x-nullable":true
        },
        "previous":{
            "format":"uri",
            "type":"string",
            "x-nullable":true
        },
        "results":{
            "items":{
                "$ref":"#/definitions/Instance"
            },
            "type":"array"
        }
    },
    "required":[
        "count",
        "results"
    ],
    "type":"object"
}

Nested Schema : results

Type: array

Show Source

• Array of: object Instance

{
    "items":{
        "$ref":"#/definitions/Instance"
    },
    "type":"array"
}

Nested Schema : Instance

Type: object

Show Source

• capacity: integer
  Title: Capacity

  Read Only: true

  Minimum Value: 0
• capacity_adjustment: string(decimal)
  Title: Capacity adjustment

  Default Value: 1.00
• consumed_capacity: string
  Title: Consumed capacity

  Read Only: true
• cpu: string(decimal)
  Title: Cpu

  Read Only: true
• cpu_capacity: integer
  Title: Cpu capacity

  Read Only: true
• created: string
  Title: Created

  Read Only: true
• enabled: boolean
  Title: Enabled

  Default Value: true
• errors: string
  Title: Errors

  Read Only: true

  Minimum Length: 1

  Any error details from the last health check.
• health_check_pending: string
  Title: Health check pending

  Read Only: true
• health_check_started: string(date-time)
  Title: Health check started

  Read Only: true

  The last time a health check was initiated on this instance.
• hostname(required): string
  Title: Hostname

  Minimum Length: 1

  Maximum Length: 250
• id: integer
  Title: ID

  Read Only: true
• ip_address: string
  Title: Ip address

  Read Only: true

  Minimum Length: 1
• jobs_running: integer
  Title: Jobs running

  Read Only: true

  Count of jobs in the running or waiting state that are targeted for this instance
• jobs_total: integer
  Title: Jobs total

  Read Only: true

  Count of all jobs that target this instance
• last_health_check: string(date-time)
  Title: Last health check

  Read Only: true

  Last time a health check was ran on this instance to refresh cpu, memory, and capacity.
• last_seen: string(date-time)
  Title: Last seen

  Read Only: true

  Last time instance ran its heartbeat task for main cluster nodes. Last known connection to receptor mesh for execution nodes.
• listener_port: integer
  Title: Listener port

  Minimum Value: 0

  Maximum Value: 65535

  Port that Receptor will listen for incoming connections on.
• managed_by_policy: boolean
  Title: Managed by policy

  Default Value: true
• mem_capacity: integer
  Title: Mem capacity

  Read Only: true
• memory: integer
  Title: Memory

  Read Only: true

  Total system memory of this instance in bytes.
• modified: string
  Title: Modified

  Read Only: true
• node_state: string
  Title: Node state

  Default Value: installed

  Allowed Values: [ "provisioning", "provision-fail", "installed", "ready", "unavailable", "deprovisioning", "deprovision-fail" ]

  Indicates the current life cycle stage of this instance.
• node_type: string
  Title: Node type

  Default Value: execution

  Allowed Values: [ "control", "execution", "hybrid", "hop" ]

  Role that this node plays in the mesh.
• peers: array peers
  Unique Items Required: true
• peers_from_control_nodes: boolean
  Title: Peers from control nodes

  If True, control plane cluster nodes should automatically peer to it.
• percent_capacity_remaining: string
  Title: Percent capacity remaining

  Read Only: true
• related: string
  Title: Related

  Read Only: true
• summary_fields: string
  Title: Summary fields

  Read Only: true
• type: string
  Title: Type

  Read Only: true
• url: string
  Title: Url

  Read Only: true
• uuid: string
  Title: Uuid

  Read Only: true

  Minimum Length: 1
• version: string
  Title: Version

  Read Only: true

  Minimum Length: 1

{
    "properties":{
        "capacity":{
            "minimum":"0",
            "readOnly":true,
            "title":"Capacity",
            "type":"integer"
        },
        "capacity_adjustment":{
            "default":"1.00",
            "format":"decimal",
            "title":"Capacity adjustment",
            "type":"string"
        },
        "consumed_capacity":{
            "readOnly":true,
            "title":"Consumed capacity",
            "type":"string"
        },
        "cpu":{
            "format":"decimal",
            "readOnly":true,
            "title":"Cpu",
            "type":"string"
        },
        "cpu_capacity":{
            "readOnly":true,
            "title":"Cpu capacity",
            "type":"integer"
        },
        "created":{
            "readOnly":true,
            "title":"Created",
            "type":"string"
        },
        "enabled":{
            "default":true,
            "title":"Enabled",
            "type":"boolean",
            "x-nullable":true
        },
        "errors":{
            "description":"Any error details from the last health check.",
            "minLength":"1",
            "readOnly":true,
            "title":"Errors",
            "type":"string"
        },
        "health_check_pending":{
            "readOnly":true,
            "title":"Health check pending",
            "type":"string"
        },
        "health_check_started":{
            "description":"The last time a health check was initiated on this instance.",
            "format":"date-time",
            "readOnly":true,
            "title":"Health check started",
            "type":"string",
            "x-nullable":true
        },
        "hostname":{
            "maxLength":"250",
            "minLength":"1",
            "title":"Hostname",
            "type":"string",
            "x-nullable":true
        },
        "id":{
            "readOnly":true,
            "title":"ID",
            "type":"integer"
        },
        "ip_address":{
            "minLength":"1",
            "readOnly":true,
            "title":"Ip address",
            "type":"string",
            "x-nullable":true
        },
        "jobs_running":{
            "description":"Count of jobs in the running or waiting state that are targeted for this instance",
            "readOnly":true,
            "title":"Jobs running",
            "type":"integer"
        },
        "jobs_total":{
            "description":"Count of all jobs that target this instance",
            "readOnly":true,
            "title":"Jobs total",
            "type":"integer"
        },
        "last_health_check":{
            "description":"Last time a health check was ran on this instance to refresh cpu, memory, and capacity.",
            "format":"date-time",
            "readOnly":true,
            "title":"Last health check",
            "type":"string",
            "x-nullable":true
        },
        "last_seen":{
            "description":"Last time instance ran its heartbeat task for main cluster nodes. Last known connection to receptor mesh for execution nodes.",
            "format":"date-time",
            "readOnly":true,
            "title":"Last seen",
            "type":"string",
            "x-nullable":true
        },
        "listener_port":{
            "description":"Port that Receptor will listen for incoming connections on.",
            "maximum":"65535",
            "minimum":"0",
            "title":"Listener port",
            "type":"integer",
            "x-nullable":true
        },
        "managed_by_policy":{
            "default":true,
            "title":"Managed by policy",
            "type":"boolean",
            "x-nullable":true
        },
        "mem_capacity":{
            "readOnly":true,
            "title":"Mem capacity",
            "type":"integer"
        },
        "memory":{
            "description":"Total system memory of this instance in bytes.",
            "readOnly":true,
            "title":"Memory",
            "type":"integer"
        },
        "modified":{
            "readOnly":true,
            "title":"Modified",
            "type":"string"
        },
        "node_state":{
            "default":"installed",
            "description":"Indicates the current life cycle stage of this instance.",
            "enum":[
                "provisioning",
                "provision-fail",
                "installed",
                "ready",
                "unavailable",
                "deprovisioning",
                "deprovision-fail"
            ],
            "title":"Node state",
            "type":"string",
            "x-nullable":true
        },
        "node_type":{
            "default":"execution",
            "description":"Role that this node plays in the mesh.",
            "enum":[
                "control",
                "execution",
                "hybrid",
                "hop"
            ],
            "title":"Node type",
            "type":"string",
            "x-nullable":true
        },
        "peers":{
            "items":{
                "type":"string"
            },
            "type":"array",
            "uniqueItems":true
        },
        "peers_from_control_nodes":{
            "description":"If True, control plane cluster nodes should automatically peer to it.",
            "title":"Peers from control nodes",
            "type":"boolean",
            "x-nullable":true
        },
        "percent_capacity_remaining":{
            "readOnly":true,
            "title":"Percent capacity remaining",
            "type":"string"
        },
        "related":{
            "readOnly":true,
            "title":"Related",
            "type":"string"
        },
        "summary_fields":{
            "readOnly":true,
            "title":"Summary fields",
            "type":"string"
        },
        "type":{
            "readOnly":true,
            "title":"Type",
            "type":"string"
        },
        "url":{
            "readOnly":true,
            "title":"Url",
            "type":"string"
        },
        "uuid":{
            "minLength":"1",
            "readOnly":true,
            "title":"Uuid",
            "type":"string",
            "x-nullable":true
        },
        "version":{
            "minLength":"1",
            "readOnly":true,
            "title":"Version",
            "type":"string",
            "x-nullable":true
        }
    },
    "required":[
        "hostname"
    ],
    "type":"object"
}

Nested Schema : peers

Type: array

Unique Items Required: true

Show Source

• Array of: string

{
    "items":{
        "type":"string"
    },
    "type":"array",
    "uniqueItems":true
}

Back to Top