Skip to content
Snippets Groups Projects
Commit db6539bf authored by Alejandro Tjaarda's avatar Alejandro Tjaarda
Browse files

documentation: added general development and use documentation

parent 839ecc3d
No related branches found
No related tags found
1 merge request!2repo: added new directory where utils scripts will be
...@@ -6,7 +6,7 @@ The following figure outlines a high-level overview of L2S-M, with an illustrati ...@@ -6,7 +6,7 @@ The following figure outlines a high-level overview of L2S-M, with an illustrati
![alt text](../assets/v1_architecture.png?raw=true) ![alt text](../assets/v1_architecture.png?raw=true)
**NOTE**: The current version of L2S-M utilizes an infrastructure of virtual switches based on [Open Virtual Switch (OVS)](http://www.openvswitch.org). The integration of physical switches is currently ongoing. **NOTE**: The current version of L2S-M utilizes an infrastructure of virtual switches based on [Open Virtual Switch (OVS)](http://www.openvswitch.org). This implementation can be followed up in https://github.com/Networks-it-uc3m/l2sm-switch .
In L2S-M, a k8s node deploys a virtual SDN switch or is connected to a physical SDN switch. Virtual switches are interconnected through point-to-point links. These links are established using IP tunnels (based on VXLAN technologies). This way, SDN switches build an overlay network that interconnects all the K8s nodes. L2S-M uses an SDN controller to install forwarding rules on the virtual/physical switches. This way, data traffic among workloads is appropriately distributed through isolated virtual networks (i.e., the SDN controller instructs the switches which ports should be used to forward and/or block incoming/outgoing traffic). In L2S-M, a k8s node deploys a virtual SDN switch or is connected to a physical SDN switch. Virtual switches are interconnected through point-to-point links. These links are established using IP tunnels (based on VXLAN technologies). This way, SDN switches build an overlay network that interconnects all the K8s nodes. L2S-M uses an SDN controller to install forwarding rules on the virtual/physical switches. This way, data traffic among workloads is appropriately distributed through isolated virtual networks (i.e., the SDN controller instructs the switches which ports should be used to forward and/or block incoming/outgoing traffic).
...@@ -14,6 +14,6 @@ Specifically for K8s clusters, the element in charge of managing the creation, d ...@@ -14,6 +14,6 @@ Specifically for K8s clusters, the element in charge of managing the creation, d
To provide isolation among virtual networks, the operator interacts with the SDN controller component to communicate which ports are associated with each virtual network, updating its status every time a pod is deployed/deleted. Using this information, the SDN controller injects the corresponding rules in the switches, forwarding and/or blocking traffic according to the virtual networks being used at each moment. To provide isolation among virtual networks, the operator interacts with the SDN controller component to communicate which ports are associated with each virtual network, updating its status every time a pod is deployed/deleted. Using this information, the SDN controller injects the corresponding rules in the switches, forwarding and/or blocking traffic according to the virtual networks being used at each moment.
**NOTE**: The current version of L2S-M utilizes a simple-switch implementation based on the [RYU](https://ryu.readthedocs.io/en/latest/) SDN controller. An SDN application to specifically support virtual network isolation is currently under implementation. **NOTE**: The current version of L2S-M utilizes a custom implementation of SDN controller. This sdn controller implementation can be seen at https://github.com/Networks-it-uc3m/l2sm-controller .
More information on how to deploy virtualise workloads attached to virtual networks can be seen in the [ping-pong](https://github.com/Networks-it-uc3m/L2S-M/tree/main/examples/ping-pong) example. More information on how to use this solution can be seen in the [how to use guide](./general-use.md).
# General Use of L2S-M Application
This document will guide you through the usage of L2S-M, a tool designed to manage L2 networks, overlays, and Network Edge Devices (NEDs) within a Kubernetes cluster environment. L2S-M uses Custom Resource Definitions (CRDs) to enable flexible network management and pod attachment within Kubernetes.
For more specific examples, you can go to the [examples section](../examples/), this document is meant to be a general use guide.
## Custom Resource Definitions (CRDs)
L2S-M introduces three core CRDs that allow users to configure networks, overlays, and edge devices dynamically:
### 1. **L2Network CRD**
- **Purpose**: Defines a Layer 2 virtual network inside the Kubernetes environment.
- **Configurable Fields**:
- **Network Type**: Specifies the type of network.
- **Connectivity**: Controls the connection with the Software-Defined Networking (SDN) controller.
- **Connected Pods**: Lists the pods connected to this network.
- **Usage**: Once a network is defined, pods can be connected to it. The L2Network CRD provides specifications through the `spec` field, where the user defines the network attributes, while the `status` field reports the current state of the network, including the pods connected to it.
- An example of this CR can be found [here](../config/samples/l2sm_v1_l2network.yaml)
### 2. **Overlay CRD**
- **Purpose**: Defines the logical connections between nodes in the cluster, creating the overlay network.
- **Configurable Fields**:
- **Topology**: Specifies how nodes should be interconnected.
- **Switch Template**: Defines the type of switches used within the overlay.
- **Network Controller**: Identifies the SDN controller responsible for managing the topology.
- **Usage**: Administrators can use the Overlay CRD to define the connections between nodes based on their resource capacities or geographic location, creating custom topologies suited to specific needs.
- An example of this CR can be found [here](../config/samples/l2sm_v1_overlay.yaml)
### 3. **NetworkEdgeDevice (NED) CRD**
- **Purpose**: Extends the network beyond the cluster, enabling communication with external networks or other clusters.
- **Configurable Fields**:
- **Device Type**: Defines the hardware or software that forms the edge device.
- **Connections**: Specifies the external networks or clusters this NED should connect to.
- **Usage**: The NED CRD facilitates inter-cluster communication by connecting Kubernetes clusters or other platforms like OpenStack. Each NED is controlled by an SDN controller for dynamic flow control and traffic management.
- An example of this CR can be found [here](../config/samples/l2sm_v1_networkedgedevice.yaml)
## Attaching Pods to Networks
Pods can be dynamically attached to L2 networks defined by the L2Network CRD. This process involves the following steps:
1. **Defining the L2Network**: Use the L2Network CRD to create a network in Kubernetes. The network will be managed by the L2S-M controller, which communicates with the SDN controller to configure the necessary networking parameters.
2. **Scheduling Pods**: When a pod is deployed in the cluster, it can be attached to the L2Network by specifying the network during the pod creation process. The L2S-M controller will automatically configure the required network interfaces and assign IP addresses via the integrated IP Address Management (IPAM) system.
3. **Monitoring Connectivity**: Once attached, the status of the pod’s network connectivity can be checked via the L2Network CRD’s `status` field, which will list all connected pods and report any changes in the connectivity state.
...@@ -11,30 +11,23 @@ This component is essentially a set of Custom Resource Definitions (CRDs) accomp ...@@ -11,30 +11,23 @@ This component is essentially a set of Custom Resource Definitions (CRDs) accomp
- Access to a Kubernetes v1.11.3+ cluster. - Access to a Kubernetes v1.11.3+ cluster.
### To Deploy on the cluster ### To Deploy on the cluster
**Build and push your image to the location specified by `IMG`:** **Build and push your image to the location specified by `IMG`, inside the Makefile:**
```sh ```sh
make docker-build docker-push IMG=<some-registry>/l2network:tag make docker-build docker-push
``` ```
**NOTE:** This image ought to be published in the personal registry you specified. **NOTE:** The image ought to be published in the personal registry you specified.
And it is required to have access to pull the image from the working environment. And it is required to have access to pull the image from the working environment.
Make sure you have the proper permission to the registry if the above commands don’t work. Make sure you have the proper permission to the registry if the above commands don’t work.
**Install the CRDs into the cluster:**
```sh
make install
```
**Deploy the Manager to the cluster with the image specified by `IMG`:** **Deploy the Manager to the cluster with the image specified by `IMG`:**
```sh ```sh
make deploy IMG=<some-registry>/l2network:tag make deploy
``` ```
> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
privileges or be logged in as admin.
**Create instances of your solution** **Create instances of your solution**
You can apply the samples (examples) from the config/sample: You can apply the samples (examples) from the config/sample:
...@@ -52,17 +45,47 @@ kubectl apply -k config/samples/ ...@@ -52,17 +45,47 @@ kubectl apply -k config/samples/
kubectl delete -k config/samples/ kubectl delete -k config/samples/
``` ```
**Delete the APIs(CRDs) from the cluster:** **UnDeploy the controller from the cluster:**
```sh ```sh
make uninstall make undeploy
``` ```
**UnDeploy the controller from the cluster:**
> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
privileges or be logged in as admin.
### To Run locally the solution and make your custom changes
If you are interested in running the solution locally, feel free to make your own branch and start developing! Any feedback is welcome as well.
We provide the following commands to run the application locally
1. **Install the CRDs into the cluster:**
```sh ```sh
make undeploy make install
``` ```
2. **Deploy the webhook server locally:**
```sh
make deploy-webhook
```
3. **Run the application with the changes:**
```sh
make run
```
And once you've finished:
**Delete the APIs(CRDs) from the cluster:**
```sh
make uninstall
```
**Remove the Webhook Server from the cluster:**
```sh
make undeploy-webhook
```
## Project Distribution ## Project Distribution
...@@ -71,11 +94,11 @@ Following are the steps to build the installer and distribute this project to us ...@@ -71,11 +94,11 @@ Following are the steps to build the installer and distribute this project to us
1. Build the installer for the image built and published in the registry: 1. Build the installer for the image built and published in the registry:
```sh ```sh
make build-installer IMG=<some-registry>/l2network:tag make build-installer
``` ```
NOTE: The makefile target mentioned above generates an 'install.yaml' NOTE: The makefile target mentioned above generates an 'install.yaml'
file in the dist directory. This file contains all the resources built file in the deployment directory. This file contains all the resources built
with Kustomize, which are necessary to install this project without with Kustomize, which are necessary to install this project without
its dependencies. its dependencies.
...@@ -84,5 +107,5 @@ its dependencies. ...@@ -84,5 +107,5 @@ its dependencies.
Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project, i.e.: Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project, i.e.:
```sh ```sh
kubectl apply -f https://raw.githubusercontent.com/<org>/l2network/<tag or branch>/deployments/install.yaml kubectl apply -f https://raw.githubusercontent.com/<org>/L2S-M/<tag or branch>/deployments/install.yaml
``` ```
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment