ISND, PART 2

Following up on my previous post on ISND (International Standard of Network Documentation). This post is about how you can do good network diagrams.
But first I have to correct my self, based on the feedback I got on my previous post.
I wrote that "builders don't get a 10 page report describing how the house should be built" and have been corrected. In the construction business, there is written documentation. There is documentation on what materials to use, which codes to follow and general descriptions. If you include the public codes, there's a lot of written documentation.
We are lucky in that our industry doesn't have public codes regulating how networks should be built. There are "codes" in the private domain, which a customer may refer to when requesting a solution but no public ones.
So to correct myself, I'm not suggesting, that you don't produce any written documentation at all!
You should.
But you need to separate what goes into your written documentation and what goes into your diagrams. The diagram is your blueprint - your building instruction, this tells you what to build. Your written documentation is the detail, this tells you how to build it.

Since this post is about diagrams, I've decided that I might make a follow up on this one, to talk about the the written documentation.


To recap from my last post, I stated that you need to make different diagrams for different purposes. Here I will give you some examples of how to do that. This is obviously not going to be complete standard, I don't have the time and space to write that here and you couldn't be bothered to read it. Instead I will try to give you an idea of the concepts you should be using and which ones to avoid, with some examples to get you started.

Keeping the architects drawings in mind, we start by dividing our network diagrams into two categories. The design sketch, this is our High Level Design (HLD) and the technical drawings, these are our Low Level Designs (LLDs).

The purpose of the HLD is to conway an idea, a vision, to a client. It shows the big picture. These are the things you sketch on a whiteboard using your classic iconography and most of you should be familiar with this. But remember: Your HLD contains no technical information. Don't be tempted to add IP addresses, VLAN numbers and so on. They should be readable on A3 size paper. Split them up. Just like the architect has sketches of different parts of the house, you to should have diagrams of different parts of the network. When you do HLDs you must think about your client. He should be able to understand them and recognize the elements, that he has requested for the design.

The audience of your LLD are the people how are going to build the network or extend it in the future. Here you must remember to keep everything in diagrams - often people attach a text to the diagrams explaining how it works. This should not be necessary if you do your diagrams correctly and put the detailed information into the written documentation.

In your LLD you always need to make diagrams for your Layer 1, Layer 2 and Layer 3. In addition, you can make other functional diagrams, that are needed for your design, such as rack diagrams, power diagrams, routing diagrams, security diagrams and so on. Which ones are required, depends on your design. You should be in no doubt as to where to put what information.
Remember to put in a legend explaining your symbols.
Any information you need to add, should be drawn with basic technical information on the elements, such as IP addresses, device names and so on. If you need to reference detailed information in the written documentation, do that through the legend as well.
In the LLD you need to get away from the idea, that you can depict a device as a single icon, with lines coming out of it. You use those for your HLD. There is so much going on inside and between devices, that you need to make them big. Use icons in the top corner to show what kind of device it is, but make lots of room.
Don't be afraid to put devices inside devices. Use decent sized interfaces, that can contain information. Put interfaces inside interfaces if you need to. Use an interface shape, that clearly shows ingress and egress. When putting devices, interfaces or areas inside each other, think about which element is a part of something bigger.
If you find yourself typing, the same information over and over again, change it to a symbol and put it in the legend.
Use combinations of, color, shading, corners, line types and thickness as symbols.
Don't be afraid to use the space you need. Have you ever seen a blueprint for a house, that fits on a piece of A4?
If your design becomes crowded, you need to group things together and put them in separate diagrams. When you do this, you need to be consistent in your grouping. Make a rule, like: "If there are more than 3 devices doing the same thing connected to another device, they will be grouped."

Here is an overview of what could go into various diagrams and how you can depict it. It's not complete, but from the context your should be able to figure out where, what information goes and how you can depict it.

Layer 1 diagrams should depict everything physical. You want to show how it's wired together. This could contain your:
Devices: Depict the type as a symbol and the name as text. Use a distinct shape for devices, like a rectangle.
Physical interfaces: Media as asymbol and a name text. If you use special MTU, duplex and speed depict that with color and numbers, otherwise put it in the legend.
Cables: Use colors for types and the end of the line colored differently to show subtypes.
Locations: Group things together in their physical location. Use a distinct border shape for locations.

