Bug 987711 - Provider external network documentation clarifications [NEEDINFO]
Provider external network documentation clarifications
Status: CLOSED CURRENTRELEASE
Product: Red Hat OpenStack
Classification: Red Hat
Component: doc-Installation_and_Configuration_Guide (Show other bugs)
3.0
Unspecified Unspecified
medium Severity medium
: z2
: 4.0
Assigned To: Don Domingo
ecs-bugs
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-07-23 20:17 EDT by Bob Kukura
Modified: 2016-04-26 22:15 EDT (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Build: CSProcessor Builder Version 1.11 Build Name: 15807, Installation and Configuration Guide-null-1 Build Date: 08-07-2013 12:33:42 Topic ID: 17918-457334 [Latest]
Last Closed: 2014-03-03 19:05:03 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---
ddomingo: needinfo? (rkukura)


Attachments (Terms of Use)

  None (edit)
Description Bob Kukura 2013-07-23 20:17:14 EDT
Title: Configuring a Provider Network

Describe the issue:

First, section 9.6, is titled "Configuring a Provider Network", but should be titled "Configuring a Provider External Network", since provider networks have applications other than a router's external network.

Second, I've helped two separate users who misinterpreted steps 5 and 6, invoking "quantum-router-interface-add" for the subnet belonging to the same network for which "quantum router-gateway-set" has previously been called. This results in an error such as "Bad router request: Router already has a port on subnet <subnet-id>". The text for these steps needs to clarify that "quantum router-gateway-set" is invoked for the router's external network, and "quantum-router-interface-add" is invoked for each of the router's private networks' subnets. The two commands should not be both be invoked for the same network/subnet combination.


Suggestions for improvement:


Additional information:
Comment 2 Bob Kukura 2013-07-24 13:16:38 EDT
One of the same users also pointed out: 

Start openvswitch in 9.8.1.2. should be in 9.7. Configuring the L3 Agent as  9.7.3. requires this service to run ovs-vsctl.


Actually, section 9.8 on the L2 agent should precede the sections on the other agents (DHCP & L3), since the L2 agent needs to be running for these other agents to function correctly.
Comment 3 Bob Kukura 2013-07-24 13:30:21 EDT
One more thing - Section 9.7.3.B.b of https://access.redhat.com/site/documentation//en-US/Red_Hat_OpenStack/3/html/Installation_and_Configuration_Guide/Configuring_the_L3_Agent.html should be removed - there is no need to set router_id when using either a provider external network or an external network bridge.
Comment 4 Stephen Gordon 2013-07-24 14:04:51 EDT
(In reply to Bob Kukura from comment #2)
> One of the same users also pointed out: 
> 
> Start openvswitch in 9.8.1.2. should be in 9.7. Configuring the L3 Agent as 
> 9.7.3. requires this service to run ovs-vsctl.

This was already filed as Bug # 980504.

> Actually, section 9.8 on the L2 agent should precede the sections on the
> other agents (DHCP & L3), since the L2 agent needs to be running for these
> other agents to function correctly.

Is there a separate Bugzilla for this?

(In reply to Bob Kukura from comment #3)
> One more thing - Section 9.7.3.B.b of https://access.redhat.com/site/documentation//en-US/Red_Hat_OpenStack/3/html/Installation_and_Configuration_Guide/Configuring_the_L3_Agent.html should be
> removed - there is no need to set router_id when using either a provider 
> external network or an external network bridge.

Please clarify what should be removed *precisely*, I assume you don't mean the whole linked section.
Comment 6 Bob Kukura 2013-07-24 15:24:53 EDT
Bug # 980504 covers moving the section on the L2 agent before the sections on the DHCP and L3 agents (including 9.6). I've added a comment to that BZ.

The text to be removed is:

 Set the value of the router_id configuration key in the /etc/quantum/l3_agent.ini file to the identifier of the external router that must be used by the L3 agent when accessing the external provider network.

# openstack-config --set /etc/quantum/l3_agent.ini \
   DEFAULT router_id ROUTER

Replace ROUTER with the unique identifier of the router that has been defined for use when accessing the external provider network. 



The above text should be removed because the router_id has nothing to do with using a provider external network or an external network bridge. Its a way to manage multiple l3-agents that each realize a single router, which was necessary when network namespaces were not available. It is no longer relevant.


I think much of the confusion here is because section 9.6 (Configuring a Provider [External] Network) and section 9.7 (Configuring the L3 Agent) aren't really separable in they way they are currently organized. To me, the order for all of this should be something like:

0) Have the L2 agent configured and running, as covered in 9.8.

1) Decide whether to use a provider external network vs. an external_network_bridge for the l3 agent's external network.

2) Configure/start the l3 agent, with external_network_bridge set to "" or "br-ex" based on item 1. Most of the details currently in 9.7 make sense, except for the issues discussed here regarding 9.7.3.

3) Create the external network, with the provider attributes based on item 1. Section 9.6.2 currently covers the provider external network case. But if using an external network bridge, I recommend using "quantum net-create EXTERNAL_NAME --router:external True --provider:network_type local", which doesn't seem to be covered anywhere (note some guides leave out setting network type to local, which wastes a tenant network).

4) Create the external subnet as currently shown in 9.6.3. This is needed for either choice in item 1, not just with a provider external network.

5) Create the router as currently shown in 9.6.4.

6) Add the external network as the router's gateway as shown in 9.6.5.

7) Add the private networks' subnets as the router's interfaces as shown in 9.6.6. Note that this MUST NOT be done for the external network's subnet (original issue for which this BZ was filed). Note this this step is likely done as part of provisioning each new tenant's private network.
Comment 10 Don Domingo 2013-12-04 01:31:22 EST
Did part of the work for this BZ. Details below:

(In reply to Bob Kukura from comment #0)
> Title: Configuring a Provider Network
> 
> Describe the issue:
> 
> First, section 9.6, is titled "Configuring a Provider Network", but should
> be titled "Configuring a Provider External Network", since provider networks
> have applications other than a router's external network.
> 

Edited title as "External Provider Network".

> Second, I've helped two separate users who misinterpreted steps 5 and 6,
> invoking "quantum-router-interface-add" for the subnet belonging to the same
> network for which "quantum router-gateway-set" has previously been called.
> This results in an error such as "Bad router request: Router already has a
> port on subnet <subnet-id>". The text for these steps needs to clarify that
> "quantum router-gateway-set" is invoked for the router's external network,
> and "quantum-router-interface-add" is invoked for each of the router's
> private networks' subnets. The two commands should not be both be invoked
> for the same network/subnet combination.
> 

Done. Clarified router-gateway-set and router-interface-add steps accordingly, stating that the latter one should be run on each private network subnet.


(In reply to Bob Kukura from comment #6)
> Bug # 980504 covers moving the section on the L2 agent before the sections
> on the DHCP and L3 agents (including 9.6). I've added a comment to that BZ.
> 
> The text to be removed is:
> 
>  Set the value of the router_id configuration key in the
> /etc/quantum/l3_agent.ini file to the identifier of the external router that
> must be used by the L3 agent when accessing the external provider network.
> 
> # openstack-config --set /etc/quantum/l3_agent.ini \
>    DEFAULT router_id ROUTER
> 
> Replace ROUTER with the unique identifier of the router that has been
> defined for use when accessing the external provider network. 
> 

Done. Removed the text.
Comment 16 Don Domingo 2014-01-20 22:19:06 EST
Moving this BZ to A2 just in case. Bear in mind that I'm keeping the edits in for A1 release.

Note You need to log in before you can comment on or make changes to this bug.