Working with the Agents control API

Provider Connectivity Assurance API for Sensor Agent Control

IMPORTANT: When querying and changing configuration through the orchestration API, it is highly recommended to use a dedicated service account for this task and not an individual user account. Sensor Agents use JWT tokens for authentication, and these tokens will expire if the user account is deleted.

Overview

The control and orchestration of Sensor Agents is part of the Provider Connectivity Assurance cloud platform in this first release. This means that all control of agents are done using the same API credentials as for other Provider Connectivity Assurance services.
In a later release, it will be possible to deploy these orchestration services also on-prem for local access to the control API and metrics data streams.

API Documentation

All API functions are documented in the AgentServiceV3 section of the
Provider Connectivity Assurance API, see API Documentation for more information.

API Structure and Objects

Each agent, once created and defined in the orchestration API, will be represented with a unique agent object in the system, referred to by its agentId.

Any agent-specific parameters for communication, localization, identification, etc. reside in this configuration block. The agent configuration typically doesn't change but is static for the full lifecycle of the agent once configured.

Each agent also has a status object that can be read through the API. On the status node, the agent reports current version, state, etc. that can be used to check for reachability of the agent.

The API syntax for retreiving these two blocks of information for an agent can be seen below.

Retreive agent status:

GET
https://my.tenant.io/api/orchestrate/v3/agents/<agentId>

Retreive agent configuration:

GET
https://my.tenant.io/api/orchestrate/v3/agents/configuration/<agentId>

Before an agent is deployed, an agent configuration needs to be created on the agent orchestrator. This is also a prerequisite for accessing the SSL secret required for authentication and encryption of the agent communication flows. See Agent Installation Guidelines for information on how to create the initial agent configuration object, retreive the secret through the API, and how to deploy and register your agent.

Typical API Workflow for Agent Control

All agents, sessions and tests are identified with a unique UUID string; this allows for seamless control of an agent, regardless through which Sensor Collector service it is connected, and allows for Provider Connectivity Assurance to keep track of the agent's reported metrics even if the agent name should change.

For each agent, there are typically two parts of configuration that can be defined:

• Agent configuration - these parameters relate to the agent itself, such as metadata for address, region or geocoordinates.
• Test or measurement configuration - these parameters define the characteristics of the test that the agent should perform.

Typical workflow for creating a new test or session

• Look up agentID that should be responsible for the test

Use GET for inventory at /api/orchestrate/v3/agents

• Create a session or test configuration

Example new session object for TWAMP:

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "{{agentId}}",
      "session": {
        "sessionId": "{{sessionId}}",
        "sessionName": "my TWAMP session example 😀",
        "sessionType": "twamp-stateful",
        "enable": true,
        "period": "continuous",
        "twamp": {
            "senderPayloadSize": 82,
            "senderRate": 10,
            "reflectorAddr": "10.122.1.254",
            "reflectorPort": 50862,
            "reportInterval": 10
        }
      }
    }
  }
}

• POST new configuration to API

Send the session configuration to
POST to /api/orchestrate/v3/agents/session

• Optionally start the test if not automatically done

See details for each agent type on these pages:

• Agent: actuate - configuration
• Agent: throughput - configuration
• Agent: trace- Configuration
• Agent: transfer - Configuration