Layer 2 diagrams should depict your domains, regardless of what they travers. The reader should be able to follow a domain everywhere it goes. Inside and outside of devices. The reader also needs to know the transport method of your domain, is it a VLAN, L2 VPN, a (virtual) switch. This could contain your:
Devices: Any device, physical or virtual, see Layer 1.
Interfaces: Physical and logical interfaces, use iconography to represent the type (LAG, redundant ethernet and so on). Place interface on the edge of your device if they interconnect with other devices or on the inside of your device, if they exist only logically there.
VLANs: Inside and outside your devices. Different VLANs can be show by color. If you need to represent both S-VLANs and C-VLANs together, place a thick S-VLAN at the interface and spilt it into several C-VLANs on the interconnecting part. Use a distinct line type for VLANs. You can put the ID either in the legend or in the middle of the line.
Spanning Tree: Interfaces can be marked with different states, either by color or symbols.
MPLS: Isn't techincally layer 2, but is required to represent other layer 2 domains. MPLS can be represented as a virtual device surrounding the MPLS area, with the MPLS interfaces connecting through that area. Use a distinct line type and distinct shading and shape for your area.
L2 Circuits: Can be represented as a virtual device with two interfaces inside the MPLS device described above. You can then interconnect these interfaces with their real interfaces on the physical devices.
L2 VPN: Can be represented in the same way as L2 circuits, as its own device inside the MPLS device, with VLAN representation, just like on physical devices.

Layer 3 diagrams should depict your subnets and only elements participating on the IP layer. The reader should be able to see how to get from one subnet to another. This could contain your
Devices: Only layer 3 devices, logical or physical
Interfaces: Logical and physical, but only layer 3 interfaces.
Subnets: Use cloud or bus depictions. Put the subnet in CIDR format there. The connecting interfaces should only have the remainder of the IP addresses displayed. If you use a bus depiction, place the gateway at the end of the bus or mark it out (in bold) on a cloud depiction.
L3 VPN: Are represented as devices inside the MPLS device described in Layer 2 in the same manner as L2 VPNs.
VRRP: Can be represented as a logical interface without a device. Connect one side to the participating interfaces and the other to the subnet.
DHCP: Put a logical device with your DHCP information containing the appropriate interfaces inside the physical device.

These are the basic three diagrams, that you should always have. In addition, you can create functional diagrams suiting your purposes. Here are some examples.

Security diagrams should depict where and how security is handled. This example assumes you're dealing with a layer 3 firewall, but this can just as easily be applied to a layer 2 firewall. I know NAT is in here, which technically has nothing to do with security and if this is your only "security" element you could include that in the Layer 3 diagram. The diagrams could contain your
Devices: Any device performing a firewall/security function.
Interfaces: Particitpating in a firwall/security function.
Subnets: All subnets affected by a firewall/security function.
Zones: Represent these as colored cones. With the top of the cone placed on the interface creating the zone.
Policies: Create a logical container for policies inside the device. Connect it to the zones with arrowhead indicating the direction of the policy.
Rules: Create a logical container inside your policies or devices. Give it an icon indicating its action and place the affected ports/address in the container. If there is to much information to put here or in the legend, refer to the written documentation.
NAT: Static NAT is represented as a line with arrowheads at each end between the public and private IP addresses. Source NAT is represented as a line with an arrowhead at the NATing address, between the public IP and the subnet. Destination NAT is represented as a line with an arrowhead at the NATed end, between the public and private address/port.

Routing diagrams should tell the reader about the overall routing. What peers and areas exist, how do we get from one area or subnet to another. This could contain your
Devices: Any device performing a routing action, physical or logical.
Interfaces: Any interface participating in a routing action.
BGP: Include all devices inside a colored ASN area. Use lines to represent peerings. iBGP peerings can have the ASN color and eBGP peerings can have two colors representing the ASNs.
OSPF: Include all devices inside a colored OSPF area. Use lines to represent the OSPF neighbors. Use shading to indicate differnt kinds of areas.
Static routes: Put an arrow with the route outside the egress interface.

This is by no means a complete standard and you don't need to do the representations in the way they are described here. If a different representation works better for you, use that instead. I hope it has given you a better understanding of how to do network diagrams and that you have been inspired.
If it sounds like a lot of work, think about why you are doing your documentation.