diff --git a/api-ref/source/v2/agents.inc b/api-ref/source/v2/agents.inc new file mode 100644 index 000000000..8b7108e32 --- /dev/null +++ b/api-ref/source/v2/agents.inc @@ -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 `__. + +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. diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 9754682d1..3a0be4ae3 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -80,3 +80,7 @@ BGP/MPLS VPN Interconnection Logging ####### .. include:: logging.inc +################# +Networking Agents +################# +.. include:: agents.inc diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index 0c6209cec..2cf856fe2 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -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. diff --git a/api-ref/source/v2/samples/agents/agent-show-response.json b/api-ref/source/v2/samples/agents/agent-show-response.json new file mode 100644 index 000000000..4402648bb --- /dev/null +++ b/api-ref/source/v2/samples/agents/agent-show-response.json @@ -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" + } + } + } +} diff --git a/api-ref/source/v2/samples/agents/agent-update-request.json b/api-ref/source/v2/samples/agents/agent-update-request.json new file mode 100644 index 000000000..7b5d8c248 --- /dev/null +++ b/api-ref/source/v2/samples/agents/agent-update-request.json @@ -0,0 +1,5 @@ +{ + "agent": { + "description": "My OVS agent for OpenStack" + } +} diff --git a/api-ref/source/v2/samples/agents/agent-update-response.json b/api-ref/source/v2/samples/agents/agent-update-response.json new file mode 100644 index 000000000..6653ddc62 --- /dev/null +++ b/api-ref/source/v2/samples/agents/agent-update-response.json @@ -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" + } + } + } +} diff --git a/api-ref/source/v2/samples/agents/agents-list-response.json b/api-ref/source/v2/samples/agents/agents-list-response.json new file mode 100644 index 000000000..9b10e5502 --- /dev/null +++ b/api-ref/source/v2/samples/agents/agents-list-response.json @@ -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" + } + } + ] +}