Bug 1276148 - [Docs][Director] Fixes for networking content
[Docs][Director] Fixes for networking content
Status: CLOSED CURRENTRELEASE
Product: Red Hat OpenStack
Classification: Red Hat
Component: documentation (Show other bugs)
7.0 (Kilo)
Unspecified Unspecified
unspecified Severity unspecified
: y2
: 7.0 (Kilo)
Assigned To: Dan Macpherson
RHOS Documentation Team
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-10-28 17:23 EDT by Dan Macpherson
Modified: 2015-12-07 20:57 EST (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2015-12-07 20:57:12 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Dan Macpherson 2015-10-28 17:23:44 EDT
6.3.7.1. Creating Custom Interface Templates
  YAML formatting is different than actual NIC config templates. This is
  confusing at best, but I haven't tested these to see if they work with
  the new formatting. This is REALLY going to confuse people if we have
  a different format than the sample templates. I see this throughout the
  document, so I assume you were trying to save space, but I find it hard
  to parse.

  Which leads me to Appendix D:

  The section for VLAN doesn't include the device: section, which is
  required when the VLAN is on a bond. We might want to at least indicate
  in appendix D table D.2 that

  In appendix D, each table lists nic_mapping as an option for each element
  (bond, vlan, interface, ovs_bridge, etc.), but this is actually a global
  that is set for the whole file, not for a specific interface. References
  should be removed.

  In appendix E.2, you have this:

  # No default route on the Provisioning network
  - type: interface
    name: nic1
    use_dhcp: true
    defroute: false
  # Instead use this DHCP infrastructure VLAN as the default route
  - type: interface
    name: nic2
    use_dhcp: true

  Except that the above won't work. The Undercloud does funny things with
  routing, so the default route on the provisioning network *can not* be
  disabled with defroute: false. There is no way to influence the default
  route when the provisioning network is DHCP. This is why we now use
  static IPs on the provisioning net. Really, the entire E.2 section is now
  obsolete and should be rewritten with a different example that doesn't
  assume the provisioning net is DHCP.

Section 6.3.7.2. Creating an Advanced Overcloud Network Environment File:
  The declaration of ServiceNetMap is wrong. It needs to be declared under
  parameter_defaults, not parameters. I thought we fixed this, so it sounds
  like a regression.

Section 6.3.8 Creating an Advanced Overcloud
  We REALLY need to mention here that the order of operations matters for -e
  includes. Templates included later override values set in template included
  earlier on the command line. This isn't an error as much as an omission that
  I just realized we had.

Section ⁠7.5. Creating the Overcloud Provider Network
  We should mention here that users must create additional bridge mappings if
  they want to deploy provider networks on a bridge other than br-ex. Some
  variation of the instructions given in section 7.4 would suffice, or even
  just a reference that it works the same way with provider networks.

Appendix F. Network Environment Options
  Missing:
    ControlPlaneDefaultRoute (compute only)
    ControlPlaneSubnetCidr
    EC2MetadataIp

Table G.1. Bonding Options
  Should mention that balance-tcp is only supported with LACP active
Comment 2 Dan Macpherson 2015-11-01 21:07:07 EST
Made an initial commit: https://gitlab.cee.redhat.com/rhci-documentation/docs-Red_Hat_Enterprise_Linux_OpenStack_Platform/commit/fb733d5bfd80390dbd5c906285c3153793632725

(In reply to Dan Macpherson from comment #0)
> 6.3.7.1. Creating Custom Interface Templates
>   YAML formatting is different than actual NIC config templates. This is
>   confusing at best, but I haven't tested these to see if they work with
>   the new formatting. This is REALLY going to confuse people if we have
>   a different format than the sample templates. I see this throughout the
>   document, so I assume you were trying to save space, but I find it hard
>   to parse.

Yep, this was essentially a space saving measure. I don't think this is a major issue as both the in-book example and the sample templates should work, and customers with a basic knowledge of YAML should be able to recognize this. Having said that, if we do get reports from the field that customers are getting confused by this, I'm more than willing to change it.

>   Which leads me to Appendix D:
> 
>   The section for VLAN doesn't include the device: section, which is
>   required when the VLAN is on a bond. We might want to at least indicate
>   in appendix D table D.2 that

I hunted around for information on this param but could find any. There didn't seem to be any reference to 'section' in the os-net-config code. NEEDINFOing dneddon -- any advice on where I can find info on this?

>   In appendix D, each table lists nic_mapping as an option for each element
>   (bond, vlan, interface, ovs_bridge, etc.), but this is actually a global
>   that is set for the whole file, not for a specific interface. References
>   should be removed.

No prob. Removed this.
 
>   In appendix E.2, you have this:
> 
>   # No default route on the Provisioning network
>   - type: interface
>     name: nic1
>     use_dhcp: true
>     defroute: false
>   # Instead use this DHCP infrastructure VLAN as the default route
>   - type: interface
>     name: nic2
>     use_dhcp: true
> 
>   Except that the above won't work. The Undercloud does funny things with
>   routing, so the default route on the provisioning network *can not* be
>   disabled with defroute: false. There is no way to influence the default
>   route when the provisioning network is DHCP. This is why we now use
>   static IPs on the provisioning net. Really, the entire E.2 section is now
>   obsolete and should be rewritten with a different example that doesn't
>   assume the provisioning net is DHCP.

I revised the example so that if configures nic2 and nic3. Removed mentions of the Provisioning network.

> Section 6.3.7.2. Creating an Advanced Overcloud Network Environment File:
>   The declaration of ServiceNetMap is wrong. It needs to be declared under
>   parameter_defaults, not parameters. I thought we fixed this, so it sounds
>   like a regression.

Fixed.

> Section 6.3.8 Creating an Advanced Overcloud
>   We REALLY need to mention here that the order of operations matters for -e
>   includes. Templates included later override values set in template included
>   earlier on the command line. This isn't an error as much as an omission
> that
>   I just realized we had.

I've updated the deployment params appendix to include this info.

> Section ⁠7.5. Creating the Overcloud Provider Network
>   We should mention here that users must create additional bridge mappings if
>   they want to deploy provider networks on a bridge other than br-ex. Some
>   variation of the instructions given in section 7.4 would suffice, or even
>   just a reference that it works the same way with provider networks.

Haven't added this yet, but it's on my list.

> Appendix F. Network Environment Options
>   Missing:
>     ControlPlaneDefaultRoute (compute only)
>     ControlPlaneSubnetCidr
>     EC2MetadataIp

Added.

> Table G.1. Bonding Options
>   Should mention that balance-tcp is only supported with LACP active

This has been added in a different commit:

https://gitlab.cee.redhat.com/rhci-documentation/docs-Red_Hat_Enterprise_Linux_OpenStack_Platform/commit/d8d1cb968ead5cc5dbc51e6264a8344aec6b4cad
Comment 3 Dan Macpherson 2015-12-07 20:57:12 EST
The content in this bug is live now. Closing this bug.

Please feel free to reopen if further changes are required.

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