Documenting DHCP agent scheduler

Closes-Bug: #1733364

Change-Id: Ibf854d1f8d6cb80d1d831c070e97274f902d142c
Signed-off-by: Michal Kelner Mishali <mkelnermishal@vmware.com>

api-ref/source/v2/dhcp-agent-scheduler.inc

@@ -0,0 +1,177 @@
+.. -*- rst -*-
+
+====================
+DHCP agent scheduler
+====================
+
+The DHCP agent scheduler extension (``dhcp_agent_scheduler``)
+enables administrators to assign DHCP servers for Neutron networks to given
+Neutron DHCP agents, and retrieve mappings between Neutron networks
+and DHCP agents.
+
+List networks hosted by a DHCP agent
+====================================
+
+.. rest_method::  GET /v2.0/agents/{agent_id}/dhcp-networks
+
+
+Lists networks that a DHCP agent hosts.
+
+Normal response codes: 200
+
+Error response codes: 401, 403
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - agent_id: agent_id-path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - network: network
+   - admin_state_up: network-admin_state_up
+   - availability_zone_hints: availability_zone_hints
+   - availability_zones: availability_zones
+   - created_at: created_at_resource
+   - dns_domain: dns_domain
+   - id: network-id
+   - ipv4_address_scope: ipv4_address_scope
+   - ipv6_address_scope: ipv6_address_scope
+   - l2_adjacency: l2_adjacency
+   - mtu: mtu
+   - name: network-name
+   - port_security_enabled: network-port_security_enabled
+   - project_id: project_id
+   - provider:network_type: provider:network_type
+   - provider:physical_network: provider:physical_network
+   - provider:segmentation_id: provider:segmentation_id
+   - qos_policy_id: qos_policy_id
+   - revision_number: revision_number
+   - router:external: router:external
+   - segments: segments
+   - shared: network-shared
+   - status: network-status
+   - subnets: network-subnets
+   - tenant_id: project_id
+   - updated_at: updated_at_resource
+   - vlan_transparent: vlan_transparent
+   - description: description
+   - is_default: network_is_default
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/agents/agent-dhcp-networks-list-response.json
+   :language: javascript
+
+
+Schedule a network to a DHCP agent
+==================================
+
+.. rest_method::  POST /v2.0/agents/{agent_id}/dhcp-networks
+
+Add a network to a DHCP agent
+
+Normal response codes: 201
+
+Error response codes: 400, 403, 409, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - agent_id: agent_id-path
+   - network_id: network-id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/agents/agent-dhcp-network-add-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+null
+
+Response Example
+----------------
+
+There is no body content for the response of a successful POST request.
+
+
+Remove network from a DHCP agent
+================================
+
+.. rest_method::  DELETE /v2.0/agents/{agent_id}/dhcp-networks/{network_id}
+
+Removes a network from a dhcp agent.
+
+Normal response codes: 204
+
+Error response codes: 401, 403, 404, 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - agent_id: agent_id-path
+   - network_id: network_id
+
+Response Example
+----------------
+
+There is no body content for the response of a successful DELETE request.
+
+
+List DHCP agents hosting a network
+==================================
+
+.. rest_method::  GET /v2.0/networks/{network_id}/dhcp-agents
+
+
+Lists DHCP agents hosting a network.
+
+Normal response codes: 200
+
+Error response codes: 401, 403
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - network_id: network_id
+
+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_resource
+   - description: description
+   - heartbeat_timestamp: heartbeat_timestamp
+   - host: host
+   - id: id
+   - started_at: started_at
+   - topic: topic
+
+Response Example
+----------------
+
+.. literalinclude:: samples/agents/network-dhcp-agent-list-response.json
+   :language: javascript

api-ref/source/v2/index.rst

@@ -86,6 +86,7 @@ Networking Agents
 #################
 .. include:: agents.inc
 .. include:: l3-agent-scheduler.inc
+.. include:: dhcp-agent-scheduler.inc
 #######################
 Auto Allocated Topology
 #######################

api-ref/source/v2/samples/agents/agent-dhcp-network-add-request.json

@@ -0,0 +1 @@
+{"network_id": "1ae075ca-708b-4e66-b4a7-b7698632f05f"}

api-ref/source/v2/samples/agents/agent-dhcp-networks-list-response.json

@@ -0,0 +1,64 @@
+{
+    "networks": [
+        {
+            "admin_state_up": true,
+            "availability_zone_hints": [],
+            "availability_zones": [
+                "nova"
+            ],
+            "created_at": "2016-03-08T20:19:41",
+            "dns_domain": "my-domain.org.",
+            "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
+            "ipv4_address_scope": null,
+            "ipv6_address_scope": null,
+            "l2_adjacency": false,
+            "mtu": 1500,
+            "name": "net1",
+            "port_security_enabled": true,
+            "project_id": "4fd44f30292945e481c7b8a0c8908869",
+            "qos_policy_id": "6a8454ade84346f59e8d40665f878b2e",
+            "revision_number": 1,
+            "router:external": false,
+            "shared": false,
+            "status": "ACTIVE",
+            "subnets": [
+                "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
+            ],
+            "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
+            "updated_at": "2016-03-08T20:19:41",
+            "vlan_transparent": true,
+            "description": "",
+            "is_default": false
+        },
+        {
+            "admin_state_up": true,
+            "availability_zone_hints": [],
+            "availability_zones": [
+                "nova"
+            ],
+            "created_at": "2016-03-08T20:19:41",
+            "dns_domain": "my-domain.org.",
+            "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
+            "ipv4_address_scope": null,
+            "ipv6_address_scope": null,
+            "l2_adjacency": false,
+            "mtu": 1500,
+            "name": "net2",
+            "port_security_enabled": true,
+            "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
+            "qos_policy_id": "bfdb6c39f71e4d44b1dfbda245c50819",
+            "revision_number": 3,
+            "router:external": false,
+            "shared": false,
+            "status": "ACTIVE",
+            "subnets": [
+                "08eae331-0402-425a-923c-34f7cfe39c1b"
+            ],
+            "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
+            "updated_at": "2016-03-08T20:19:41",
+            "vlan_transparent": false,
+            "description": "",
+            "is_default": false
+        }
+    ]
+}

api-ref/source/v2/samples/agents/network-dhcp-agent-list-response.json

@@ -0,0 +1,28 @@
+{
+    "agents": [
+        {
+            "binary": "neutron-dhcp-agent",
+            "description": null,
+            "availability_zone": "nova",
+            "heartbeat_timestamp": "2018-04-08 07:32:42",
+            "admin_state_up": true,
+            "alive": true,
+            "topic": "dhcp_agent",
+            "host": "mkm-instance01",
+            "ha_state": null,
+            "agent_type": "DHCP agent",
+            "resource_versions": {},
+            "created_at": "2018-03-11 08:10:58",
+            "started_at": "2018-03-11 08:10:58",
+            "id": "b64f5c61-2210-41a6-869f-b51d7914511e",
+            "configurations": {
+              "subnets": 1,
+              "dhcp_lease_duration": 86400,
+              "dhcp_driver": "neutron.agent.linux.dhcp.Dnsmasq",
+              "ports": 2,
+              "log_agent_heartbeats": false,
+              "networks": 1
+            }
+        }
+    ]
+}