Skip to content

Commit 9e7b463

Browse files
parthyadav3105parthyadav3105
committed
Design: Initial basic KupenStack Virtual Router CR Proposal
Signed-off-by: Parth Yadav<parthyadav3105@gmail.com>
1 parent 178ba0c commit 9e7b463

1 file changed

Lines changed: 196 additions & 0 deletions

File tree

‎design-doc/custom-resources/virtualrouter.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# VirtualRouter
2+
3+
* [Summary](#Summary)
4+
* [Motivation](#Motivation)
5+
* [Design Details](#Design-Details)
6+
* [API](#API)
7+
* [Overview](#Overview)
8+
* [ExternalNetwork](#ExternalNetwork)
9+
* [VirtualNetworks](#VirtualNetworks)
10+
* [ExtendScope](#ExtendScope)
11+
* [Routes](#Routes)
12+
* [Creation Considerations](#Creation-Considerations)
13+
* [Deletion Considerations](#Deletion-Considerations)
14+
* [Updation Considerations](#Updation-Considerations)
15+
* [Other implementation considerations](#Other-implementation-considerations)
16+
* [Functioning at OpenStack](#Functioning-at-OpenStack)
17+
18+
### Summary
19+
20+
This document covers design specification, functionality, details for **VirtualRouter** custom resource(CR) in KupenStack. A Virtual Router CR manages router resources in the associated OpenStack cluster.
21+
22+
### Motivation
23+
24+
In networking, routers are used to provide connectivity between hosts on different networks. They decide how a packet should be routed. In KupenStack there are various VirtualNetworks(VN) separated by namespaces. VirtualMachines(VM) connected to these VN may require to communicate with VMs in another VN. A Virtual Router can solve this problem.
25+
26+
Also, a VM may want to connect to an external network, a Virtual Router can solve this problem as well.
27+
28+
Therefore, it is required to have a Virtual Router CR that can dynamically connect to these VNs and an external network to provide required connectivity to workloads connected to them.
29+
30+
### Design Details
31+
32+
#### API
33+
34+
```yaml
35+
apiVersion: kupenstack.io/v1alpha1
36+
kind: VirtualRouter
37+
# shortName=vr
38+
39+
metadata:
40+
# scope=Namespaced
41+
name: sample-router
42+
namespace: default
43+
44+
spec:
45+
46+
# Name of the External Network that the router uses as its gateway.
47+
# required=false, type=string
48+
externalNetwork: provider-net
49+
50+
# Virtual Networks that should connect to this router.
51+
# required=false, type=object
52+
virtualNetworks:
53+
selector:
54+
# MatchLabels takes multiple key:value labels. These labels are used to
55+
# search the required virtual networks to connect.
56+
matchLabels:
57+
key: value
58+
key2: value
59+
60+
# ExtendScope takes a list of the names of additional namespaces inside which router
61+
# should search vitual networks, in addition to its own namespace.
62+
# required=false, type=array
63+
extendScope:
64+
- "backend-ns"
65+
- "database-ns"
66+
- "dev-ns"
67+
68+
# Routes defines the static routes.
69+
# required=false, type=array
70+
routes:
71+
- destinationCidr: "10.10.100.0/24"
72+
nextHopIP: "172.168.10.5"
73+
74+
status:
75+
76+
# Id of router at openstack cloud.
77+
# type=string
78+
id: a29d8-1d73n-2dw45-h4hr2
79+
80+
# Whether virtual router is ready for use or not.
81+
# type=boolean
82+
ready: true
83+
84+
# Contains list of all the virtual networks connected to this virtual router.
85+
# type=array
86+
virtualNetworkList: [ "Namespace/Name" ]
87+
88+
# IP address of virtual router from external network
89+
# type=string
90+
exteranlIP: "172.29.249.149"
91+
92+
```
93+
94+
**Output on `kubectl get virtualrouters` or `kubectl get vr`**
95+
96+
```
97+
NAME EXTERNAL-NETWORK EXTERNAL-IP AGE
98+
sample-router provider-net 172.29.249.149 47m
99+
```
100+
101+
**Output on `kubectl get vr -o wide`**
102+
103+
```
104+
NAME EXTERNAL-NETWORK EXTERNAL-IP AGE
105+
sample-router provider-net 172.29.249.149 47m
106+
```
107+
108+
#### Overview
109+
110+
Virtual Router CR is a namespaced resource. It can connect to many virtual networks and only one external network. Virtual Router(VR) uses the external network as its default gateway. By default the scope of VR is limited to the namespace it is created in.
111+
112+
###### ExternalNetwork
113+
114+
External networks are special networks in KupenStack. These are cluster scoped. A VR can connect to anyone from the available external networks. This external network is then used as the default gateway by this VR.
115+
116+
###### VirtualNetworks
117+
118+
VR can connect to multiple virtual networks. This field uses the approach of labels and selectors to dynamically connect to all the available virtual networks with matching labels in its scope. By default the scope of VR is limited to the namespace it is created in.
119+
120+
###### ExtendScope
121+
122+
This field takes a list of namespaces and extends the scope of VR from the current namespace to the new namespaces specified in the list. This may be required to provide connectivity between VN from different namespaces.
123+
124+
###### Routes
125+
126+
This field takes a list of static routes to use for this virtual router. Every route is defined by two fields `destinationCidr` and `nextHopIP`. The `destinationCidr` defines the IP range that the packet may be destined to and `nextHopIP` tells the IP to which this packet should be routed to.
127+
128+
#### Creation Considerations
129+
130+
All fields in a VR are optional, hence VR can be created with minimal configuration as follow:
131+
132+
```yaml
133+
# Minimal Virtual Network example
134+
apiVersion: kupenstack.io/v1alpha1
135+
kind: VirtualRouter
136+
metadata:
137+
name: sample-router
138+
---
139+
```
140+
141+
Suppose the goal is to route traffic between workloads of two VNs namely, `my-vn1` and `my-vn2` in `ns1` then we need to create a VR that connects these two VN. First, make sure that both VNs have some common labels that can be used to select them let's say `router`=`my-vr1`. Now create a VR in the same namespace `ns1` that tries to connect to these two VN as follow:
142+
143+
```yaml
144+
# VR that connects to all VN with labels router=my-vr1 (VN in same namespace)
145+
apiVersion: kupenstack.io/v1alpha1
146+
kind: VirtualRouter
147+
metadata:
148+
name: sample-router
149+
namespace: ns1
150+
spec:
151+
virtualNetworks:
152+
selector:
153+
matchLabels:
154+
router: my-vr1
155+
---
156+
```
157+
158+
Now, our two VNs have a virtual router connecting them.
159+
160+
Let us say that `my-vn2` is in a different namespace called `ns2` instead of `ns1` then the above VR custom resource has to be slightly modified. We need to add `ns2` in the scope of our VR as follow:
161+
162+
```yaml
163+
# VR that connects to all VN with labels router=my-vr1 (VN in different namespace)
164+
apiVersion: kupenstack.io/v1alpha1
165+
kind: VirtualRouter
166+
metadata:
167+
name: sample-router
168+
namespace: ns1
169+
spec:
170+
extendScope:
171+
- "ns2"
172+
virtualNetworks:
173+
selector:
174+
matchLabels:
175+
router: my-vr1
176+
---
177+
```
178+
179+
#### Deletion Considerations
180+
181+
VR does not have any pre-clean-up requirements. Deleting a VR deletes it. But it is to be noted that if a VR is deleted then all VN connected to it will loose connection to it.
182+
183+
#### Updation Considerations
184+
185+
All fields of VR are mutable and can be changed.
186+
187+
### Other implementation considerations
188+
189+
Nil.
190+
191+
### Functioning at OpenStack
192+
193+
*Note: This section describes how Virtual Routers are implemented internally using OpenStack. This section serve as an extra documentation to explain what is happening behind at the OpenStack. Although as a KupenStack user who is working with custom resources, this knowledge may not be required. Feel free to skip this section.*
194+
195+
* When a VR is created in KupenStack then a Router resource is created in OpenStack for it. VR stores the reference of the Router ID from OpenStack.
196+
* VR creates a Router with Admin State True.

0 commit comments

Comments
 (0)