Early Review of draft-ietf-i2rs-yang-dc-fabric-network-topology-02
review-ietf-i2rs-yang-dc-fabric-network-topology-02-yangdoctors-early-rahman-2017-12-12-00

Request Review of draft-ietf-i2rs-yang-dc-fabric-network-topology
Requested rev. no specific revision (document currently at 12)
Type Early Review
Team YANG Doctors (yangdoctors)
Deadline 2017-12-12
Requested 2017-11-28
Requested by Susan Hares
Draft last updated 2017-12-12
Completed reviews Yangdoctors Early review of -02 by Reshad Rahman (diff)
Rtgdir Early review of -03 by Matthew Bocci (diff)
Opsdir Telechat review of -06 by Carlos Martínez (diff)
Secdir Telechat review of -06 by Radia Perlman (diff)
Genart Telechat review of -08 by Paul Kyzivat (diff)
Comments
This is a request for a QA review.  It will run parallel to the WG LC for this document.
Assignment Reviewer Reshad Rahman
State Completed
Review review-ietf-i2rs-yang-dc-fabric-network-topology-02-yangdoctors-early-rahman-2017-12-12
Reviewed rev. 02 (document currently at 12)
Review result Ready with Issues
Review completed: 2017-12-12

Review
review-ietf-i2rs-yang-dc-fabric-network-topology-02-yangdoctors-early-rahman-2017-12-12

YANG Doctor review of draft-ietf-i2rs-yang-dc-fabric-network-topology-02 (by Reshad Rahman)

3 modules defined in this draft:
- ietf-fabric-topology-state@2017-11-29.yang
- ietf-fabric-topology@2017-11-29.yang
- ietf-fabric-types@2017-11-29.yang

No YANG validation errors or warnings (from yang and tangling).

0 examples are provided in this draft (section 3.12 of draft-ietf-netmod-rfc6087bis-14)

Module ietf-fabric-types@2017-11-29.yang:
- “import ietf-inet-types” should have a reference to RFC6991 (see section 4.7 of rfc6087bis-14)
- “import ietf-network-topology”, prefix should match new prefix name (if it changes) for this module as per YD review comments of draft-ietf-i2rs-yang-network-topo
- Remove WG Chairs from contact information as per Appendix C of rfc6087bis-14
- Description mentions draft-zhuang-i2rs-…, should say draft-ietf-i2rs-…. Also in description add “Note to RFC Editor” with text saying something along the lines of “Please replace reference to draft-ietf-i2rs-… with RFC Number when published”.
- In description: Copyright s/2016/2017/
- Is the bandwidth identity really needed? Why not a uint64 with a unit of kbps as in draft-ietf-netmod-intf-ext-yang? 
- Get rid of revision history, i.e. keep only 1 revision (latest) 
- What is the difference between identity fabric-type (VXLAN, VLAN) and enum underlay-network-type (VXLAN, TRILL, VLAM). Are both needed or do they refer to the same thing? Should be identity and not enum to support new types in the future?
- service-capabilities. Should this be an identity for future extensibility? Need more in the description, add reference to other documents where appropriate. 
- Groupings route-group, port-functions, acl-list not used, still needed or can these be removed? 
- If you do keep route-group, it is IPv4 specific right now so it needs to be modified.
- If you do keep acl-group, please take a look at draft-ietf-netmod-acl-model
- device-role and fabric-port-role. Why not use identity to allow for new roles to be added in the future.
- Is it possible (now or in near-future) for multiple roles to be assumed?  If yes, how will this be handled?
- In grouping fabric-port, tunnel-option is there unconditionally. Should it be there only when type is layer2Tunnel or layer3Tunnel? If so add a when statement. Similarly should are only be allowed for layer3Tunnel?
- In grouping fabric-port, looks like only L3 tunnel (GRE) is supported. What L2 Tunnels will be supported?
 
Module ietf-fabric-topology@2017-11-29.yang:
- Remove WG Chairs from contact information as per Appendix C of rfc6087bis-14
- Indentation issue on P17
- fport-attributes is “config false”, how is a GRE tunnel configured?
- Description mentions draft-zhuang-i2rs-…, should say draft-ietf-i2rs-…. Also in description add “Note to RFC Editor” with text saying something along the lines of “Please replace reference to draft-ietf-i2rs-… with RFC Number when published”.
- In description: Copyright s/2016/2017/
- gateway-mode, need more text in the description and/or references to other documents.

ietf-fabric-topology-state@2017-11-29.yang:
- In description make it clear that this module is not needed when NMDA is supported.
- Revision history is incorrect since it has “NMDA”.
- Same comments as for ietf-fabric-topology

General comments on draft:
- Since the document is for DC Fabrics, should the YANG modules be renamed from ietf-fabric-xxx.yang to ietf-dc-fabric-xxx.yang?
- The descriptions in all YANG Modules are very short/terse. 
- No IANA Considerations, please see section 3.8 of 6087bis-14.
- Security Considerations. Follow template @ https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines as per 6087bis-14. Looks like the first part of the template is missing.
- Appendix A has no text, just the YANG module. There should be some text explaining why the -state module exists. Take a look at the text in Appendix B of draft-ietf-i2rs-yang-network-topo-14 as an example.

Nits:
- 3.2.1 s/snatch/snip/?
- 3.2.3 s/terminiation/termination/
- 3.2.3 s/etc al/etc/?
- Most descriptions in the YANG Modules start with lower-case, should be upper-case.
- s/Security Consideration/Security Considerations/
- s/fabric Topology/fabric topology/? Any it should either be both lower-case or both upper-case.