Documenting L3 agent scheduler

Closes-Bug: #1733374

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

api-ref/source/v2/index.rst

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

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

@@ -0,0 +1,165 @@
+.. -*- rst -*-
+
+==================
+L3 agent scheduler
+==================
+
+The L3 agent scheduler extension (``l3_agent_scheduler``) allows administrators
+to assign Neutron routers to Neutron L3 agents, and retrieve mappings between
+Neutron routers and L3 agents.
+
+List routers hosted by an L3 agent
+==================================
+
+.. rest_method::  GET /v2.0/agents/{agent_id}/l3-routers
+
+
+Lists routers that an l3 agent hosts.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - agent_id: agent_id-path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - routers: routers
+   - id: router-id-body
+   - tenant_id: project_id
+   - project_id: project_id
+   - name: name
+   - description: description
+   - admin_state_up: admin_state_up
+   - status: router-status
+   - external_gateway_info: router-external_gateway_info
+   - revision_number: revision_number
+   - routes: router-routes
+   - destination: router-destination
+   - nexthop: router-nexthop
+   - distributed: router-distributed
+   - ha: router-ha
+   - availability_zone_hints: router-availability_zone_hints
+   - availability_zones: router-availability_zones
+   - service_type_id: router-service_type_id
+   - flavor_id: router-flavor_id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../v2/samples/agents/agent-l3-routers-list-response.json
+   :language: javascript
+
+Schedule router to an l3 agent
+==============================
+
+.. rest_method::  POST /v2.0/agents/{agent_id}/l3-routers
+
+Add a router to an l3 agent.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - agent_id: agent_id-path
+   - router_id: router-id-body
+
+Request Example
+---------------
+
+.. literalinclude:: ../v2/samples/agents/agent-l3-router-add-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+null
+
+Response Example
+----------------
+
+There is no body content for the response of a successful POST request.
+
+
+Remove l3 router from an l3 agent
+=================================
+
+.. rest_method::  DELETE /v2.0/agents/{agent_id}/l3-routers/{router_id}
+
+Removes a router from an l3 agent.
+
+Normal response codes: 204
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - agent_id: agent_id-path
+   - router_id: router_id
+
+Response Example
+----------------
+
+There is no body content for the response of a successful DELETE request.
+
+List L3 agents hosting a router
+===============================
+
+.. rest_method::  GET /v2.0/routers/{router_id}/l3-agents
+
+
+Lists l3 agents hosting a specific router.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - router_id: router_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:: ../v2/samples/agents/router-l3-agent-list-response.json
+   :language: javascript

api-ref/source/v2/parameters.yaml

@@ -255,6 +255,12 @@ router_id:
   in: path
   required: true
   type: string
+router_name:
+  description: |
+    The name of the router.
+  in: path
+  required: true
+  type: string
 security_group-id-path:
   description: |
     The ID of the security group.
@@ -1320,6 +1326,7 @@ agent:
   in: body
   required: true
   type: object
+  type: string
 agent_type:
   description: |
     The type of agent such as ``Open vSwitch agent`` or ``DHCP agent``.
@@ -3164,6 +3171,12 @@ insert_before:
   in: body
   required: false
   type: string
+interfaces:
+  description: |
+    Router interfaces
+  in: body
+  required: true
+  type: string
 interval:
   description: |
     The dead peer detection (DPD) interval, in
@@ -3404,6 +3417,12 @@ log:
   in: body
   required: true
   type: object
+log_agent_heartbeats:
+  description: |
+    Log agent heartbeats configuration.
+  in: body
+  required: true
+  type: boolean
 log_enabled:
   description: |
     Indicates whether this log object is enabled or disabled.
@@ -4699,6 +4718,12 @@ resource_target_log_id-request:
   in: body
   required: false
   type: string
+resource_versions:
+  description: |
+    version resource
+  in: body
+  required: true
+  type: string
 resources:
   description: |
     List of resource objects.
@@ -4820,6 +4845,18 @@ router-external_gateway_info-request:
   in: body
   required: false
   type: object
+router-external_gateway_ports:
+  description: |
+    The external gateway ports.
+  in: body
+  required: true
+  type: string
+router-external_network_bridge:
+  description: |
+   Router external network bridge
+  in: body
+  required: true
+  type: string
 router-flavor_id:
   description: |
     The ID of the flavor associated with the router.
@@ -4832,6 +4869,18 @@ router-flavor_id-optional:
   in: body
   required: false
   type: string
+router-floating_ips:
+  description: |
+    Number of floating IPs
+  in: body
+  required: true
+  type: string
+router-gw-port-id:
+  description: |
+    router gateway port ID
+  in: body
+  required: true
+  type: string
 router-ha:
   description: |
     ``true`` indicates a highly-available router.
