Martin: Unlike RHOS 4.0, which only supported api_workers, 5.0 will support a second configuration option named rpc_workers.  The defaults for both options in 5.0 is 0 pending the testing necessary to validate multi-process behavior.  If/when multi-process behavior proves stable, an operator will be able to configure the Neutron service with both options set to 1 and then increment the options independently when bottlenecks are identified.

Since each worker represents a process, the sum of api_workers and rpc_workers should not exceed the available number of cores on the host.

Setting api_workers and rpc_workers in RHOS 5.0 to non-zero values breaks the Neutron service rather than increasing its scalability.  The documentation will need to discourage changing the values for these configuration settings until further notice.

I've attached a link to an upstream patch that demonstrates the failure mode in question.

I think it would make sense to remove the section in question or limit it to a warning not to change the api_workers and rpc_workers options.  The metadata_workers option does not impact the scalability of the Neutron service, only that of the metadata agent (as per the following bug):

https://bugs.launchpad.net/neutron/+bug/1274536

Thanks Maru, 

I've removed the section from the book spec, and flagged this BZ for the Release  Notes as a known issue.

Mention of the api_workers known issue is noted in BZ#1056405

Setting to verified.