openstack
/
neutron-lib
Code Issues Proposed changes

add api ref for agents 

This patch adds the api ref for the agents api.

Change-Id: Ie678a23079e4469f43c336e592cb4506d6384992
Closes-Bug: #1639254
This commit is contained in:
Boden R 2017-09-12 15:06:14 -06:00
parent 2ebcd88430
commit 7f3a778acb
7 changed files with 488 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
api-ref/source/v2/agents.inc Normal file
View File

@ -0,0 +1,177 @@
.. -*- rst -*-
======
Agents
======
Lists, shows details for, updates, and deletes agents.
List all agents
===============
.. rest_method:: GET /v2.0/agents
Shows details for an agent.
Use the ``fields`` query parameter to control which fields are
returned in the response body. For information, see `Filtering and
Column Selection <http://specs.openstack.org/openstack/neutron-
specs/specs/api/networking_general_api_information.html#filtering-
and-column-selection>`__.
Normal response codes: 200
Error response codes: 401
Request
-------
.. rest_parameters:: parameters.yaml
- fields: fields
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- admin_state_up: admin_state_up
- agents: agents
- agent_type: agent_type
- alive: alive
- binary: binary
- configurations: configurations
- created_at: created_at
- description: description
- heartbeat_timestamp: heartbeat_timestamp
- host: host
- id: id
- started_at: started_at
- topic: topic
Response Example
----------------
.. literalinclude:: samples/agents/agents-list-response.json
:language: javascript
Show agent details
==================
.. rest_method:: GET /v2.0/agents/{agent_id}
Shows details for an agent.
Normal response codes: 200
Error response codes: 401, 404
Request
-------
.. rest_parameters:: parameters.yaml
- agent_id: agent_id-path
- fields: fields
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- admin_state_up: admin_state_up
- agent: agent
- agent_type: agent_type
- alive: alive
- binary: binary
- configurations: configurations
- created_at: created_at
- description: description
- heartbeat_timestamp: heartbeat_timestamp
- host: host
- id: id
- started_at: started_at
- topic: topic
Response Example
----------------
.. literalinclude:: samples/agents/agent-show-response.json
:language: javascript
Update agent
==============
.. rest_method:: PUT /v2.0/agents/{agent_id}
Updates an agent.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request
-------
.. rest_parameters:: parameters.yaml
- agent_id: agent_id-path
- admin_state_up: admin_state_up-request
- description: description-request
Request Example
---------------
.. literalinclude:: samples/agents/agent-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- admin_state_up: admin_state_up
- agent: agent
- agent_type: agent_type
- alive: alive
- binary: binary
- configurations: configurations
- created_at: created_at
- description: description
- heartbeat_timestamp: heartbeat_timestamp
- host: host
- id: id
- started_at: started_at
- topic: topic
Response Example
----------------
.. literalinclude:: samples/agents/agent-update-response.json
:language: javascript
Delete agent
============
.. rest_method:: DELETE /v2.0/agents/{agent_id}
Agents that won't be used anymore can be removed. Before deleting agents via
API, the agent should be stopped/disabled.
Normal response codes: 204
Error response codes: 401, 404, 409
Request
-------
.. rest_parameters:: parameters.yaml
- agent_id: agent_id-path
Response
--------
There is no body content for the response of a successful DELETE request.

4
api-ref/source/v2/index.rst
View File

@ -80,3 +80,7 @@ BGP/MPLS VPN Interconnection
Logging
#######
.. include:: logging.inc
#################
Networking Agents
#################
.. include:: agents.inc

72
api-ref/source/v2/parameters.yaml
View File