@@ -4846,12 +4895,38 @@ router-ha-request:
   in: body
   required: false
   type: boolean
+router-ha-vr-id:
+  description: |
+    router VR ID.
+  in: body
+  required: true
+  type: string
+router-ha_state:
+  description: |
+    router ha state.
+  in: body
+  required: true
+  type: string
+router-handle_internal_only_routers:
+  description: |
+    Router configuration to handle internal
+    only routers.
+  in: body
+  required: true
+  type: boolean
 router-id-body:
   description: |
     The ID of the router.
   in: body
   required: true
   type: string
+router-interface_driver:
+  description: |
+    Type of interface driver,
+    i.e. ``neutron.agent.linux.interface.OVSInterfaceDriver``.
+  in: body
+  required: true
+  type: string
 router-network_id:
   description: |
     Network ID which the router gateway is connected to.

api-ref/source/v2/samples/agents/agent-l3-router-add-request.json

@@ -0,0 +1,3 @@
+{
+  "router_id": "43e66290-79a4-415d-9eb9-7ff7919839e1"
+}

api-ref/source/v2/samples/agents/agent-l3-router-remove-request.json

@@ -0,0 +1,3 @@
+{
+  "router_id": "43e66290-79a4-415d-9eb9-7ff7919839e1"
+}

api-ref/source/v2/samples/agents/agent-l3-routers-list-response.json

@@ -0,0 +1,75 @@
+{
+    "routers": [
+        {
+            "admin_state_up": true,
+            "availability_zone_hints": [],
+            "availability_zones": [
+                "nova"
+            ],
+            "description": "",
+            "distributed": false,
+            "external_gateway_info": {
+                "enable_snat": true,
+                "external_fixed_ips": [
+                    {
+                        "ip_address": "172.24.4.3",
+                        "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
+                    },
+                    {
+                        "ip_address": "2001:db8::c",
+                        "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
+                    }
+                ],
+                "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
+            },
+            "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
+            "ha": false,
+            "id": "915a14a6-867b-4af7-83d1-70efceb146f9",
+            "name": "router2",
+            "revision_number": 1,
+            "routes": [
+                {
+                    "destination": "179.24.1.0/24",
+                    "nexthop": "172.24.3.99"
+                }
+            ],
+            "status": "ACTIVE",
+            "project_id": "0bd18306d801447bb457a46252d82d13",
+            "tenant_id": "0bd18306d801447bb457a46252d82d13",
+            "service_type_id": null
+        },
+        {
+            "admin_state_up": true,
+            "availability_zone_hints": [],
+            "availability_zones": [
+                "nova"
+            ],
+            "description": "",
+            "distributed": false,
+            "external_gateway_info": {
+                "enable_snat": true,
+                "external_fixed_ips": [
+                    {
+                        "ip_address": "172.24.4.6",
+                        "subnet_id": "b930d7f6-ceb7-40a0-8b81-a425dd994ccf"
+                    },
+                    {
+                        "ip_address": "2001:db8::9",
+                        "subnet_id": "0c56df5d-ace5-46c8-8f4c-45fa4e334d18"
+                    }
+                ],
+                "network_id": "ae34051f-aa6c-4c75-abf5-50dc9ac99ef3"
+            },
+            "flavor_id": "f7b14d9a-b0dc-4fbe-bb14-a0f4970a69e0",
+            "ha": false,
+            "id": "f8a44de0-fc8e-45df-93c7-f79bf3b01c95",
+            "name": "router1",
+            "revision_number": 1,
+            "routes": [],
+            "status": "ACTIVE",
+            "project_id": "0bd18306d801447bb457a46252d82d13",
+            "tenant_id": "0bd18306d801447bb457a46252d82d13",
+            "service_type_id": null
+        }
+    ]
+}

api-ref/source/v2/samples/agents/router-l3-agent-list-response.json

@@ -0,0 +1,32 @@
+{
+    "agents": [
+        {
+            "binary": "neutron-l3-agent",
+            "description": null,
+            "availability_zone": "nova",
+            "heartbeat_timestamp": "2018-04-08 07:32:42",
+            "admin_state_up": true,
+            "alive": true,
+            "topic": "l3_agent",
+            "host": "mkm-instance01",
+            "ha_state": null,
+            "agent_type": "L3 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": {
+                "agent_mode": "legacy",
+                "gateway_external_network_id": "",
+                "handle_internal_only_routers": true,
+                "routers": 3,
+                "interfaces": 1,
+                "floating_ips": 0,
+                "interface_driver": "openvswitch",
+                "log_agent_heartbeats": false,
+                "external_network_bridge": "",
+                "ex_gw_ports": 1
+            }
+        }
+    ]
+}