Skip to content

Commit

Permalink
docs(riklet):add network impl
Browse files Browse the repository at this point in the history 
Signed-off-by: AlexandreBrg <burgoni@pm.me>
  • Loading branch information
@alexandrebrg
alexandrebrg committed Apr 26, 2023
1 parent 4f9a81b commit 64e38d9
Show file tree
Hide file tree
Showing 6 changed files with 145 additions and 103 deletions.
5 changes: 3 additions & 2 deletions docs/src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,6 @@
---

- [Developer Reference]()
- [Controller](./controller.md)
- [Network](./network.md)
- [Controller](./reference/controller.md)
- [Network](./reference/network.md)
- [Riklet](./reference/network/riklet.md)
30 changes: 0 additions & 30 deletions docs/src/controller.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1 @@
# Controller

## Configuration

| Environment variable | Default | Description |
|:---------------------|-------------------------|--------------------------------|
| `DATABASE_LOCATION` | `/var/lib/rik/data/` | Database data location |
| `SCHEDULER_URL` | `http://localhost:4996` | Host location of the scheduler |
| `PORT` | `5000` | Port to listen on |


## Database structure

**Workloads**:

* `element_type`: `/workload`

* `element_id`: `/workload/${WORKLOAD_KIND}/${NAMESPACE}/${WORKLOAD_NAME}`
* *WORKLOAD_KIND*: One of`pods`, `function`
* *NAMESPACE*: Static `default`
* *WORKLOAD_NAME*: Dynamically defined


**Instances**:

* `element_type`: `/instance`

* `element_id`: `/instance/${WORKLOAD_KIND}/${NAMESPACE}/${INSTANCE_NAME}`
* *WORKLOAD_KIND*: One of`pods`, `function`
* *NAMESPACE*: Static `default`
* *INSTANCE_NAME*: Dynamically defined
71 changes: 0 additions & 71 deletions docs/src/network.md
View file
Original file line number Diff line number Diff line change
@@ -1,72 +1 @@
# Network

This project has network features, it's state is **unstable** and should be used
with caution as it is managing your network interfaces and routing. We are doing
our best not to break your system's network!

*In this document words Network and SDN (Software Designed Network) have the
same meaning*.

## Workloads

Current workloads cannot be configured with network implementation, however
`Function` workload implement a first version of network configuration which
can't be configured yet.

## Riklet

