Initial Home page

Introduction-to-Mizu.md

@@ -0,0 +1,62 @@
+Mizu as a Kubernetes-aware network sniffer, consists of two separate programs. One is CLI and the other one is Agent.
+
+## CLI
+
+Mizu CLI is the program that's responsible for the deployment of Mizu Agent to the Kubernetes cluster which your `kubectl`
+points to. Mizu CLI also configures the Mizu Agent according to the parameters supplied through, you guessed it CLI.
+
+It can be built using `make cli` command. Which is a `Makefile` rule.
+
+Mizu CLI is the program that's published under [the latest release](https://github.com/up9inc/mizu/releases/latest) section
+and the supported operating systems are macOS(darwin) and Linux (64-bit only).
+
+Another important job of Mizu CLI is that it automatically establishes a proxy to the Mizu Agent as soon as it's deployed.
+Such that the user can easily access to the web UI effortlessly.
+
+## Agent
+
+Mizu Agent is a Docker image that's pulled into the subject Kubernetes cluster. Mizu CLI is the software that orchestrates this deployment.
+The default image of Mizu Agent is `gcr.io/up9-docker-hub/mizu/main:latest` but it can be changed to a custom image
+using `--set agent-image=<IMAGE>` CLI option or setting `agent-image: <IMAGE>` in `~/.mizu/config.yaml`.
+
+The repository hosts a Docker image in the root directory. A simple Docker build and push is enough to have your own
+custom Mizu Agent version in Docker Hub, like below:
+
+```bash
+docker build . -t username/mizuagent:latest && docker push username/mizuagent:latest
+```
+
+Mizu Agent consists of at least two pods and while being a single Docker image, it has actually two main modes that makes it serve for two fundamental purposes:
+- **Tapper:** Listens a Linux network interface of given Kubernetes namespace.
+- **API Server:** Acts as a hub for the tappers and provide a REST API and WebSocket connections to monitor the traffic.
+
+### Tapper
+
+Tapper pod is the heart of Mizu. It listens the network traffic (TCP packets), dissects them and streams them to the API server.
+It listens all active ports, tries to analyze the incoming TCP streams and identify the protocols.
+
+Currently Mizu supports these TCP-based protocols:
+
+- HTTP 1.1
+- gRPC (HTTP/2)
+- AMQP
+- Kafka
+- Redis
+
+Mizu aims to understand the traffic above the Transport layer in OSI Model. It's currently only capable of
+recognizing Application and Presentation layer. The UDP in Transport layer is out-of-scope for Mizu.
+
+In a Kubernetes cluster, there can be one or many tappers. The number of tappers scales with the number of nodes in
+a given Kubernetes namespace. Nodes mean machines, so each machine needs its own tapper.
+
+Tapper is an extremely parallel software thanks to the Goroutines and it's able to keep up with high traffic loads.
+Although just like any other software, it's limited by the physical resources like the CPU and memory. It's not
+a disk intensive program.
+
+### API Server
+
+If the tapper was a freeway, the API server would be a highway. It's the road where all the other roads connected into.
+
+The API server pod communicates with the tappers through a series of WebSocket pipelines and eventually streams
+the dissected traffic into web UI. It's, in its essence, a web application. Such that it provides a REST API, a server
+for the React app (web UI) and let's you do a bunch of other things that can be done after the traffic analysis step.