@ -1,6 +1,12 @@
# variables in header
# variables in path
agent_id-path:
description: |
The ID of the agent.
in: path
required: true
type: string
bgpvpn-id-path:
description: |
The ID of the BGP VPN.
@ -562,6 +568,24 @@ admin_state_up_trunk:
in: body
required: false
type: boolean
agent:
description: |
An ``agent`` object.
in: body
required: true
type: object
agent_type:
description: |
The type of agent such as ``Open vSwitch agent`` or ``DHCP agent``.
in: body
required: true
type: string
agents:
description: |
A list of ``agent`` objects.
in: body
required: true
type: array
alias:
description: |
The alias for the extension. For example,
@ -570,6 +594,12 @@ alias:
in: body
required: true
type: string
alive:
description: |
Indicates the agent is alive and running.
in: body
required: true
type: boolean
allowed_address_pairs:
description: |
A set of zero or more allowed address pair objects each where address pair
@ -962,6 +992,13 @@ bgpvpns:
in: body
required: true
type: array
binary:
description: |
The executable command used to start the agent such as
``neutron-openvswitch-agent`` or ``neutron-dhcp-agent``.
in: body
required: true
type: string
binding:host_id:
description: |
The ID of the host where the port resides.
@ -1047,6 +1084,13 @@ cidr:
in: body
required: true
type: string
configurations:
description: |
An object containing configuration specific key/value pairs; the semantics
of which are determined by the binary name and type.
in: body
required: true
type: object
connection_id-body-response:
description: |
The ID of the IPSec site-to-site connection.
@ -1084,7 +1128,7 @@ connection_limit_3:
type: integer
created_at:
description: |
Time at which port has been created.
Time at which the resource was created.
in: body
required: true
type: string
@ -2765,6 +2809,18 @@ healthmonitors_status:
in: body
required: true
type: array
heartbeat_timestamp:
description: |
Time at which the last heartbeat was received.
in: body
required: true
type: string
host:
description: |
The hostname of the system the agent is running on.
in: body
required: true
type: string
http_method:
description: |
The HTTP method that the monitor uses for requests.
@ -5476,6 +5532,12 @@ source_port_1:
in: body
required: true
type: string
started_at:
description: |
Time at which the agent was started.
in: body
required: true
type: string
status_description:
description: |
Human-readable description of the status.
@ -6022,6 +6084,14 @@ timeout:
in: body
required: true
type: integer
topic:
description: |
The name of AMQP topic the agent is listening on such as
``dhcp_agent``. A special value of ``N/A`` is used when the
agent doesn't use an AMQP topic.
in: body
required: true
type: string
total_ips:
description: |
The total number of IP addresses in a network.

53
api-ref/source/v2/samples/agents/agent-show-response.json Normal file
View File

@ -0,0 +1,53 @@
{
"agent": {
"binary": "neutron-openvswitch-agent",
"description": null,
"availability_zone": null,
"heartbeat_timestamp": "2017-09-12 19:40:38",
"admin_state_up": true,
"alive": true,
"id": "04c62b91-b799-48b7-9cd5-2982db6df9c6",
"topic": "N/A",
"host": "agenthost1",
"agent_type": "Open vSwitch agent",
"started_at": "2017-09-12 19:35:38",
"created_at": "2017-09-12 19:35:38",
"configurations": {
"ovs_hybrid_plug": true,
"in_distributed_mode": false,
"datapath_type": "system",
"vhostuser_socket_dir": "/var/run/openvswitch",
"tunneling_ip": "172.16.78.191",
"arp_responder_enabled": false,
"devices": 0,
"ovs_capabilities": {
"datapath_types": [
"netdev",
"system"
],
"iface_types": [
"geneve",
"gre",
"internal",
"ipsec_gre",
"lisp",
"patch",
"stt",
"system",
"tap",
"vxlan"
]
},
"log_agent_heartbeats": false,
"l2_population": false,
"tunnel_types": [
"vxlan"
],
"extensions": [],
"enable_distributed_routing": false,
"bridge_mappings": {
"public": "br-ex"
}
}
}
}

5
api-ref/source/v2/samples/agents/agent-update-request.json Normal file
View File

@ -0,0 +1,5 @@
{
"agent": {
"description": "My OVS agent for OpenStack"
}
}

53
api-ref/source/v2/samples/agents/agent-update-response.json Normal file
View File

@ -0,0 +1,53 @@
{
"agent": {
"binary": "neutron-openvswitch-agent",
"description": "My OVS agent for OpenStack",
"availability_zone": null,
"heartbeat_timestamp": "2017-09-12 19:40:38",
"admin_state_up": true,
"alive": true,
"id": "04c62b91-b799-48b7-9cd5-2982db6df9c6",
"topic": "N/A",
"host": "agenthost1",
"agent_type": "Open vSwitch agent",
"started_at": "2017-09-12 19:35:38",
"created_at": "2017-09-12 19:35:38",
"configurations": {
"ovs_hybrid_plug": true,
"in_distributed_mode": false,
"datapath_type": "system",
"vhostuser_socket_dir": "/var/run/openvswitch",
"tunneling_ip": "172.16.78.191",
"arp_responder_enabled": false,
"devices": 0,
"ovs_capabilities": {
"datapath_types": [
"netdev",
"system"
],
"iface_types": [
"geneve",
"gre",
"internal",
"ipsec_gre",
"lisp",
"patch",
"stt",
"system",
"tap",
"vxlan"
]
},
"log_agent_heartbeats": false,
"l2_population": false,
"tunnel_types": [
"vxlan"
],
"extensions": [],
"enable_distributed_routing": false,
"bridge_mappings": {
"public": "br-ex"
}
}
}
}

