Add documentation and subnet-get command to yap.
This commit is contained in:
Brandon Cazander
parent
40a9a8f0ff
commit
9516d47ae8
1
.gitignore
vendored
Normal file
1
.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
||||
docs/
|
||||
9
Makefile
9
Makefile
@ -14,5 +14,12 @@ install:
|
||||
test -f $(DESTDIR)$(TOPFILE) || echo "partner:" > $(DESTDIR)$(TOPFILE)
|
||||
grep -q 'aggregator|vxr' $(DESTDIR)$(TOPFILE) || cat salt/top.sls >> $(DESTDIR)$(TOPFILE)
|
||||
|
||||
docs: README.rst
|
||||
mkdir -p docs/
|
||||
cp VXLAN-backhaul.png docs/
|
||||
rst2html README.rst docs/index.html
|
||||
|
||||
.PHONY: all install
|
||||
clean:
|
||||
rm -rf docs/
|
||||
|
||||
.PHONY: all install clean
|
||||
|
||||
226
README.rst
226
README.rst
@ -15,6 +15,10 @@ If a backhaul is not already set up in a data center, additional "VXR" boxes
|
||||
can be added to each data center to provide an overlay backhaul using
|
||||
VXLAN-over-IPSEC.
|
||||
|
||||
.. contents::
|
||||
|
||||
Installation and setup
|
||||
----------------------
|
||||
|
||||
Initial installation
|
||||
====================
|
||||
@ -23,6 +27,10 @@ First, install the software on the bondingadmin server::
|
||||
|
||||
make install
|
||||
|
||||
|
||||
.. note:: The rest of the yap commands are run on the management server, unless
|
||||
otherwise stated.
|
||||
|
||||
Then add a read-only user in the Bondingadmin web interface allow the tool to
|
||||
query the API. Add the user details using the ``yap`` tool::
|
||||
|
||||
@ -38,8 +46,8 @@ spaces. To add a region::
|
||||
yap region-add yvr
|
||||
|
||||
|
||||
Setting up spaces
|
||||
=================
|
||||
Adding spaces
|
||||
=============
|
||||
|
||||
To add the space with key ``foo``::
|
||||
|
||||
@ -118,3 +126,217 @@ example, to show the state of space ``foo`` on the VXR ``yvr-vxr01`` and the
|
||||
aggregator with ID 1::
|
||||
|
||||
salt -C 'L@yvr-vxr01,node-1' cmd.run "yap status foo"
|
||||
|
||||
|
||||
Architectural overview
|
||||
----------------------
|
||||
|
||||
The following diagram shows an overview of the various nodes involved in a
|
||||
typical YAP deployment for a space. This fictional space has a firewall in
|
||||
YVR only, but bonds in both YVR and TOR.
|
||||
|
||||
The red circles denote details and troubleshooting commands that can be run
|
||||
on each respective node.
|
||||
|
||||
.. image:: VXLAN-backhaul.png
|
||||
:scale: 30 %
|
||||
:alt: VXLAN backhaul diagram
|
||||
|
||||
.. This diagram may be updated at the following link:
|
||||
https://www.lucidchart.com/invitations/accept/27dfc950-e351-4511-b42a-d1f08fe26833
|
||||
|
||||
|
||||
Adding spaces
|
||||
-------------
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
* All bonds are moved to yap-enabled aggregators.
|
||||
* A VLAN is designated for each region that will host bonds. For example, for
|
||||
a space that has bonds on aggregators in two regions, YVR and TOR, you must
|
||||
designate a VLAN for both regions.
|
||||
|
||||
Migrating existing private WAN spaces
|
||||
=====================================
|
||||
|
||||
The following commands are all to be run on the management server.
|
||||
|
||||
.. warning:: There will be a brief outage when migrating a space.
|
||||
|
||||
1. Add the space::
|
||||
|
||||
yap space-add <key>
|
||||
|
||||
This can be run in advance as it does not make any runtime changes.
|
||||
|
||||
2. To calculate the subnet for each region/space, you can run the following
|
||||
command. This only returns the network that will be designated for the VLAN
|
||||
on the aggregators in the region, it does not apply any changes::
|
||||
|
||||
yap subnet-get <key> <region>
|
||||
|
||||
This will return the base subnet for this space-region pair, as well as the
|
||||
specific IPs of the aggregators in that region. The first IP in the subnet
|
||||
is reserved for the firewall::
|
||||
|
||||
Subnet: 100.31.88.0/21
|
||||
Firewall: 100.31.88.1
|
||||
Aggregators:
|
||||
agg03: 100.31.88.5
|
||||
|
||||
3. Configure the firewall with the IP shown in step 2 on the VLAN interface and
|
||||
configure OSPF. While the exact settings will be vendor-specific, here are
|
||||
the general details:
|
||||
|
||||
* area 0.0.0.0
|
||||
* subnet <from step 2>
|
||||
* redistribute connected
|
||||
* hello interval 10s
|
||||
* dead interval 40s
|
||||
|
||||
4. Add a VLAN association for each region::
|
||||
|
||||
yap vlan-set <key> <region> <vlan_id>
|
||||
|
||||
This will start the VLAN interfaces on each yap-enabled aggregator in the
|
||||
region using the same subnet reflected in step 2.
|
||||
|
||||
.. caution:: This is the start of an outage for the space, as the private
|
||||
WAN router's BGP protocols for the space are brought down to prevent
|
||||
routing loops/conflicts.
|
||||
|
||||
5. Confirm OSPF is up in each region by running this command on the
|
||||
aggregators::
|
||||
|
||||
yap status <key>
|
||||
|
||||
If the OSPF protocol is not 'Running', jump to troubleshooting
|
||||
`B: Aggregator`_.
|
||||
|
||||
6. Once OSPF is up and the routes have propagated both ways, you can disable
|
||||
the outbound gateway configured in the existing space to finish cleanup.
|
||||
|
||||
|
||||
Adding new private WAN spaces
|
||||
=============================
|
||||
|
||||
Follow the same steps as for migrating an existing space, with these two
|
||||
exceptions:
|
||||
|
||||
* Enable private WAN on the space through the management server interface.
|
||||
* An outbound gateway should not be enabled in the space's private WAN tab,
|
||||
however, you may wish to add a disabled gateway for record-keeping of the
|
||||
firewall's IP.
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
A: Bond
|
||||
=======
|
||||
|
||||
While YAP doesn't directly affect bonds, it can be useful to troubleshoot
|
||||
private WAN routes at the bond level, by inspecting their routing table::
|
||||
|
||||
ip route show table bonding-pwan
|
||||
|
||||
B: Aggregator
|
||||
=============
|
||||
|
||||
YAP-enabled aggregators have a ``yap`` command installed that can be used
|
||||
to show information about the spaces currently running on the aggregator.
|
||||
|
||||
The most useful command is ``yap status <space key>``, which shows the status
|
||||
of the bird protocols and the current routing table for that space::
|
||||
|
||||
agg:~# yap status bammya
|
||||
|
||||
spcbammya BGP krt8251 up 2018-12-06 Established
|
||||
ospf_bammya OSPF krt8251 up 07:21:22 Running
|
||||
|
||||
default via 100.109.152.1 dev vl-bammya proto bird
|
||||
10.10.1.0/24 via 100.109.152.8 dev vl-bammya proto bird
|
||||
192.168.33.0/24 via 100.109.152.8 dev vl-bammya proto bird
|
||||
|
||||
The BGP protocol for the space is controlled by bonding and should be in
|
||||
'Established' state. The ``ospf_<key>`` protocol is the one managed by YAP and
|
||||
should be in 'Running' state. If the status is 'Alone' instead, it means there
|
||||
are no OSPF neighbors.
|
||||
|
||||
If you want to, you can show the current OSPF neighbors for a space::
|
||||
|
||||
pwanbirdc - show ospf neighbor ospf_<key>
|
||||
|
||||
An aggregator has one VLAN interface per space, which follows the naming
|
||||
convention of ``vl-<key>``. You can use this command to show the VLAN id::
|
||||
|
||||
ip -d link show dev vl-bammya
|
||||
|
||||
Lastly, you can look at the VLAN interface to see the aggregator's IP, as well
|
||||
as the subnet designated for the space and routing group::
|
||||
|
||||
agg:~# ip address show dev vl-bammya
|
||||
|
||||
440: vl-bammya@eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
|
||||
link/ether d0:43:1e:c5:1b:44 brd ff:ff:ff:ff:ff:ff
|
||||
inet 100.109.152.7/21 scope global vl-bammya
|
||||
|
||||
In the example above, the firewall would be configured with ``100.109.152.1/21``.
|
||||
|
||||
Knowing the subnet, you can test ICMP connectivity to the firewall IP::
|
||||
|
||||
ping <gateway IP>
|
||||
|
||||
When troubleshooting OSPF it may be useful to run a packet capture on the VLAN
|
||||
interface to see which options are set::
|
||||
|
||||
tcpdump -ni vl-<key> proto 89 -vvv
|
||||
|
||||
|
||||
D: VXR
|
||||
======
|
||||
|
||||
The most useful command is ``yap status <space key>``, which shows the status
|
||||
of the bird protocol and the current routing table for that space::
|
||||
|
||||
agg:~# yap status bammya
|
||||
|
||||
ospf_bammya OSPF bammya up 07:21:23.175 Running
|
||||
|
||||
default via 100.109.152.1 dev vl-bammya proto bird metric 32
|
||||
10.10.1.0/24 via 100.109.152.8 dev vl-bammya proto bird metric 32
|
||||
|
||||
Otherwise, the same troubleshooting steps apply as on the aggregator.
|
||||
|
||||
If you need to troubleshoot the VXLAN as well, you can view the interface
|
||||
details with the standard linux utilities::
|
||||
|
||||
agg:~# ip -d l show dev vx-<key>
|
||||
|
||||
191: vx-bammya: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1432 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
|
||||
link/ether 66:da:5c:17:37:38 brd ff:ff:ff:ff:ff:ff promiscuity 0
|
||||
vxlan id 59 srcport 0 0 dstport 4789 ageing 300 udpcsum noudp6zerocsumtx noudp6zerocsumrx addrgenmode eui64 numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535
|
||||
|
||||
E: Firewall
|
||||
===========
|
||||
|
||||
Out of YAP's control. Here be dragons.
|
||||
|
||||
F: bondingadmin
|
||||
===============
|
||||
|
||||
Like all the nodes, there is a command in the path called ``yap`` that serves
|
||||
as the entry point for all things backhauled. Most of the commands are
|
||||
described above in their relevant sections. You can always run ``yap`` with
|
||||
no arguments to see what actions are available::
|
||||
|
||||
root@bondingadmin:~# yap
|
||||
/usr/local/bin/yap <action> [args]
|
||||
|
||||
Actions:
|
||||
|
||||
region-list
|
||||
region-show <region>
|
||||
region-add <region>
|
||||
...
|
||||
|
||||
|
||||
BIN
VXLAN-backhaul.png
Normal file
BIN
VXLAN-backhaul.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 94 KiB |
15
update-docs.sh
Executable file
15
update-docs.sh
Executable file
@ -0,0 +1,15 @@
|
||||
#!/bin/bash -e
|
||||
|
||||
RADOSGW_USER="yap-docs"
|
||||
BUCKET_NAME="yap-docs"
|
||||
BUCKET="s3://$BUCKET_NAME"
|
||||
ACCESS_KEY=$(radosgw-admin user info --uid=$RADOSGW_USER | grep "access_key" | cut -d '"' -f 4)
|
||||
SECRET_ACCESS_KEY=$(radosgw-admin user info --uid=$RADOSGW_USER | grep "secret_key" | cut -d '"' -f 4)
|
||||
|
||||
S3CMD_OPTIONS="--access_key=$ACCESS_KEY --secret_key=$SECRET_ACCESS_KEY --no-ssl --acl-public --host=rgw.multapplied.net --host-bucket='yap-docs.rgw.multapplied.net'"
|
||||
echo "$S3CMD_OPTIONS"
|
||||
S3CMD="s3cmd $S3CMD_OPTIONS"
|
||||
|
||||
$S3CMD mb $BUCKET
|
||||
$S3CMD ws-create $BUCKET
|
||||
$S3CMD sync docs/ $BUCKET
|
||||
87
yap
87
yap
@ -173,6 +173,52 @@ function list_sections() {
|
||||
}
|
||||
|
||||
|
||||
function ip2dec() {
|
||||
local a b c d ip=$@
|
||||
IFS=. read -r a b c d <<< "$ip"
|
||||
printf '%d\n' "$((a * 256 ** 3 + b * 256 ** 2 + c * 256 + d))"
|
||||
}
|
||||
|
||||
|
||||
function dec2ip() {
|
||||
local delim ip dec=$@
|
||||
for e in {3..0} ; do
|
||||
((octet = dec / (256 ** e) ))
|
||||
((dec -= octet * 256 ** e))
|
||||
ip+=$delim$octet
|
||||
delim=.
|
||||
done
|
||||
printf '%s' "$ip"
|
||||
}
|
||||
|
||||
|
||||
# Generate an IP for a VLAN interface based on the VLAN and and the YAP ID.
|
||||
# The first octet will always be 100, while the other 3 octets are split into
|
||||
# 3 sections of varying size to contain the IP type, the VLAN, and the YAP ID:
|
||||
#
|
||||
# type: 1-bit
|
||||
# vlan ID: 12-bits
|
||||
# YAP ID: 11-bits
|
||||
#
|
||||
# The resulting IP should be used with a prefix length of 21
|
||||
#
|
||||
function get_vlan_ip() {
|
||||
vlan_id=$1
|
||||
yap_id=$2
|
||||
|
||||
# Start at 100.0.0.0
|
||||
local ip=$(ip2dec 100.0.0.0)
|
||||
|
||||
# Add the VLAN ID, shifted 11-bits
|
||||
((ip += vlan_id << 11))
|
||||
|
||||
# Add the YAP ID
|
||||
((ip += yap_id))
|
||||
|
||||
dec2ip $ip
|
||||
}
|
||||
|
||||
|
||||
function validate_ip() {
|
||||
if ! [[ $1 =~ ^(0*(1?[0-9]{1,2}|2([0-4][0-9]|5[0-5]))\.){3}0*(1?[0-9]{1,2}|2([0-4][0-9]|5[0-5]))$ ]] ; then
|
||||
return 1
|
||||
@ -453,9 +499,10 @@ function region_show() {
|
||||
echo "VLAN associations:"
|
||||
|
||||
for space in $(list_sections "/regions/$region/spaces") ; do
|
||||
var="/regions/$region/spaces/$space/vlan"
|
||||
var="$space/vlan"
|
||||
if has_var "$var" ; then
|
||||
echo " $(basename space) $(get_var $var)"
|
||||
vlan_id=$(get_var $var)
|
||||
echo " $(basename space) $vlan_id: $(get_vlan_ip $vlan_id 0)/21"
|
||||
fi
|
||||
done
|
||||
|
||||
@ -558,6 +605,39 @@ function space_delete() {
|
||||
}
|
||||
|
||||
|
||||
#
|
||||
# Subnet commands
|
||||
#
|
||||
|
||||
function subnet_get() {
|
||||
args=$(check_args space,,$1, region,,$2) || return 1
|
||||
eval $args
|
||||
|
||||
if ! has_section "/spaces/$space" ; then
|
||||
echo "Space does not exist"
|
||||
return 1
|
||||
fi
|
||||
|
||||
if ! has_section "/regions/$region" ; then
|
||||
echo "Region does not exist"
|
||||
return 1
|
||||
fi
|
||||
|
||||
vlan_id=$(get_var "/regions/$region/spaces/$space/vlan")
|
||||
|
||||
echo "Subnet: $(get_vlan_ip $vlan_id 0)/21"
|
||||
echo "Firewall: $(get_vlan_ip $vlan_id 1)"
|
||||
echo "Aggregators:"
|
||||
|
||||
for aggregator in $(list_sections "/aggregators") ; do
|
||||
if [ "$(get_var $aggregator/region)" = $region ] ; then
|
||||
ip=$(get_vlan_ip $vlan_id $(get_var $aggregator/yap_id))
|
||||
echo " $(get_var $aggregator/name): $ip"
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
|
||||
#
|
||||
# Aggregator commands
|
||||
#
|
||||
@ -939,6 +1019,9 @@ case "$action" in
|
||||
space-delete)
|
||||
space_delete "$@"
|
||||
;;
|
||||
subnet-get)
|
||||
subnet_get "$@"
|
||||
;;
|
||||
agg-list|aggregator-list)
|
||||
aggregator_list "$@"
|
||||
;;
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user