add concepts doc

Author: gxben

content/en/docs/concepts/_index.md

@@ -12,13 +12,13 @@ Local data centers consist of a bunch of physical machines (can range from perso
 
 From an IT and assets management's perspective, one simply needs to ensure they run and, capacity planning in mind, that they do offer enough physical resources to sustain future applications hosting needs.
 
-On each data-center, some physical machines (usually lightweight) will be dedicated to providing networking kind of services, through Kowabunga's **Kiwi** agents, while others will providing computing and storage capabilities, thanks to Kowabunga's **Kaktus** agents.
+On each data-center, some physical machines (usually lightweight) will be dedicated to providing networking kind of services, through Kowabunga's [Kiwi](/docs/concepts/kiwi/) agents, while others will providing computing and storage capabilities, thanks to Kowabunga's [Kaktus](/docs/concepts/kaktus/) agents.
 
 ![](concept.png)
 
-The Kowabunga project then come with **Kahuna**, its orchestration engine. This is the masterpiece cornerstone of your architecture. Kahuna act as a maestro, providing API servicess for admins and end-users, and provising and controlling virtual resources on the various data-centers through Kowabunga connected agents.
+The Kowabunga project then come with [Kahuna](/docs/concepts/kahuna/), its orchestration engine. This is the masterpiece cornerstone of your architecture. Kahuna act as a maestro, providing API servicess for admins and end-users, and provising and controlling virtual resources on the various data-centers through Kowabunga connected agents.
 
-Ultimately, DevOps consumers will only ever interface with **Kahuna**.
+Ultimately, DevOps consumers will only ever interface with [Kahuna](/docs/concepts/kahuna/).
 
 So, how does magic happen ?
 
@@ -32,10 +32,10 @@ So, how does magic happen ?
 
 So, let's rewind, the Kowabunga projects consists of multiple core components:
 
-- **Kahuna**: the core orchestration system. Remotely controls every resource and maintains ecosystem consistent. Gateway to the Kowabunga REST API.
-- **Kaktus**: the HCI node(s). Provides KVM-based virtual computing hypervisor with Ceph-based distributed storage services.
-- **Kiwi**: the SD-WAN node(s). Provides various network services like routing, firewall, DHCP, DNS, VPN, peering (with active-passive failover).
-- **Koala**: the WebUI. Allows for day-to-day supervision and operation of the various projects and services.
+- [Kahuna](/docs/concepts/kahuna/): the core orchestration system. Remotely controls every resource and maintains ecosystem consistent. Gateway to the Kowabunga REST API.
+- [Kaktus](/docs/concepts/kaktus/): the HCI node(s). Provides KVM-based virtual computing hypervisor with Ceph-based distributed storage services.
+- [Kiwi](/docs/concepts/kiwi/): the SD-WAN node(s). Provides various network services like routing, firewall, DHCP, DNS, VPN, peering (with active-passive failover).
+- [Koala](/docs/concepts/koala/): the WebUI. Allows for day-to-day supervision and operation of the various projects and services.
 
 Aside from these, Kowabunga introduces the concept of:
 
@@ -93,5 +93,5 @@ But aside from cost, Kowabunga has been developed by and for DevOps, the ones wh
 {{% alert color="success" title="Tips for Managed Services Provider" %}}
 If you're acting as a **Managed Services Provider** (MSP) having to sustain various applications for dozens if not hundreds of customers, **Kowabunga** might come in handy.
 
-Simply picture your various customer on-premises data-centers as Kowabunga regions. All autonomous, un-aware of each others, non-exposed to Internet (hello IT !), yet fully remotely manageable in a single unique way, thanks to **Kahuna**'s orchestration !
+Simply picture your various customer on-premises data-centers as Kowabunga regions. All autonomous, un-aware of each others, non-exposed to Internet (hello IT !), yet fully remotely manageable in a single unique way, thanks to [Kahuna](/docs/concepts/kahuna/)'s orchestration !
 {{% /alert %}}

content/en/docs/concepts/kahuna.md

@@ -1,5 +1,49 @@
 ---
 title: Kahuna
-description: Learn about Kahuna conceptual architecture
+description: Learn about Kahuna orchestrator.
 weight: 3
 ---
+
+**Kahuna** is Kowabunga's orchestration system. Its name takes root from Hawaiian's **(Big) Kahuna** word, meaning *"the expert, the most dominant thing"*.
+
+**Kahuna** remotely controls every resource and maintains ecosystem consistent. It's the gateway to Kowabunga REST API.
+
+From a technological stack perspective, **Kahuna** features:
+
+- a [Caddy](https://caddyserver.com/) public HTTPS frontend, reverse-proxying requests to:
+  - [Koala](/docs/concepts/koala/) Web application, or
+  - **Kahuna** orchestrator daemon
+- a [MongoDB](https://www.mongodb.com/) database backend.
+
+The **Kahuna** orchestrator features:
+
+- **Public REST API handler**: implements and operates the API calls to manage resources,interacting with rightful local agents through JSON-RPC over WSS.
+- **Public WebSocket handler**: agent connection manager, where the various agents establish secure WebSocket tunnels to, for being further controlled, bypassing on-premises firewall constraints and preventing the need of any public service exposure.
+- **Metadata endpoint**: where managed virtual instances and services can retrieve information services and self-configure themselves.
+
+Kowabunga API folds into 2 type of assets:
+
+- **admin** ones, used to handle objects like region, zone, kaktus and kiwi hosts, agents, networks ...
+- **user** ones, used to handle objects such as **Kompute**, **Kawaii**, **Konvey** ...
+
+**Kahuna** implements robust RABC and segregation of duty as to ensure access boundaries, such as:
+
+- Nominative RBAC capabilities and per-organization and team user management.
+- Per-project teams associationfor per-resource access control.
+- Support for both JWT bearer (human-to-server) and API-Key token-based (server-to-server) authentication mechanisms.
+- Support for 2-steps account creation/validation and enforced robust passwords/tokens usage(server-generated, user-input is prohibited).
+- Nominative robust HMAC ID+token credentials over secured WebSocket agent connections.
+
+This ensures that:
+
+- only rightful designated agents are able to establish WSS connections with **Kahuna**
+- created virtual instances can only retrieve the metadata profile they belong to (and self configure or update themselves at boot or runtime).
+- users can only see and manage resources for the projects they belong to.
+
+{{< alert color="warning" title="Warning" >}}
+Despite being central, **Kahuna**'s implementation does not yet allow for stateless distribution.
+
+The current design with DB caches and WebSocket connection makes it hard to distribute without involving a message queue middleware. This is a good problem for the future, but not for now. A single Kahuna instance is perefeclty capable of handling multiple thousands of concurrent connections, which we believe to be more than enough for a private platform orchestrator (it wouldn't for a large-scale public Cloud one).
+
+Providing **Kahuna** with high-availability remains however fully possible, using good-old active-passive failover mechanism.
+{{< /alert >}}

content/en/docs/concepts/kaktus.md

@@ -1,5 +1,44 @@
 ---
 title: Kaktus
-description: Learn about Kaktus conceptual architecture
+description: Learn about Kaktus HCI node.
 weight: 6
 ---
+
+**Kaktus** stands for **K**owabunga **A**ffordable **K**vm and **TU**rnkey **S**torage (!!), basically, our Hyper-Converged Infrastructure (HCI) node.
+
+While large virtualization systems such as VMware usually requires you to dedicate servers as computing hypervisors (with plenty of CPU and memory) and associate them with remote, extensive NAS or vSAN, providing storage, Kowabunga follows the opposite approach. Modern hardware is powerful enough to handle both computing and storage.
+
+This approach allows you to:
+
+- use commodity hardware, if needed
+- use heterogenous hardware, each member of the pool featuring more or less computing and storage resources.
+
+If you're already ordering a heavy computing rackable server, extending it with 4-8 SSDs is always going to be cheaper than adding an extra enterprise SAN.
+
+**Kaktus** nodes will then consists of
+
+- a [KVM](https://linux-kvm.org/page/Main_Page)/[QEMU](https://www.qemu.org/) + [libvirt](https://libvirt.org/) virtualization computing stack. Featuring all possible VT-x and VT-d assistance on x86_64 architectures, it'll provide near passthrough virtualization capabilities.
+- several local disks, to be part of a region-global [Ceph](https://ceph.io/en/) distributed storage cluster.
+- the **Kowabunga Kaktus agent**, connected to **Kahuna**
+
+**Kaktus agent** controls the local **KVM** hypervisor through **libvirt** backend and the local-network distributed **Ceph** storage, allowing management of virtual machines and disks.
+
+{{< alert color="success" title="Note" >}}
+When configured for production-systems, Ceph storage cluster will be backed by cross-zones N-times (usually 3) replicated high-performance block devices, providing virtually infinitely scalable and resizeable disk volumes with byte-precision.
+
+Virtual disks contents being sharded into thousands of fragmented objects, spread across the various disks from the various **Kaktus** instances of a given region, the "chance" of data loss or corruption is close to none.
+{{< /alert >}}
+
+{{< alert color="warning" title="Enterprise Recommendations" >}}
+If you intend to use Kowabunga to run serious business (and we hope you'll do), you need to ensure to give Ceph its full potential.
+
+Too many Cloud systems are today limited (CPU stuck in I/O wait) by disk bandwidth. Using Ceph, implies that your disks I/Os are to be adressed through network. Simply put, don't expect to get NVME SSDs access time.
+
+In order to ensure the fastest storage possible, it remains key that you:
+
+- use local NVMe SSDs on as much server instances as possible (they'll all be part of the same cluster pool).
+- use physical servers with at 10 Gbps network interfaces (25 Gbps is even better, link-agregation is a nice bonus).
+- ensure that your regional zones are less than 1ms away from each other.
+
+This may sounds like heavy requirements, but by today enterprise-grade standards, it's really isn't anymore ;-)
+{{< /alert >}}

content/en/docs/concepts/kiwi.md

@@ -1,5 +1,18 @@
 ---
 title: Kiwi
-description: Learn about Kiwi conceptual architecture
+description: Learn about Kiwi SD-WAN node.
 weight: 5
 ---
+
+**Kiwi** is Kowabunga SD-WAN node in your local data-center. It provides various network services like routing, firewall, DHCP, DNS, VPN and peering, all with active-passive failover (ideally over multiple zones).
+
+**Kiwi** is central to our regional infrastructure to operate smoothly and internal gateway to all your projects **Kawaii** private network instances. It controls the local network configuration and creates/updates VLANs, subnets and DNS entries per API requests.
+
+**Kiwi** offers a Kowabunga project's network isolation feature by enabling VLAN-bound, cross-zones, project-attributed, VPC L3 networking range. Created virtual instances and services are bound to VPC by default and never publicly exposed unless requested.
+
+Access to project's VPC resources is managed either through:
+
+- **Kiwi-managed** region-global VPN tunnels.
+- **Kawaii-managed** project-local VPN tunnels.
+
+Decision to do or another depends on private Kowabunga IT policy.

content/en/docs/concepts/koala.md

@@ -1,5 +1,17 @@
 ---
 title: Koala
-description: Learn about Koala conceptual architecture
+description: Learn about Koala Web application.
 weight: 4
 ---
+
+**Koala** is Kowabunga's WebUI. It allows for day-to-day supervision and operation of the various projects and services.
+
+![](/docs/concepts/koala.png)
+
+But should you ask a senior DevOps / SRE / IT admin, fully automation-driven, he'd damn anyone who'd have used the Web client to manually create/edit resources and messes around his perfecly maintained CasC.
+
+We've all been there !!
+
+That's why **Koala** has been designed to be read-only. While using Kowabunga's API, the project's directive is to enforce infrastructure and configuration as code, and such, prevents any means to do harm.
+
+**Koala** is AngularJS based and usually located next to **Kahuna**'s instance. It provides users with capability to connect, check for the various projects (they belong to) resources, optionnally start/reboot/stop them and/or see various piece of information and ... that's it ;-)