diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/alembic_migration.rst | 102 | ||||
| -rwxr-xr-x | doc/source/api.rst | 626 | ||||
| -rw-r--r-- | doc/source/command_extensions.rst | 64 | ||||
| -rwxr-xr-x | doc/source/conf.py | 76 | ||||
| -rw-r--r-- | doc/source/contribution.rst | 29 | ||||
| -rw-r--r-- | doc/source/index.rst | 66 | ||||
| -rw-r--r-- | doc/source/installation.rst | 37 | ||||
| -rw-r--r-- | doc/source/ovs_driver_and_agent_workflow.rst | 311 | ||||
| -rw-r--r-- | doc/source/system_design and_workflow.rst | 245 | ||||
| -rw-r--r-- | doc/source/usage.rst | 32 |
10 files changed, 1588 insertions, 0 deletions
diff --git a/doc/source/alembic_migration.rst b/doc/source/alembic_migration.rst new file mode 100644 index 0000000..bb225af --- /dev/null +++ b/doc/source/alembic_migration.rst @@ -0,0 +1,102 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Alembic-migration +================= + +Using alembic-migration, required data modeling for networking-sfc is defined and +applied to the database. Refer to `Neutron alembic migration process <http://docs.openstack.org/developer/neutron/devref/alembic_migrations.html>`_ for further details. + +Important operations: +--------------------- + +Checking migration: +~~~~~~~~~~~~~~~~~~~ + +:: + + neutron-db-manage --subproject networking-sfc check_migration + Running branches for networking-sfc ... + start_networking_sfc (branchpoint) + -> 48072cb59133 (contract) (head) + -> 24fc7241aa5 (expand) + + OK + +Checking branch information: +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + neutron-db-manage --subproject networking-sfc branches + Running branches for networking-sfc ... + start_networking_sfc (branchpoint) + -> 48072cb59133 (contract) (head) + -> 24fc7241aa5 (expand) + + OK + +Checking migration history: +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + neutron-db-manage --subproject networking-sfc history + Running history for networking-sfc ... + 9768e6a66c9 -> 5a475fc853e6 (expand) (head), Defining OVS data-model + 24fc7241aa5 -> 9768e6a66c9 (expand), Defining flow-classifier data-model + start_networking_sfc -> 24fc7241aa5 (expand), Defining Port Chain data-model. + start_networking_sfc -> 48072cb59133 (contract) (head), Initial Liberty no-op script. + <base> -> start_networking_sfc (branchpoint), start networking-sfc chain + +Applying changes: +~~~~~~~~~~~~~~~~~ + +:: + + neutron-db-manage --subproject networking-sfc upgrade head + INFO [alembic.runtime.migration] Context impl MySQLImpl. + INFO [alembic.runtime.migration] Will assume non-transactional DDL. + Running upgrade for networking-sfc ... + INFO [alembic.runtime.migration] Context impl MySQLImpl. + INFO [alembic.runtime.migration] Will assume non-transactional DDL. + INFO [alembic.runtime.migration] Running upgrade -> start_networking_sfc, start networking-sfc chain + INFO [alembic.runtime.migration] Running upgrade start_networking_sfc -> 48072cb59133, Initial Liberty no-op script. + INFO [alembic.runtime.migration] Running upgrade start_networking_sfc -> 24fc7241aa5, Defining Port Chain data-model. + INFO [alembic.runtime.migration] Running upgrade 24fc7241aa5 -> 9768e6a66c9, Defining flow-classifier data-model + INFO [alembic.runtime.migration] Running upgrade 9768e6a66c9 -> 5a475fc853e6, Defining OVS data-model + OK + +Checking current version: +~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + neutron-db-manage --subproject networking-sfc current + Running current for networking-sfc ... + INFO [alembic.runtime.migration] Context impl MySQLImpl. + INFO [alembic.runtime.migration] Will assume non-transactional DDL. + 48072cb59133 (head) + 5a475fc853e6 (head) + OK + diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100755 index 0000000..aaa079a --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,626 @@ +.. + Copyright 2015 Futurewei. All rights reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +========= +API Model +========= + +Problem Description +=================== + +Currently Neutron does not support service function chaining. To support +service function chaining, Service VMs must be attached at points in the +network and then traffic must be steered between these attachment +points. Please refer to `Neutron Service Chain blue-print <https://blueprints.launchpad.net/neutron/+spec/neutron-api-extension-for-service-chaining>`_ and Bugs `[1] <https://bugs.launchpad.net/neutron/+bug/1450617>`_ `[2] <https://bugs.launchpad.net/neutron/+bug/1450625>`_ +releated to this specification for more information. + +Proposed Change +=============== + +All Neutron network services and VMs are connected to a Neutron network +via Neutron ports. This makes it possible to create a traffic steering model +for service chaining that uses only Neutron ports. This traffic steering +model has no notion of the actual services attached to these Neutron +ports. + +The service VM hosting the service functions is instantiated and configured, +then VNICs are added to the VM and then these VNICs are attached to the +network by Neutron ports. Once the service function is attached to Neutron +ports, the ports may be included in a "port chain" to allow the service +function to provide treatment to the user's traffic. + +A Port Chain (Service Function Path) consists of: + +* a set of Neutron ports, to define the sequence of service functions +* a set of flow classifiers, to specify the classified traffic flows to + enter the chain + +If a service function has a pair of ports, the first port in +the port-pair is the ingress port of the service function, and the second +port is the egress port of the service function. +If a service function has one bidirectional port, then both ports in +the port-pair have the same value. +A Port Chain is a directional service chain. The first port of the first port-pair +is the head of the service chain. The second port of the last port-pair is the tail +of the service chain. A bidirectional service chain would be composed of two unidirectional Port Chains. + +For example, [{'p1': 'p2'}, {'p3': 'p4'}, {'p5': 'p6'}] represents:: + + +------+ +------+ +------+ + | SF1 | | SF2 | | SF3 | + +------+ +------+ +------+ + p1| |p2 p3| |p4 p5| |P6 + | | | | | | + ->---+ +---------+ +----------+ +----> + +where P1 is the head of the Port Chain and P6 is the tail of the Port Chain, and +SF1 has ports p1 and p2, SF2 has ports p3 and p4, and SF3 has ports p5 and p6. + +In order to create a chain, the user needs to have the actual port objects. +The work flow would typically be: + +a) create the ports +b) create the chain +c) boot the vm's passing the ports as nic's parameters + +The sequence of b) and c) can be switched. + +A SF's Neutron port may be associated with more than one Port Chain to allow +a service function to be shared by multiple chains. + +If there is more than one service function instance of a specific type +available to meet the user's service requirement, their Neutron ports are +included in the port chain as a sub-list. For example, if {p3, p4}, {p7, p8} +are the port-pairs of two FW instances, they +both may be included in a port chain for load distribution as shown below. + + [{'p1': 'p2'}, [{'p3': 'p4'},{'p7': 'p8'}], {'p5': 'p6'}] + +Flow classifiers are used to select the traffic that can +access the chain. Traffic that matches any flow classifier will be +directed to the first port in the chain. The flow classifier will be a generic +independent module and may be used by other projects like FW, QOS, etc. + +A flow classifier cannot be part of two different port-chains otherwise ambiguity +will arise as to which chain path that flow's packets should go. A check will be +made to ensure no ambiguity. But multiple flow classifiers can be associated with +a port chain since multiple different types of flows can request the same service +treatment path. + +CLI Commands + +Syntax:: + + neutron port-pair-create [-h] + [--description <description>] + --ingress <port-id> + --egress <port-id> + [--service-function-parameters <parameter>] PORT-PAIR-NAME + + neutron port-pair-group-create [-h] + [--description <description>] + --port-pairs <port-pair-id> PORT-PAIR-GROUP-NAME + + neutron flow-classifier-create [-h] + [--description <description>] + [--protocol <protocol>] + [--ethertype <Ethertype>] + [--source-port <Minimum source protocol port>:<Maximum source protocol port>] + [--destination-port <Minimum destination protocol port>:<Maximum destination protocol port>] + [--source-ip-prefix <Source IP prefix>] + [--destination-ip-prefix <Destination IP prefix>] + [--logical-source-port <Neutron source port>] + [--logical-destination-port <Neutron destination port>] + [--l7-parameters <L7 parameter>] FLOW-CLASSIFIER-NAME + + neutron port-chain-create [-h] + [--description <description>] + --port-pair-group <port-pair-group-id> + [--flow-classifier <classifier-id>] + [--chain-parameters <chain-parameter>] PORT-CHAIN-NAME + +1. neutron port-chain-create +The port-chain-create returns the ID of the Port Chain. + +Each "port-pair-group" option specifies a type of SF. If a chain consists of a sequence +of different types of SFs, then the chain will have multiple "port-pair-group"s. +There must be at least one "port-pair-group" in the Port Chain. + +The "flow-classifier" option may be repeated to associate multiple flow classifiers +with a port chain, with each classifier identifying a flow. If the flow-classifier is not +specified, then no traffic will be steered through the chain. + +One chain parameter option is currently defined. More parameter options can be added +in future extensions to accommodate new requirements. +The "correlation" parameter is used to specify the type of chain correlation mechanism. +This parameter allows different correlation mechanim to be selected. +This will be set to "mpls" for now to be consistent with current OVS capability. +If this parameter is not specified, it will default to "mpls". + +The port-chain-create command returns the ID of a Port chain. + +A port chain can be created, read, updated and deleted, and when a chain is +created/read/updated/deleted, the options that are involved would be based on +the CRUD in the "Port Chain" resource table below. + +2. neutron port-pair-group-create +Inside each "port-pair-group", there could be one or more port-pairs. +Multiple port-pairs may be included in a "port-pair-group" to allow the specification of +a set of functionally equivalent SFs that can be be used for load distribution, +i.e., the "port-pair" option may be repeated for multiple port-pairs of +functionally equivalent SFs. + +The port-pair-group-create command returns the ID of a Port Pair group. + +3. neutron port-pair-create +A Port Pair represents a service function instance. The ingress port and the +egress port of the service function may be specified. If a service function +has one bidirectional port, the ingress port has the same value as the egress port. +The "service-function-parameter" option allows the passing of SF specific parameter +information to the data path. One parameter option is currently defined. More parameter +options can be added in future extensions to accommodate new requirements. +The "correlation" parameter is used to specify the type of chain correlation mechanism +supported by a specific SF. This is needed by the data plane switch to determine +how to associate a packet with a chain. This will be set to "none" for now since +there is no correlation mechanism supported by the SF. In the future, it can be extended +to include "mpls", "nsh", etc.. If this parameter is not specified, it will default to "none". + +The port-pair-create command returns the ID of a Port Pair. + +4. neutron flow-classifier-create +A combination of the "source" options defines the source of the flow. +A combination of the "destination" options defines the destination of the flow. +The l7_parameter is a place-holder that may be used to support flow classification +using L7 fields, such as URL. If an option is not specified, it will default to wildcard value +except for ethertype which defaults to 'IPv4', for logical-source-port and +logical-destination-port which defaults to none. + +The flow-classifier-create command returns the ID of a flow classifier. + + +Data Model Impact +----------------- + +Data model:: + + +-------+ +----------+ +------------+ + | Port |--------| Port Pair|--------| Port Pairs | + | Chain |* *| Groups | 1 *| | + +-------+ +----------+ +------------+ + |1 + | + |* + +--------------+ + | Flow | + | Classifiers | + +--------------+ + +New objects: + +Port Chain + * id - Port chain ID. + * tenant_id - Tenant ID. + * name - Readable name. + * description - Readable description. + * port_pair_groups - List of port-pair-group IDs. + * flow_classifiers - List of flow-classifier IDs. + * chain_parameters - Dict. of chain parameters. + +Port Pair Group + * id - Port pair group ID. + * tenant_id - Tenant ID. + * name - Readable name. + * description - Readable description. + * port_pairs - List of service function (Neutron) port-pairs. + +Port Pair + * id - Port pair ID. + * tenant_id - Tenant ID. + * name - Readable name. + * description - Readable description. + * ingress - Ingress port. + * egress - Egress port. + * service_function_parameters - Dict. of service function parameters + +Flow Classifier + * id - Flow classifier ID. + * tenant_id - Tenant ID. + * name - Readable name. + * description - Readable description. + * ethertype - Ethertype ('IPv4'/'IPv6'). + * protocol - IP protocol. + * source_port_range_min - Minimum source protocol port. + * source_port_range_max - Maximum source protocol port. + * destination_port_range_min - Minimum destination protocol port. + * destination_port_range_max - Maximum destination protocol port. + * source_ip_prefix - Source IP address or prefix. + * destination_ip_prefix - Destination IP address or prefix. + * logical_source_port - Neutron source port. + * logical_destination_port - Neutron destination port. + * l7_parameters - Dictionary of L7 parameters. + +REST API +-------- + +Port Chain Operations: + ++------------+---------------------------+------------------------------------------+ +|Operation |URL |Description | ++============+===========================+==========================================+ +|POST |/sfc/port_chains |Create a Port Chain | ++------------+---------------------------+------------------------------------------+ +|PUT |/sfc/port_chains/{chain_id}|Update a specific Port Chain | ++------------+---------------------------+------------------------------------------+ +|DELETE |/sfc/port_chains/{chain_id}|Delete a specific Port Chain | ++------------+---------------------------+------------------------------------------+ +|GET |/sfc/port_chains |List all Port Chains for specified tenant | ++------------+---------------------------+------------------------------------------+ +|GET |/sfc/port_chains/{chain_id}|Show information for a specific Port Chain| ++------------+---------------------------+------------------------------------------+ + +Port Pair Group Operations: + ++------------+--------------------------------+-----------------------------------------------+ +|Operation |URL |Description | ++============+================================+===============================================+ +|POST |/sfc/port_pair_groups |Create a Port Pair Group | ++------------+--------------------------------+-----------------------------------------------+ +|PUT |/sfc/port_pair_groups/{group_id}|Update a specific Port Pair Group | ++------------+--------------------------------+-----------------------------------------------+ +|DELETE |/sfc/port_pair_groups/{group_id}|Delete a specific Port Pair Group | ++------------+--------------------------------+-----------------------------------------------+ +|GET |/sfc/port_pair_groups |List all Port Pair Groups for specified tenant | ++------------+--------------------------------+-----------------------------------------------+ +|GET |/sfc/port_pair_groups/{group_id}|Show information for a specific Port Pair | ++------------+--------------------------------+-----------------------------------------------+ + +Port Pair Operations: + ++------------+-------------------------+------------------------------------------+ +|Operation |URL |Description | ++============+=========================+==========================================+ +|POST |/sfc/port_pairs |Create a Port Pair | ++------------+-------------------------+------------------------------------------+ +|PUT |/sfc/port_pairs/{pair_id}|Update a specific Port Pair | ++------------+-------------------------+------------------------------------------+ +|DELETE |/sfc/port_pairs/{pair_id}|Delete a specific Port Pair | ++------------+-------------------------+------------------------------------------+ +|GET |/sfc/port_pairs |List all Port Pairs for specified tenant | ++------------+-------------------------+------------------------------------------+ +|GET |/sfc/port_pairs/{pair_id}|Show information for a specific Port Pair | ++------------+-------------------------+------------------------------------------+ + +Flow Classifier Operations: + ++------------+-------------------------------+------------------------------------------------+ +|Operation |URL |Description | ++============+===============================+================================================+ +|POST |/sfc/flow_classifiers |Create a Flow-classifier | ++------------+-------------------------------+------------------------------------------------+ +|PUT |/sfc/flow_classifiers/{flow_id}|Update a specific Flow-classifier | ++------------+-------------------------------+------------------------------------------------+ +|DELETE |/sfc/flow_classifiers/{flow_id}|Delete a specific Flow-classifier | ++------------+-------------------------------+------------------------------------------------+ +|GET |/sfc/flow_classifiers |List all Flow-classifiers for specified tenant | ++------------+-------------------------------+------------------------------------------------+ +|GET |/sfc/flow_classifiers/{flow_id}|Show information for a specific Flow-classifier | ++------------+-------------------------------+------------------------------------------------+ + +REST API Impact +--------------- + +The following new resources will be created as a result of the API handling. + +Port Chain resource: + ++----------------+----------+--------+---------+----+-------------------------+ +|Attribute |Type |Access |Default |CRUD|Description | +|Name | | |Value | | | ++================+==========+========+=========+====+=========================+ +|id |uuid |RO, all |generated|R |Port Chain ID. | ++----------------+----------+--------+---------+----+-------------------------+ +|tenant_id |uuid |RO, all |from auth|CR |Tenant ID. | +| | | |token | | | ++----------------+----------+--------+---------+----+-------------------------+ +|name |string |RW, all |'' |CRU |Port Chain name. | ++----------------+----------+--------+---------+----+-------------------------+ +|description |string |RW, all |'' |CRU |Port Chain description. | ++----------------+----------+--------+---------+----+-------------------------+ +|port_pair_groups|list(uuid)|RW, all |N/A |CR |List of port-pair-groups.| ++----------------+----------+--------+---------+----+-------------------------+ +|flow_classifiers|list(uuid)|RW, all |[] |CRU |List of flow-classifiers.| ++----------------+----------+--------+---------+----+-------------------------+ +|chain_parameters|dict |RW, all |mpls |CR |Dict. of parameters: | +| | | | | |'correlation':String | ++----------------+----------+--------+---------+----+-------------------------+ + +Port Pair Group resource: + ++-----------+--------+---------+---------+----+---------------------+ +|Attribute |Type |Access |Default |CRUD|Description | +|Name | | |Value | | | ++===========+========+=========+=========+====+=====================+ +|id |uuid |RO, all |generated|R |Port pair group ID. | ++-----------+--------+---------+---------+----+---------------------+ +|tenant_id |uuid |RO, all |from auth|CR |Tenant ID. | +| | | |token | | | ++-----------+--------+---------+---------+----+---------------------+ +|name |string |RW, all |'' |CRU |Port pair group name.| ++-----------+--------+---------+---------+----+---------------------+ +|description|string |RW, all |'' |CRU |Port pair group | +| | | | | |description. | ++-----------+--------+---------+---------+----+---------------------+ +|port_pairs |list |RW, all |N/A |CRU |List of port-pairs. | ++-----------+--------+---------+---------+----+---------------------+ + +Port Pair resource: + ++---------------------------+--------+---------+---------+----+----------------------+ +|Attribute Name |Type |Access |Default |CRUD|Description | ++===========================+========+=========+=========+====+======================+ +|id |uuid |RO, all |generated|R |Port pair ID. | ++---------------------------+--------+---------+---------+----+----------------------+ +|tenant_id |uuid |RO, all |from auth|CR |Tenant ID. | +| | | |token | | | ++---------------------------+--------+---------+---------+----+----------------------+ +|name |string |RW, all |'' |CRU |Port pair name. | ++---------------------------+--------+---------+---------+----+----------------------+ +|description |string |RW, all |'' |CRU |Port pair description.| ++---------------------------+--------+---------+---------+----+----------------------+ +|ingress |uuid |RW, all |N/A |CR |Ingress port ID. | ++---------------------------+--------+---------+---------+----+----------------------+ +|egress |uuid |RW, all |N/A |CR |Egress port ID. | ++---------------------------+--------+---------+---------+----+----------------------+ +|service_function_parameters|dict |RW, all |None |CR |Dict. of parameters: | +| | | | | |'correlation':String | ++---------------------------+--------+---------+---------+----+----------------------+ + +Flow Classifier resource: + ++--------------------------+--------+---------+---------+----+-----------------------+ +|Attribute Name |Type |Access |Default |CRUD|Description | +| | | |Value | | | ++==========================+========+=========+=========+====+=======================+ +|id |uuid |RO, all |generated|R |Flow-classifier ID. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|tenant_id |uuid |RO, all |from auth|CR |Tenant ID. | +| | | |token | | | ++--------------------------+--------+---------+---------+----+-----------------------+ +|name |string |RW, all |'' |CRU |Flow-classifier name. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|description |string |RW, all |'' |CRU |Flow-classifier | +| | | | | |description. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|ethertype |string |RW, all |'IPv4' |CR |L2 ethertype. Can be | +| | | | | |'IPv4' or 'IPv6' only. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|protocol |string |RW, all |Any |CR |IP protocol name. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|source_port_range_min |integer |RW, all |Any |CR |Minimum source | +| | | | | |protocol port. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|source_port_range_max |integer |RW, all |Any |CR |Maximum source | +| | | | | |protocol port. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|destination_port_range_min|integer |RW, all |Any |CR |Minimum destination | +| | | | | |protocol port. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|destination_port_range_max|integer |RW, all |Any |CR |Maximum destination | +| | | | | |protocol port. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|source_ip_prefix |CIDR |RW, all |Any |CR |Source IPv4 or IPv6 | +| | | | | |prefix. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|destination_ip_prefix |CIDR |RW, all |Any |CR |Destination IPv4 or | +| | | | | |IPv6 prefix. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|logical_source_port |uuid |RW, all |None |CR |Neutron source port. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|logical_destination_port |uuid |RW, all |None |CR |Neutron destination | +| | | | | |port. | ++--------------------------+--------+---------+---------+----+-----------------------+ +|l7_parameters |dict |RW, all |Any |CR |Dict. of L7 parameters.| ++--------------------------+--------+---------+---------+----+-----------------------+ + +Json Port-pair create request example:: + + {"port_pair": {"name": "SF1", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Firewall SF instance", + "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1", + "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345", + } + } + + {"port_pair": {"name": "SF2", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Loadbalancer SF instance", + "ingress": "797f899e-73d4-11e5-b392-2c27d72acb4c", + "egress": "797f899e-73d4-11e5-b392-2c27d72acb4c", + } + } + +Json Port-pair create response example:: + + {"port_pair": {"name": "SF1", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Firewall SF instance", + "ingress": "dace4513-24fc-4fae-af4b-321c5e2eb3d1", + "egress": "aef3478a-4a56-2a6e-cd3a-9dee4e2ec345", + "id": "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae", + } + } + + {"port_pair": {"name": "SF2", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Loadbalancer SF instance", + "ingress": "797f899e-73d4-11e5-b392-2c27d72acb4c", + "egress": "797f899e-73d4-11e5-b392-2c27d72acb4c", + "id": "d11e9190-73d4-11e5-b392-2c27d72acb4c" + } + } + +Json Port Pair Group create request example:: + + {"port_pair_group": {"name": "Firewall_PortPairGroup", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Grouping Firewall SF instances", + "port_pairs": [ + "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae" + ] + } + } + + {"port_pair_group": {"name": "Loadbalancer_PortPairGroup", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Grouping Loadbalancer SF instances", + "port_pairs": [ + "d11e9190-73d4-11e5-b392-2c27d72acb4c" + ] + } + } + +Json Port Pair Group create response example:: + + {"port_pair_group": {"name": "Firewall_PortPairGroup", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Grouping Firewall SF instances", + "port_pairs": [ + "78dcd363-fc23-aeb6-f44b-56dc5e2fb3ae + ], + "id": "4512d643-24fc-4fae-af4b-321c5e2eb3d1", + } + } + + {"port_pair_group": {"name": "Loadbalancer_PortPairGroup", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Grouping Loadbalancer SF instances", + "port_pairs": [ + "d11e9190-73d4-11e5-b392-2c27d72acb4c" + ], + "id": "4a634d49-76dc-4fae-af4b-321c5e23d651", + } + } + +Json Flow Classifier create request example:: + + {"flow_classifier": {"name": "FC1", + "tenant_id": "1814726e2d22407b8ca76db5e567dcf1", + "description": "Flow rule for classifying TCP traffic", + "protocol": "TCP", + "source_port_range_min": 22, "source_port_range_max": 4000, + "destination_port_range_min": 80, "destination_port_range_max": 80, + "source_ip_prefix": null, "destination_ip_prefix": "22.12.34.45" + } + } + + {"flow_classifier": {"name": "FC2", + "tenant_id": "1814726e2d22407b8ca76db5e567dcf1", + "description": "Flow rule for classifying UDP traffic", + "protocol": "UDP", + "source_port_range_min": 22, "source_port_range_max": 22, + "destination_port_range_min": 80, "destination_port_range_max": 80, + "source_ip_prefix": null, "destination_ip_prefix": "22.12.34.45" + } + } + +Json Flow Classifier create response example:: + + {"flow_classifier": {"name": "FC1", + "tenant_id": "1814726e2d22407b8ca76db5e567dcf1", + "description": "Flow rule for classifying TCP traffic", + "protocol": "TCP", + "source_port_range_min": 22, "source_port_range_max": 4000, + "destination_port_range_min": 80, "destination_port_range_max": 80, + "source_ip_prefix": null , "destination_ip_prefix": "22.12.34.45", + "id": "4a334cd4-fe9c-4fae-af4b-321c5e2eb051" + } + } + + {"flow_classifier": {"name": "FC2", + "tenant_id": "1814726e2d22407b8ca76db5e567dcf1", + "description": "Flow rule for classifying UDP traffic", + "protocol": "UDP", + "source_port_range_min": 22, "source_port_range_max": 22, + "destination_port_range_min": 80, "destination_port_range_max": 80, + "source_ip_prefix": null , "destination_ip_prefix": "22.12.34.45", + "id": "105a4b0a-73d6-11e5-b392-2c27d72acb4c" + } + } + +Json Port Chain create request example:: + + {"port_chain": {"name": "PC1", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Steering TCP and UDP traffic first to Firewall and then to Loadbalancer", + "flow_classifiers": [ + "4a334cd4-fe9c-4fae-af4b-321c5e2eb051", + "105a4b0a-73d6-11e5-b392-2c27d72acb4c" + ], + "port_pair_groups": [ + "4512d643-24fc-4fae-af4b-321c5e2eb3d1", + "4a634d49-76dc-4fae-af4b-321c5e23d651" + ], + } + } + +Json Port Chain create response example:: + + {"port_chain": {"name": "PC2", + "tenant_id": "d382007aa9904763a801f68ecf065cf5", + "description": "Steering TCP and UDP traffic first to Firewall and then to Loadbalancer", + "flow_classifiers": [ + "4a334cd4-fe9c-4fae-af4b-321c5e2eb051", + "105a4b0a-73d6-11e5-b392-2c27d72acb4c" + ], + "port_pair_groups": [ + "4512d643-24fc-4fae-af4b-321c5e2eb3d1", + "4a634d49-76dc-4fae-af4b-321c5e23d651" + ], + "id": "1278dcd4-459f-62ed-754b-87fc5e4a6751" + } + } + + +Implementation +============== + +Assignee(s) +----------- +Authors of the Specification and Primary contributors: + * Cathy Zhang (cathy.h.zhang@huawei.com) + * Louis Fourie (louis.fourie@huawei.com) + +Other contributors: + * Vikram Choudhary (vikram.choudhary@huawei.com) + * Swaminathan Vasudevan (swaminathan.vasudevan@hp.com) + * Yuji Azama (yuj-azama@rc.jp.nec.com) + * Mohan Kumar (nmohankumar1011@gmail.com) + * Ramanjaneya (ramanjieee@gmail.com) + * Stephen Wong (stephen.kf.wong@gmail.com) + * Nicolas Bouthors (Nicolas.BOUTHORS@qosmos.com) + * Akihiro Motoki <amotoki@gmail.com> + * Paul Carver <pcarver@att.com> + diff --git a/doc/source/command_extensions.rst b/doc/source/command_extensions.rst new file mode 100644 index 0000000..abb4096 --- /dev/null +++ b/doc/source/command_extensions.rst @@ -0,0 +1,64 @@ +.. + Copyright 2015 Futurewei. All rights reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +================= +Command extension +================= + +Networking-sfc uses python-neutronclient's existing command extension framework +for adding required command lines for realizing service function chaining +functionality. Refer to `Python-neutronclient command extension <http://docs.openstack.org/developer/python-neutronclient/devref/client_command_extensions.html>`_ for further details. + + +List of New Neutron CLI Commands: +--------------------------------- +Below listed command lines are introduced for realizing service function chaining. + +:: + + flow-classifier-create Create a flow-classifier. + flow-classifier-delete Delete a given flow-classifier. + flow-classifier-list List flow-classifiers that belong to a given tenant. + flow-classifier-show Show information of a given flow-classifier. + flow-classifier-update Update flow-classifier information. + + port-pair-create Create a port-pair. + port-pair-delete Delete a given port-pair. + port-pair-list List port-pairs that belongs to a given tenant. + port-pair-show Show information of a given port-pair. + port-pair-update Update port-pair's information. + + port-pair-group-create Create a port-pair-group. + port-pair-group-delete Delete a given port-pair-group. + port-pair-group-list List port-pair-groups that belongs to a given tenant. + port-pair-group-show Show information of a given port-pair-group. + port-pair-group-update Update port-pair-group's information. + + port-chain-create Create a port-chain. + port-chain-delete Delete a given port-chain. + port-chain-list List port-chains that belong to a given tenant. + port-chain-show Show information of a given port-chain. + port-chain-update Update port-chain's information. + diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100755 index 0000000..e70c181 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,76 @@ +# Copyright 2015 Futurewei. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + #'sphinx.ext.intersphinx', + 'oslosphinx' +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'networking-sfc' +copyright = u'2013, OpenStack Foundation' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Foundation', 'manual'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/contribution.rst b/doc/source/contribution.rst new file mode 100644 index 0000000..852aa97 --- /dev/null +++ b/doc/source/contribution.rst @@ -0,0 +1,29 @@ +.. + Copyright 2015 Futurewei. All rights reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +============ +Contribution +============ +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..da33019 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,66 @@ +.. + Copyright 2015 Futurewei. All rights reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Welcome to the Service Function Chaining Documentation! +======================================================= +.. include:: ../../README.rst + + +=============== +Developer Guide +=============== + +In the Developer Guide, you will find information on Networking-SFC lower level +programming APIs. There are sections that cover the core pieces of networking-sfc, +including its api, command-lines, database, system-design, alembic-migration etc. +There are also subsections that describe specific plugins inside networking-sfc. +Finally, the developer guide includes information about testing infrastructure. + +Programming HowTos and Tutorials +-------------------------------- +.. toctree:: + :maxdepth: 2 + + installation + usage + contribution + +Networking-SFC Internals +------------------------ +.. toctree:: + :maxdepth: 2 + + api + system_design and_workflow + ovs_driver_and_agent_workflow + command_extensions + alembic_migration + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000..bf133b0 --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,37 @@ +.. + Copyright 2015 Futurewei. All rights reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +============ +Installation +============ + +At the command line:: + + $ pip install networking-sfc + +Or, if you have virtualenvwrapper installed:: + + $ mkvirtualenv networking-sfc + $ pip install networking-sfc diff --git a/doc/source/ovs_driver_and_agent_workflow.rst b/doc/source/ovs_driver_and_agent_workflow.rst new file mode 100644 index 0000000..d8cda09 --- /dev/null +++ b/doc/source/ovs_driver_and_agent_workflow.rst @@ -0,0 +1,311 @@ +.. + Copyright 2015 Futurewei. All rights reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +============================= +OVS Driver and Agent Workflow +============================= + +Blueprint about `Common Service chaining driver <https://blueprints.launchpad.net/neutron/+spec/common-service-chaining-driver-api>`_ describes the OVS driver and agent necessity for realizing service function chaining. + +Problem Description +=================== + +The service chain OVS driver and agents are used to configure back-end +Openvswitch devices to render service chaining in the data-plane. The driver +manager controls a common service chain API which provides a consistent interface +between the service chain manager and different device drivers. + +Proposed Change +=============== + + +Design:: + + Port Chain Plugin + +-------------------------------+ + | +-------------------------+ | + | | Port Chain API | | + | +-------------------------+ | + | | Port Chain Database | | + | +-------------------------+ | + | | Driver Manager | | + | +-------------------------+ | + | | Common Driver API | | + | +-------------------------+ | + | | | + | +-------------------------+ | + | | OVS Driver | | + | +-------------------------+ | + +-------|----------------|------+ + |rpc |rpc + +-----------+ +-----------+ + | OVS Agent | | OVS Agent | + +-----------+ +-----------+ + +A OVS service chain driver and agents communicate via rpc. + +OVS Driver +---------- +The OVS Driver is extended to support service chaining. The driver interfaces +with the OVS agents that reside on each Compute node. The OVS driver is responsible +for the following: + +* Identify the OVS agents that directly connects to the SF instances and establish + communication with OVS agents on the Compute nodes. +* Send commands to the OVS agents to create bridges, flow tables and flows to steer + chain traffic to the SF instances. + +OVS Agent +--------- +The OVS agent will manage the OVS using OVSDB commands to create bridges and tables, +and install flows to steer chain traffic to the SF instances. + +Existing tunnels between the Tunnel bridges on each Compute node are used to +transport Port Chain traffic between the CNs. + +The OVS Agent will create these tunnels to transport SFC traffic between Compute +nodes on which there are SFs. Each tunnel port has the following attributes: + +* Name +* Local tunnel IP address +* Remote tunnel IP address +* Tunnel Type: VXLAN, GRE + +The OVS agent installs additional flows on the Integration bridge and the Tunnel bridge +to perform the following functions: + +* Traffic classification. The Integration bridge classifies traffic from a VM port or + Service VM port attached to the Integration bridge. The flow classification is based on + the n-tuple rules. +* Service function forwarding. The Tunnel bridge forwards service chain + packets to the next-hop Compute node via tunnels, or to the next Service VM port + on that Compute node. Integration bridge will terminate a Service Function Path. + +The OVS Agent will use the MPLS header to transport the chain path identifier +and chain hop index. The MPLS label will transport the chain path identifier, +and the MPLS ttl will transport the chain hop index. The following packet encapsulation +will be used:: + + IPv4 Packet: + +----------+------------------------+-------+ + |L2 header | IP + UDP dst port=4790 | VXLAN | + +----------+------------------------+-------+ + -----------------------------+---------------+--------------------+ + Original Ethernet, ET=0x8847 | MPLS header | Original IP Packet | + -----------------------------+---------------+--------------------+ + +This is not intended as a general purpose MPLS implementation but rather as a +temporary internal mechanism. It is anticipated that the MPLS label will be +replaced with an NSH encapsulation +(https://datatracker.ietf.org/doc/draft-ietf-sfc-nsh/) once NSH support is +available upstream in Open vSwitch. If the service function does not support +the header, then the vSwitch will act as Service Function Forwarder (SFF) +Proxy which will strip off the header when forwarding the packet to the SF +and re-add the header when receiving the packet from the SF. + +OVS Bridge and Tunnel +--------------------- +Existing tunnels between the Tunnel bridges on each Compute node are used to +transport Port Chain traffic between the CNs:: + + CN1 CN2 + +--------------------------+ +-------------------------+ + | +-----+ +-----+ | | +-----+ +-----+ | + | | VM1 | | SF1 | | | | SF2 | | SF3 | | + | +-----+ +-----+ | | +-----+ +-----+ | + | |. ^|. | | ^| |. ^|. | + | +----.-----------.-.--+ | | +-.---.---------.-.---+ | + | | ............. .. | | | | . ........... . | | + | | Integration Bridge. | | | | .Integration Bridge | | + | | ......... | | | | ...... ........ | | + | +-----------.---------+ | | +-------.--.----------+ | + | |. | | .| . | + | +-----------.---------+ | | +-------.--.----------+ | + | | ................................. ..................> + | | Tunnel Bridge |-------------| Tunnel Bridge | | + | +---------------------+ | Tunnel | +---------------------+ | + | | | | + +--------------------=-----+ +-------------------------+ + + + +Flow Tables and Flow Rules +-------------------------- +The OVS Agent adds additional flows (shown above) on the Integration bridge to support +Port Chains: + +1. Egress Port Chain flows to steer traffic from SFs attached to the Integration bridge to a + Tunnel bridge to the next-hop Compute node. These flows may be handled using the OpenFlow + Group in the case where there are multiple port-pairs in the next-hop port-pair group. +2. Ingress Port Chain flows on the Tunnel bridge to steer service chain traffic from a + tunnel from a previous Compute node to SFs attached to the Integration bridge. +3. Internal Port Chain flows are used to steer service chain traffic from one SF to another SF + on the same Compute Node. + +The Port Chain flow rules have the higher priority, and will not impact +the existing flow rules on the Integration bridge. If traffic from SF is not part of +a service chain, e.g., DHCP messages, ARP packets etc., it will match the existing +flow rules on the Integration bridge. + +The following tables are used to process Port Chain traffic: + +* Local Switching Table (Table 0). This existing table has two new flows to handle + incoming traffic from the SF egress port and the tunnel port between Compute nodes. + +* Group Table. This new table is used to select multiple paths for load-balancing across + multiple port-pairs in a port-pair group. There are multiple buckets in the group if the next + hop is a port-pair group with multiple port-pairs. The group actions will be to send the packet + to next hop SF instance. + If the next hop port-pair is on another Compute node, the action output to the tunnel port to the + next hop Compute node. If the next hop port-pair is on the same Compute node, then the + action will be to resubmit to the TUN_TABLE for local chaining process. + +Local Switching Table (Table 0) Flows +------------------------------------- +Traffic from SF Egress port: classify for chain and direct to group:: + + priority=10,in_port=SF_EGRESS_port,traffic_match_field, + actions=strip_vlan,set_tunnel:VNI,group:gid. + +Traffic from Tunnel port:: + + priority=10,in_port=TUNNEL_port, + actions=resubmit(,TUN_TABLE[type]). + + +Group Table Flows +----------------- +The Group table is used for load distribution to spread the traffic load across a port-pair group of +multiple port-pairs (SFs of the same type). This uses the hashing of several fields in the packet. +There are multiple buckets in the group if the next hop is a port-pair group with multiple port-pairs. + +The group actions will be to send the packet to next hop SF instances. If the next hop port-pair +is on another Compute node, the action output to the tunnel port to the next hop Compute node. +If the next hop port-pair is on the same Compute node, then the action will be to resubmit +to the TUN_TABLE for local chaining process. + +The OVSDB command to create a group of type Select with a hash selection method and two buckets +is shown below. This is existing OVS functionality. The ip_src,nw_proto,tp_src packet fields are +used for the hash:: + + group_id=gid,type=select,selection_method=hash,fields=ip_src,nw_proto,tp_src + bucket=set_field:10.1.1.3->ip_dst,output:10, + bucket=set_field:10.1.1.4->ip_dst,output:10 + + +Data Model Impact +----------------- +None + +Alternatives +------------ + +None + +Security Impact +--------------- + +None. + +Notifications Impact +-------------------- + +There will be logging to trouble-shoot and verify correct operation. + +Other End User Impact +--------------------- + +None. + +Performance Impact +------------------ + +It is not expected that these flows will have a significant performance impact. + +IPv6 Impact +----------- + +None. + +Other Deployer Impact +--------------------- + +None + +Developer Impact +---------------- + +None + +Community Impact +---------------- + +Existing OVS driver and agent functionality will not be affected. + +Implementation +============== + +Assignee(s) +----------- + +* Cathy Zhang (cathy.h.zhang@huawei.com) +* Louis Fourie (louis.fourie@huawei.com) +* Stephen Wong (stephen.kf.wong@gmail.com) + +Work Items +---------- + +* Port Chain OVS driver. +* Port Chain OVS agent. +* Unit test. + +Dependencies +============ + +This design depends upon the proposed `Neutron Service Chaining API extensions <https://blueprints.launchpad.net/neutron/+spec/neutron-api-extension-for-service-chaining>`_ + +Openvswitch. + +Testing +======= + +Tempest and functional tests will be created. + +Documentation Impact +==================== + +Documented as extension. + +User Documentation +------------------ + +Update networking API reference. +Update admin guide. + +Developer Documentation +----------------------- + +None + diff --git a/doc/source/system_design and_workflow.rst b/doc/source/system_design and_workflow.rst new file mode 100644 index 0000000..11e0849 --- /dev/null +++ b/doc/source/system_design and_workflow.rst @@ -0,0 +1,245 @@ +.. + Copyright 2015 Futurewei. All rights reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +========================== +System Design and Workflow +========================== + +Problem Description +=================== +The `Service Chaining API specification <http://docs.openstack.org/developer/networking-sfc/api.html>`_ proposes a Neutron port based solution for setting up a service chain. A specification on the system architecture and related API work flow is needed to guide the code design. + +System Architecture +============================ +The following figure shows the generic architecture of the Port Chain +Plugin. As shown in the diagram, Port Chain Plugin can be backed by +different service providers such as OVS Driver and/or different types of +SDN Controller Drivers. Through the "Common Driver API", these +different drivers can provide different implementations for the service +chain path rendering. In the first release and deployment based on this +release, we will only deliver codes for the OVS driver. In the next release, +we can add codes to support multiple active drivers:: + + Port Chain Plugin With Different Types of Drivers + +-----------------------------------------------------------------+ + | +-----------------------------------------------------------+ | + | | Port Chain API | | + | +-----------------------------------------------------------+ | + | | Port Chain Database | | + | +-----------------------------------------------------------+ | + | | Driver Manager | | + | +-----------------------------------------------------------+ | + | | Common Driver API | | + | +-----------------------------------------------------------+ | + | | | + | +------------+------------------------+---------------------+ | + | | OVS Driver | Controller Driver1 | Controller Driver2 | | + | +------------+------------------------+---------------------+ | + +-------|------------------|-------------------------|------------+ + | | | + +-----------+ +-----------------+ +-----------------+ + | OVS Agent | | SDN Controller1 | | SDN Controller2 | + +-----------+ +-----------------+ +-----------------+ + +The second figure below shows the reference implementation architecture, +which is through the OVS Driver path. The figure shows the components +that will be added on the Neutron Server and the compute nodes to +support this Neutron Based SFC functionality. As shown in the diagram, +a new Port Chain Plugin will be added to the Neutron Server. +The existing "OVS Driver" and "OVS Agent" will be extended to support +the service chain functionality. The OVS Driver will communicate with +each OVS Agent to program its OVS forwarding table properly so that a +tenant's traffic flow can be steered through the user defined sequence +of Neutron ports to get the desired service treatment from the Service +Function running on the VMs. + +A separate `OVS Driver and Agent specification <http://docs.openstack.org/developer/networking-sfc/portchain-ovs-driver-agent.html>`_ will describe in more +detail on the design consideration of the Driver, Agent, and how to set up the +classification rules on the OVS to identify different flows and how to +set up the OVS forwarding table. In the reference implementation, the OVS Driver +communicates with OVS Agent through RPC to program the OVS. The communication +between the OVS Agent and the OVS is through OVSDB/Openflow:: + + + Port Chain Plugin With OVS Driver + +-------------------------------+ + | +-------------------------+ | + | | Port Chain API | | + | +-------------------------+ | + | | Port Chain Database | | + | +-------------------------+ | + | | Driver Manager | | + | +-------------------------+ | + | | Common Driver API | | + | +-------------------------+ | + | | | + | +-------------------------+ | + | | OVS Driver | | + | +-------------------------+ | + +-------|----------------|------+ + | | + +-----------+ +-----------+ + | OVS Agent | | OVS Agent | + +-----------+ +-----------+ + +Port Chain Creation Workflow +============================ +The following example shows how the Neutron CLI commands may be used to +create a port-chain consisting of a service VM vm1 and a service VM +vm2. The user can be an Admin/Tenant or an Application built on top. + +Traffic flow into the Port Chain will be from source IP address +22.1.20.1 TCP port 23 to destination IP address 171.4.5.6 TCP port 100. +The flow needs to be treated by SF1 running on VM1 identified by +Neutron port pair [p1, p2] and SF2 running on VM2 identified by Neutron +port pair [p3, p4]. + +The net1 should be created before creating Neutron port using existing +Neutron API. The design has no restriction on the type of net1, i.e. it +can be any type of Neutron network since SFC traffic will be tunneled +transparently through the type of communication channels of net1. +If the transport between vSwitches is VXLAN, then we will use that VXLAN +tunnel (and NOT create another new tunnel) to transport the SFC traffic +through. If the transport between vSwitches is Ethernet, then the SFC +traffic will be transported through Ethernet. In other words, the SFC +traffic will be carried over existing transport channel between vSwitches +and the external transport channel between vSwitches is set up for net1 +through existing Neutron API and ML2. The built-in OVS backend +implements tunneling the original flow packets over VXLAN tunnel. The detailed +outer VXLAN tunnel transport format and inner SFC flow format including +how to leverage existing OVS's support for MPLS label to carry chain ID +will be described in the `Port Chain OVS Driver and Agent specification <http://docs.openstack.org/developer/networking-sfc/portchain-ovs-driver-agent.html>`_. +In the future we can add implementation of tunneling the SFC flow packets over +flat L2 Ethernet or L3 IP network or GRE tunnel etc. + +Boot service VMs and attach ports +--------------------------------- +Create Neutron ports on network net1:: + + neutron port-create --name p1 net1 + neutron port-create --name p2 net1 + neutron port-create --name p3 net1 + neutron port-create --name p4 net1 + +Boot VM1 from Nova with ports p1 and p2 using two --nic options:: + + nova boot --image xxx --nic port-id=p1 --nic port-id=p2 vm1 + +Boot VM2 from Nova with ports p3 and p4 using two --nic options:: + + nova boot --image yyy --nic port-id=p3 --nic port-id=p4 vm2 + +Alternatively, the user can create each VM with one VNIC and then +attach another Neutron port to the VM:: + + nova boot --image xxx --nic port-id=p1 vm1 + nova interface-attach --port-id p2 vm1 + nova boot --image yyy --nic port-id=p3 vm2 + nova interface-attach --port-id p4 vm2 + +Once the Neutron ports p1 - p4 exist, the Port Chain is created using +the steps described below. + +Create Flow Classifier +---------------------- +Create flow-classifier FC1 that matches on source IP address 22.1.20.1 +(ingress direction) and destination IP address 171.4.5.6 (egress +direction) with TCP connection, source port 23 and destination port +100:: + + neutron flow-classifier-create + --ip-version ipv4 + --source-ip-prefix 22.1.20.1/32 + --destination-ip-prefix 172.4.5.6/32 + --protocol tcp + --source-port 23:23 + --destination-port 100:100 FC1 + +Create Port Pair +----------------- +Create port-pair PP1 with ports p1 and p2, port-pair PP2 with +ports p3 and p4, port-pair PP3 with ports P5 and P6:: + + neutron port-pair-create + --ingress=p1 + --egress=p2 PP1 + neutron port-pair-create + --ingress=p3 + --egress=p4 PP2 + neutron port-pair-create + --ingress=p5 + --egress=p6 PP3 + +Create Port Group +----------------- +Create port-pair-group PG1 with port-pair PP1 and PP2, and +port-pair-group PG2 with port-pair PP3:: + + neutron port-pair-group-create + --port-pair PP1 --port-pair PP2 PG1 + neutron port-pair-group-create + --port-pair PP3 PG2 + +Create Port Chain +----------------- + +Create port-chain PC1 with port-group PG1 and PG2, and flow +classifier FC1:: + + neutron port-chain-create + --port-pair-group PG1 --port-pair-group PG2 --flow-classifier FC1 PC1 + +This will result in the Port chain driver being invoked to create the +Port Chain. + +The following diagram illustrates the code execution flow (not the +exact codes) for the port chain creation:: + + PortChainAPIParsingAndValidation: create_port_chain + | + V + PortChainPlugin: create_port_chain + | + V + PortChainDbPlugin: create_port_chain + | + V + DriverManager: create_port_chain + | + V + portchain.drivers.OVSDriver: create_port_chain + +The vSwitch Driver needs to figure out which switch VM1 is connecting +with and which switch VM2 is connecting with (for OVS case, the OVS +driver has that information given the VMs' port info). As to the +connection setup between the two vSwitches, it should be done through +existing ML2 plugin mechanism. The connection between these two +vSwitches should already be set up before the user initiates the SFC +request. The service chain flow packets will be tunneled through the +connecting type/technology (e.g. VXLAN or GRE) between the two +vSwitches. For our reference code implementation, we will use VXLAN to +show a complete data path setup. Please refer to the `OVS Driver and OVS +Agent specification <http://docs.openstack.org/developer/networking-sfc/portchain-ovs-driver-agent.html>`_ for more detail info. + diff --git a/doc/source/usage.rst b/doc/source/usage.rst new file mode 100644 index 0000000..c097c33 --- /dev/null +++ b/doc/source/usage.rst @@ -0,0 +1,32 @@ +.. + Copyright 2015 Futurewei. All rights reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +===== +Usage +===== + +To use networking-sfc in a project:: + + import networking_sfc |