125
api-ref/source/v2/samples/agents/agents-list-response.json Normal file
View File

@ -0,0 +1,125 @@
{
"agents": [
{
"binary": "neutron-openvswitch-agent",
"description": null,
"availability_zone": null,
"heartbeat_timestamp": "2017-09-12 19:40:08",
"admin_state_up": true,
"alive": true,
"id":" 04c62b91-b799-48b7-9cd5-2982db6df9c6",
"topic": "N/A",
"host": "agenthost1",
"agent_type": "Open vSwitch agent",
"started_at": "2017-09-12 19:35:38",
"created_at": "2017-09-12 19:35:38",
"configurations": {
"ovs_hybrid_plug": true,
"in_distributed_mode": false,
"datapath_type": "system",
"vhostuser_socket_dir": "/var/run/openvswitch",
"tunneling_ip": "172.16.78.191",
"arp_responder_enabled": false,
"devices": 0,
"ovs_capabilities": {
"datapath_types": [
"netdev",
"system"
],
"iface_types": [
"geneve",
"gre",
"internal",
"ipsec_gre",
"lisp",
"patch",
"stt",
"system",
"tap",
"vxlan"
]
},
"log_agent_heartbeats": false,
"l2_population": false,
"tunnel_types": [
"vxlan"
],
"extensions": [
],
"enable_distributed_routing": false,
"bridge_mappings": {
"public": "br-ex"
}
}
},
{
"binary": "neutron-dhcp-agent",
"description": null,
"availability_zone": "nova",
"heartbeat_timestamp": "2017-09-12 19:39:56",
"admin_state_up": true,
"alive": true,
"id": "840d5d68-5759-4e9e-812f-f3bd19214c7f",
"topic": "dhcp_agent",
"host": "agenthost1",
"agent_type" :"DHCP agent",
"started_at": "2017-09-12 19:35:36",
"created_at": "2017-09-12 19:35:36",
"configurations": {
"subnets": 2,
"dhcp_lease_duration": 86400,
"dhcp_driver": "neutron.agent.linux.dhcp.Dnsmasq",
"networks": 1,
"log_agent_heartbeats": false,
"ports": 3
}
},
{
"binary": "neutron-l3-agent",
"description": null,
"availability_zone": "nova",
"heartbeat_timestamp": "2017-09-12 19:40:08",
"admin_state_up": true,
"alive": true,
"id": "a09b81fc-5a42-46d3-a306-1a5d122a7787",
"topic": "l3_agent",
"host": "agenthost1",
"agent_type": "L3 agent",
"started_at": "2017-09-12 19:35:38",
"created_at": "2017-09-12 19:35:38",
"configurations": {
"agent_mode": "legacy",
"gateway_external_network_id": "",
"handle_internal_only_routers": true,
"routers": 1,
"interfaces": 2,
"floating_ips": 0,
"interface_driver": "openvswitch",
"log_agent_heartbeats": false,
"external_network_bridge": "",
"ex_gw_ports": 1
}
},
{
"binary": "neutron-metadata-agent",
"description": null,
"availability_zone": null,
"heartbeat_timestamp": "2017-09-12 19:40:09",
"admin_state_up": true,
"alive": true,
"id": "c876c9f7-1058-4b9b-90ed-20fb3f905ec4",
"topic": "N/A",
"host": "agenthost1",
"agent_type": "Metadata agent",
"started_at": "2017-09-12 19:35:39",
"created_at": "2017-09-12 19:35:39",
"configurations": {
"log_agent_heartbeats": false,
"nova_metadata_host": "172.16.78.191",
"nova_metadata_port": 8775,
"metadata_proxy_socket": "/opt/stack/data/neutron/metadata_proxy"
}
}
]
}