Agent Instance

Contains the Agent Catalog instances installed in the Execution Environment.

Schema

Field

Type

Required

Readonly

Auto Managed

Example

id

String

True

True

False

firewall@mysql-server

agent_catalog_id

String

True

True

False

firewall

exec_env_id

String

True

True

False

mysql-server

status

Enum(String)[started, stopped, unknown]

True

True

False

started

operations

List(Operation)

False

True

False

description

String

False

False

False

Collect system metrics from execution environments.

Operation Schema

Field

Type

Required

Readonly

Auto Managed

Example

actions

List(Action)

False

False

False

parameters

List(Parameter)

False

False

False

resources

List(Resource)

False

False

False

Action Schema

Field

Type

Required

Readonly

Auto Managed

Example

id

String

True

True

False

period

output_format

Enum(String)[plain, lines, json]

False

True

False

plain

Parameter Schema

Field

Type

Required

Readonly

Auto Managed

Example

id

String

True

True

False

period

value

String

True

False

False

10s

Resource Schema

Field

Type

Required

Readonly

Auto Managed

Example

id

String

True

True

False

period

content

String

True

False

False

period: 10s

Warning

  • It is not possible to update readonly fields.

  • it is not possible to set the Auto managed fields.

Note

  • id is required but it is auto-generated if not provided. It is recommended to provide a friendly for simplify the retrieve of connected date in other indices. A common syntax is to use agent_catalog_id and exec_env_id concatenated with = ‘@’.

  • agent_catalog_id should be one of those stored in Agent Catalog index.

  • exec_env_id should be one of those stored in Execution Environment index.

Create

To create a new agent instance use the following REST call:

POST /instance/agent/(string: id)

with the request body in JSON format:

POST /instance/agent HTTP/1.1
Host: cb-manager.example.com
Content-Type: application/json

{
    "id": "<agent-instance-id>",
    "agent_catalog_id": "<agent-id>",
    "exec_env_id": "<exec-env-id>",
    "operations": [
        "parameters": [
            {
                "id": "<parameter-id>",
                "value": "<parameter-value>",
            }
        ],
        "actions": [
            {
                "id": "<action-id>",
                "mode": "<action-mode-value>"
            }
        ]
    ]
}
Parameters
  • id – optional agent instance id.

Request Headers
Response Headers
Status Codes

Replace the data with the correct values, for example <agent-instance-id> with “firewall@mysql-server”.

If the creation is correctly executed the response is:

HTTP/1.1 201 Created
Content-Type: application/json

[
    {
        "status": "Created",
        "code": 201,
        "error": false,
        "message": "Agent instance with id=<agent-instance-id> correctly created"
    }
]

Otherwise, if, for example, an agent instance with the given id is already found, this is the response:

HTTP/1.1 406 Not Acceptable
Content-Type: application/json

[
    {
        "status": "Not Acceptable",
        "code": 406,
        "error": true,
        "message": "Id already found"
    }
]

If some required data is missing (for example status), the response could be:

HTTP/1.1 406 Not Acceptable
Content-Type: application/json

[
    {
        "status": "Not Acceptable",
        "code": 406,
        "error": true,
        "message": {
            "status": "required"
        }
    }
]

Read

To get the list of the agent instances:

GET /instance/agent/(string: id)

The response includes all the agent instances.

It is possible to filter the results using the following request body:

GET /instance/agent HTTP/1.1
Host: cb-manager.example.com
Content-Type: application/json

{
    "select": [ "parameters" ],
    "where": {
        "equals": {
            "target:" "id",
            "expr": "<agent-instance-id>"
        }
    }
}

In this way, it will be returned only the parameters of the agent instance with id = “<agent-instance-id>”.

Update

To update an agent instance, use:

PUT /instance/agent/(string: id)
PUT /instance/agent HTTP/1.1
Host: cb-manager.example.com
Content-Type: application/json

{
    "id": "<agent-instance-id}",
    "operations": [
        "parameters": [
            {
                "id": "<parameter-id>",
                "value": "<new-parameter-value>"
            }
        ],
        "actions": [
            {
                "id": "<action-id>",
                "mode": "<new-action-mode-value>"
            }
        ]
    ]
}
Parameters
  • id – optional agent instance id.

Request Headers
Response Headers
Status Codes

This example

  1. updates the value of the parameter with id = “<parameter-id>”;

  2. execute a new action with with id = “<action-id>”

of the agent instance with id = “<agent-instance-id>”.

A possible response is:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "status": "OK",
        "code": 200,
        "error": false,
        "message": "Agent instance with id=<agent-instance-id> correctly updated"
    }
]

Instead, if the are not changes the response is:

HTTP/1.1 304 Not Modified
Content-Type: application/json

[
    {
        "status": "Not Modified",
        "code": 304,
        "error": false,
        "message": "Update for agent instance with id=<agent-instance-id> not necessary"
    }
]

Delete

To delete agent instances, use:

DELETE /instance/agent/(string: id)
DELETE /instance/agent HTTP/1.1
Host: cb-manager.example.com
Content-Type: application/json

{
    "where": {
        "equals": {
            "target:" "id",
            "expr": "<agent-instance-id>"
        }
    }
}
Parameters
  • id – optional agent instance id.

Request Headers
Response Headers
Status Codes

This request removes the agent instance with id = “<agent-instance-id>”.

This is a possible response:

HTTP/1.1 205 Reset Content
Content-Type: application/json

[
    {
        "status": "Reset Content",
        "code": 200,
        "error": false,
        "message": "Agent instance the id=<agent-instance-id> correctly deleted"
    }
]

Caution

Without request body, it removes all the agent instances.