diff options
Diffstat (limited to 'doc/source')
| -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, 0 insertions, 1588 deletions
diff --git a/doc/source/alembic_migration.rst b/doc/source/alembic_migration.rst deleted file mode 100644 index bb225af..0000000 --- a/doc/source/alembic_migration.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. - 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 deleted file mode 100755 index aaa079a..0000000 --- a/doc/source/api.rst +++ /dev/null @@ -1,626 +0,0 @@ -.. - 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 deleted file mode 100644 index abb4096..0000000 --- a/doc/source/command_extensions.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. - 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 deleted file mode 100755 index e70c181..0000000 --- a/doc/source/conf.py +++ /dev/null @@ -1,76 +0,0 @@ -# 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 deleted file mode 100644 index 852aa97..0000000 --- a/doc/source/contribution.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. - 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 deleted file mode 100644 index da33019..0000000 --- a/doc/source/index.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. - 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 deleted file mode 100644 index bf133b0..0000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. - 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 deleted file mode 100644 index d8cda09..0000000 --- a/doc/source/ovs_driver_and_agent_workflow.rst +++ /dev/null @@ -1,311 +0,0 @@ -.. - 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 deleted file mode 100644 index 11e0849..0000000 --- a/doc/source/system_design and_workflow.rst +++ /dev/null @@ -1,245 +0,0 @@ -.. - 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 deleted file mode 100644 index c097c33..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. - 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 |