This component onboard a network component which will manage network exposure
and routing. Depending on the workload, it will be configured to use a specific
network implementation. For now, only `Function` workload have an implementation
of network configuration. This implementation is based on `iptables` and
[`rtnetlink`](https://man7.org/linux/man-pages/man7/rtnetlink.7.html).

## Function network

Current implementation is based on usage of `iptables`, it will apply NAT rules
on current network configuration. Moreover, it will apply PAT (Port Address
Translation) on the host machine to expose the workload on a specific port.

```ignore
┌──────────────────────────────────────────────────────────────────┐
│ Host Machine (riklet) │
│ │
│ │
│ ┌─────────────────────────────┐ ┌─────────────────────────┐ │
│ │Iptables │ │ Function Instance │ │
│ │ │ │ │ │
│ │ ┌─────────────────────────┐ │ │ │ │
│ │ │APPLY NAT ON │ │ │┌───────────────────────┐│ │
│ │ │host:${port} │ │ ││ Guest_veth ││ │
│ │ │ │ │ ││ ││ │
│ │ │TO │─┼┐ │└───────────────────────┘│ │
│ │ │host_tap:${service_port} │ ││ │ ▲ │ │
│ │ │ │ ││ └────────────┼────────────┘ │
│ │ └─────────────────────────┘ ││ │ │
│ │ ▲ ││ │ │
│ └──────────────┼──────────────┘│ ┌───────────────────────┐ │
│ │ │ │ Host_tap │ │
│ │ └──▶│ │ │
│ │ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │Host Ethernet Interface│ │
│ │ │ │
│ └───────────────────────┘ │
│ ▲ │
└─────────────────┼────────────────────────────────────────────────┘
│
│
│
.───────.
,─' '─.
,' `.
; :
│ │
│ World Wide Web │
: ;
╲ ╱
`. ,'
'─. ,─'
`─────'
```
31 changes: 31 additions & 0 deletions docs/src/reference/controller.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Controller

## Configuration

| Environment variable | Default | Description |
|:---------------------|-------------------------|--------------------------------|
| `DATABASE_LOCATION` | `/var/lib/rik/data/` | Database data location |
| `SCHEDULER_URL` | `http://localhost:4996` | Host location of the scheduler |
| `PORT` | `5000` | Port to listen on |


## Database structure

**Workloads**:

* `element_type`: `/workload`

* `element_id`: `/workload/${WORKLOAD_KIND}/${NAMESPACE}/${WORKLOAD_NAME}`
* *WORKLOAD_KIND*: One of`pods`, `function`
* *NAMESPACE*: Static `default`
* *WORKLOAD_NAME*: Dynamically defined


**Instances**:

* `element_type`: `/instance`

* `element_id`: `/instance/${WORKLOAD_KIND}/${NAMESPACE}/${INSTANCE_NAME}`
* *WORKLOAD_KIND*: One of`pods`, `function`
* *NAMESPACE*: Static `default`
* *INSTANCE_NAME*: Dynamically defined
12 changes: 12 additions & 0 deletions docs/src/reference/network.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Network

This project has network features, it's state is **unstable** and should be used
with caution as it is managing your network interfaces and routing. We are doing
our best not to break your system's network!

## Workloads

Current workloads cannot be configured with network implementation, however
`Function` workload implement a first version of network configuration which
can't be configured yet.

99 changes: 99 additions & 0 deletions docs/src/reference/network/riklet.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# Riklet SDN

This component onboard a network component which will manage network exposure
and routing. Depending on the workload, it will be configured to use a specific
network implementation. For now, only `Function` workload have an implementation
of network configuration. This implementation is based on `iptables` and
[`rtnetlink`](https://man7.org/linux/man-pages/man7/rtnetlink.7.html).

## Function network implementation

This network feature allows you to forward traffic from a specific port to a
Function instance port. We achieve this using `iptables`, a widely used linux
tool for managing network traffic. The translation of IP and port is targetting
a [TAP](https://www.gabriel.urdhr.fr/2021/05/08/tuntap/) interface on the
machine that is communicating with the Function instance (microVM).

```ignore
┌──────────────────────────────────────────────────────────────────┐
│ Host Machine (riklet) │
│ │
│ │
│ ┌─────────────────────────────┐ ┌─────────────────────────┐ │
│ │Iptables │ │ Function Instance │ │
│ │ │ │ │ │
│ │ ┌─────────────────────────┐ │ │ │ │
│ │ │APPLY NAT ON │ │ │┌───────────────────────┐│ │
│ │ │host:${port} │ │ ││ Guest_veth ││ │
│ │ │ │ │ ││ ││ │
│ │ │TO │─┼┐ │└───────────────────────┘│ │
│ │ │host_tap:${service_port} │ ││ │ ▲ │ │
│ │ │ │ ││ └────────────┼────────────┘ │
│ │ └─────────────────────────┘ ││ │ │
│ │ ▲ ││ │ │
│ └──────────────┼──────────────┘│ ┌───────────────────────┐ │
│ │ │ │ Host_tap │ │
│ │ └──▶│ │ │
│ │ └───────────────────────┘ │
│ ┌───────────────────────┐ │
│ │Host Ethernet Interface│ │
│ │ │ │
│ └───────────────────────┘ │
│ ▲ │
└─────────────────┼────────────────────────────────────────────────┘
│
```

This is what the network configuration looks like when you deploy a Function
instance with a port mapping, please not it is very specific to Function. The
`host_tap` interface is created by the
`riklet` and is used to communicate with the Function instance. The `Guest_veth`
interface is created by the `firecracker` microVM and is used to communicate
with the `host_tap` interface. The `host_tap` is connecteed to the internet and
is not restricted in bandwidth.

## Iptables

Riklet will use a custom chain called `RIKLET` on the table nat to do DNAT (Destination NAT), it
matches two use cases:

- Local processes: when another workload wants to communicate with a Function
instance
- Internet: when the workload needs to be exposed externally on the worker node


```ignore
.─────────────────. .─────────────────.
,─' '─. ,─' '─.
( Local processes ) ( Internet )
`──. _.─' `──. _.─'
`───────────────' `───────────────'
│ │
│ │
│ │
▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ OUTPUT (nat) │ │ PREROUTING (nat) │
└────────────────────┘ └────────────────────┘
│ │
│ │
│ ┌──────────────────────────┤
│ │ │
▼ ▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ RIKLET (nat) │───────────▶│ FORWARD │
└────────────────────┘ └────────────────────┘
│
│
│
│
▼
┌────────────────────┐
│ POSTROUTING │
└────────────────────┘
│
│
│
▼
```

0 comments on commit 64e38d9

Please sign in to comment.