Oracle Linux Automation Manager CLI and API Reference Guide

List Instances

get

/api/v2/instances/

Make a GET request to this resource to retrieve the list of instances.

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

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.

Response

Supported Media Types

application/json

200 Response

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
}