<div dir="ltr">I'm hesitant to add a guide mid-release as it bit us pretty hard last release and we're still reeling from it. However if our crack info architects see this as a way out of the reorg we have to do anyway, I'm happy to support it. Can others weigh in on a good plan for this new book? Is anyone willing to be owner?<div>
<br></div><div>Thanks,</div><div>Anne</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Jan 5, 2014 at 1:08 PM, Tim Bell <span dir="ltr"><<a href="mailto:Tim.Bell@cern.ch" target="_blank">Tim.Bell@cern.ch</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div lang="EN-GB" link="blue" vlink="purple">
<div>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">My 5 cents …. Given we have an image guide book (<a href="http://docs.openstack.org/image-guide/content/" target="_blank">http://docs.openstack.org/image-guide/content/</a>)
and Neutron seems way more complex than that, I would support a dedicated book for Neutron.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">However, I think there should continue to be chapters in the standard guides for Neutron topics which can refer to the new book for
details. My experience is that part of the problem with understanding OpenStack networking is that people get scared at the first hurdle… we should be able to get them over the first few before they hit the more complex stuff.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">Tim<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<div style="border:none;border-left:solid blue 1.5pt;padding:0cm 0cm 0cm 4.0pt">
<div>
<div style="border:none;border-top:solid #e1e1e1 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b><span lang="EN-US" style="font-size:11.0pt;font-family:"Calibri","sans-serif"">From:</span></b><span lang="EN-US" style="font-size:11.0pt;font-family:"Calibri","sans-serif""> <a href="mailto:lorinh@gmail.com" target="_blank">lorinh@gmail.com</a> [mailto:<a href="mailto:lorinh@gmail.com" target="_blank">lorinh@gmail.com</a>]
<br>
<b>Sent:</b> 05 January 2014 19:54<br>
<b>To:</b> Andreas Jaeger<br>
<b>Cc:</b> <a href="mailto:openstack-docs@lists.openstack.org" target="_blank">openstack-docs@lists.openstack.org</a>; Alvise Dorigo<br>
<b>Subject:</b> Re: [Openstack-docs] [Openstack-operators] Neutron Documentation<u></u><u></u></span></p>
</div>
</div><div><div class="h5">
<p class="MsoNormal"><u></u> <u></u></p>
<div>
<div>
<p class="MsoNormal">I think that OpenStack Networking is complex enough that it warrants a separate book to describe the concepts in detail.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">In particular:<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"> * Many potential operators don't have enough prior networking experience to understand all of the underlying concepts<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"> * You really need to understand how OpenStack actually implements the networking to be able to do (and debug!) a proper deployment, especially since so many factors are site-specific<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<p class="MsoNormal">I just created this blueprint for a new guide that focuses specifically on describing the concepts behind OpenStack Networking:<u></u><u></u></p>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal"><a href="https://blueprints.launchpad.net/openstack-manuals/+spec/understanding-networking" target="_blank">https://blueprints.launchpad.net/openstack-manuals/+spec/understanding-networking</a><u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><a href="https://wiki.openstack.org/wiki/Documentation/UnderstandingNetworking" target="_blank">https://wiki.openstack.org/wiki/Documentation/UnderstandingNetworking</a><u></u><u></u></p>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">At one point, I was considering writing this book on my own, but if the doc team feel that this would be a good fit for the official docs, then I think having it as an official doc is best, especially since I likely don't have the cycles
to get it done on my own.<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">Do folks think having a separate guide focuses explicitly on Understanding OpenStack Networking would be a good idea?<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal">Lorin<u></u><u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
<div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
</div>
</div>
<div>
<p class="MsoNormal" style="margin-bottom:12.0pt"><u></u> <u></u></p>
<div>
<p class="MsoNormal">On Sun, Jan 5, 2014 at 1:43 PM, Andreas Jaeger <<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>> wrote:<u></u><u></u></p>
<blockquote style="border:none;border-left:solid #cccccc 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm">
<p class="MsoNormal">Alvise,<br>
<br>
thanks for your answer.<br>
<br>
On 01/05/2014 03:17 PM, Alvise Dorigo wrote:<br>
><br>
> On 05 Jan 2014, at 13:52, Andreas Jaeger <<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a><br>
> <mailto:<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>>> wrote:<br>
><br>
>> Hi Alvise,<br>
>><br>
>> I'm sorry to hear about your experiences. I know that the Networking<br>
>> chapter in the Install Guide is not perfect yet and we've improved it<br>
>> over the last couple of months.<br>
>><br>
>> I've copied the documentation team and would like to hear a bit more<br>
>> what exactly was the problem for you - why is it hard to follow? Do you<br>
>> have any proposals on how to improve it?<br>
>><br>
>> Reading your text, I think one suggestion is not to "jump around" where<br>
>> the guides jump to plug-in configuration and back. Anything else?<br>
><br>
> yes, that’s for sure the main point; a continuous flow of instructions<br>
> (i.e. commands to issue or files to modify) that are clear about where<br>
> to execute, should be mandatory.<br>
<br>
The guide was planned to support different plug-ins but only supports a<br>
single one - and therefore some things are done a bit awkward.<br>
<br>
> In addition. At page 29 (I’m referring to the PDF<br>
> version <a href="http://docs.openstack.org/havana/install-guide/install/yum/openstack-install-guide-yum-havana.pdf" target="_blank">
http://docs.openstack.org/havana/install-guide/install/yum/openstack-install-guide-yum-havana.pdf</a>)<br>
> I read “Enable Networking”. That chapter talks about nova-network which<br>
> is, as far as I know, deprecated in Havana, and everybody should<br>
> definitely use Neutron (am I correct ?). That chapter is clearly<br>
> misleading because put in mind the idea that one could anyway use the<br>
> easy nova-network-based networking. I would remove any reference to<br>
> nova-network at all, and make a better integration of compute node<br>
> networking setup with Neutron.<br>
<br>
A lot of people still use nova-network. There's a note "If you need the<br>
full software-defined networking stack, see Chapter 9, Install the<br>
Networking service.", should we make that more prominent?<br>
<br>
> An example of “jumping” is at page 63: “For instructions, see<br>
> ‘instructions’.” which link to page 64 ("Install and configure the<br>
> networking plug-ins”). But the are more examples in the rest of the text.<br>
><br>
> There’s also another thing not totally clear for me; at page 66<br>
> “Warning. You must use at least the No-Op firewall. Otherwise, Horizon<br>
> […]”. Those "must” and “at least” words are (at least for me) not<br>
> completely clear in the overall context; in fact above they say<br>
> “Otherwise, you can choose […] Hybrid OVS-IPTables driver”. Then, can I<br>
> choose or not ? Or maybe the Hybrid and the No-op must be specified in<br>
> different places ? but anyway it is not clear.<br>
><br>
> Page 67: 4. Return to the OVS general instructions.<br>
> Where ? perhaps step 9 @page 65 ?<br>
> The GOTO/RETURN directives in a “linear” documentation are a little bit<br>
> “annoying”… at least for me and some other people I know having<br>
> difficulties to install Neutron (they rely only on Packstack, but I need<br>
> manual configuration).<br>
><br>
> Another unclear thing: page 70, step 5 indicates a jump forward. At the<br>
> end there’s the bridge adding (br_DATA_INTERFACE), but there’s not<br>
> indication to modify ifcfg-eth0 and ifcfg-br_DATA_ as before (made on<br>
> the network node)… And as far as I understand this step should be done.<br>
><br>
> Page 71: “If you wish to have a combined controller/compute node follow<br>
> […]”. Then I can skip this chapter, because I want all neutron<br>
> services/plugins/agent on the network node, the compute daemon on the<br>
> compute node, and keystone/glance/nova-api/nova-cert/nova-conductor… on<br>
> the controller node. And this is what I’ve done (skipping the chapter at<br>
> page 71). But nova-api cannot communicate, apparently, with neutron. In<br>
> fact “nova net-list” doesn’t return anything even after net and subnet<br>
> creation with the neutron command line:<br>
><br>
> ======================<br>
> bash-4.1$ neutron net-show esterna<br>
> +---------------------------+--------------------------------------+<br>
> | Field | Value |<br>
> +---------------------------+--------------------------------------+<br>
> | admin_state_up | True |<br>
> | id | 9b12acfa-4146-4f68-b69d-fb660162ad58 |<br>
> | name | esterna |<br>
> | provider:network_type | vlan |<br>
> | provider:physical_network | physnet1 |<br>
> | provider:segmentation_id | 2 |<br>
> | router:external | True |<br>
> | shared | True |<br>
> | status | ACTIVE |<br>
> | subnets | 27876b6f-7904-42c7-9760-bc46725c4376 |<br>
> | tenant_id | ff95d472eccd428f8c5cc29dcf3014ec |<br>
> +---------------------------+--------------------------------------+<br>
> bash-4.1$ neutron net-update demo-net --shared=True<br>
> Updated network: demo-net<br>
> bash-4.1$ nova net-list<br>
><br>
> bash-4.1$<br>
><br>
> ======================<br>
><br>
> For sure I made a mistake, but it easy to make a mistake if the doc is<br>
> “adventurous” as they admit at the beginning ;-)<br>
><br>
> thanks for attention,<br>
><br>
> Alvise<br>
><br>
> P.S. I’m in hurry, so I’ve to try ASAP the RedHat documentation<br>
> suggested by Sankarshan.<br>
<span style="color:#888888"><br>
<span>Andreas</span><br>
<span>--</span><br>
<span> Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi</span><br>
<span> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany</span><br>
<span> GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)</span><br>
<span> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126</span><br>
<br>
<span>_______________________________________________</span><br>
<span>Openstack-docs mailing list</span><br>
<span><a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a></span><br>
<span><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a></span></span><u></u><u></u></p>
</blockquote>
</div>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
</div></div></div>
</div>
</div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div>