Try images

.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/src/external/mini-lab"]
+	path = docs/src/external/mini-lab
+	url = https://github.com/metal-stack/mini-lab.git

docs/make.jl

@@ -10,12 +10,15 @@ makedocs(
     ),
     authors = "metal-stack authors and contributors.",
     pages = [
-        "index.md",
-        "getting_started.md",
+        "Overview" => "index.md",
         "Architecture" => Any[
-            "The Stack" => "architecture/the_stack.md",
+            "Components" => "architecture/the_stack.md",
             "Networking" => "architecture/networking.md",
         ],
+        "Getting Started" => Any[
+            "Guides" => "guides.md",
+            "mini-lab" => "external/mini-lab/README.md",
+        ],
         "Enhancement Proposals" => "proposals/index.md",
         "contributing.md",
     ]

docs/src/guides.md

@@ -0,0 +1,7 @@
+# Getting Started
+
+Before starting to buy any expensive hardware, you should try out the metal-stack on your notebook and familiarize with all the major principles.
+
+For this, we made the [mini-lab](https://github.com/metal-stack/mini-lab).
+
+The mini-lab is a fully virtual setup and is supposed to be run on a single notebook. For this reason, the setup is slightly simplified in comparison to full-blown setups on real hardware. However, the lab should help to understand all major ideas and components of the metal-stack.

docs/src/index.md

@@ -1,4 +1,4 @@
-# Overview
+# metal-stack Documentation
 
 metal-stack is a software to provide physical servers on demand. It is a fully-automated provisioning framework for bare metal machines. To categorize this product, we commonly use the terminology _metal-as-a-service (MaaS)_ or _bare metal cloud_.
 
@@ -9,25 +9,25 @@ Depth = 5
 
 ## Use-Cases
 
-The major intent to initiate metal-stack was to build a framework that provides [Kubernetes](https://kubernetes.io/) (K8s) as a service (KaaS) in on-premise environments.
+The major intent to initiate metal-stack was to build a framework that provides an on-premise machine infrastructure for [Kubernetes](https://kubernetes.io/) (K8s) as a service (KaaS). But of course you can also use metal-stack only for multi-tenant-capable machine provisioning as well in your data center.
 
-Running this on-premise has several benefits:
+Running on-premise has several benefits:
 
-- Data sovereignty
-- Better price/performance ratio
+- Full data sovereignty
+- Typically better price/performance ratio than hyperscalers (especially the larger your environments are)
 - Easier connectivity to existing company networks
 
-From the very beginning, the machines provided by metal-stack are provided with the intention to run software managed by K8s. Reason for this is that K8s makes the bare metal approach shine and mitigates the problems that come with the approach (see [Why Bare Metal?](@ref)).
-
 metal-stack itself is typically deployed on Kubernetes as well. However, there are no specific dependencies of metal-stack running in a Kubernetes cluster. It exposes a traditional REST API that can be used for managing bare metal machines.
 
-## Why Do You Need a Cloud?
+## Kubernetes Integration
+
+In partnership with the open-source project [Gardener](https://gardener.cloud/), we provision Kubernetes clusters on metal-stack at scale. From the perspective of the Gardener, the metal-stack is just another cloud provider.
 
-We are clearly aiming at a fully-automated lifecycle for K8s clusters. The speed in which we want to provide K8s to a user makes this product very attractive. The time saving compared to providing machines and Kubernetes by hand are significant. We actually want to be able to compete with offers of public cloud providers, especially regarding speed and usability.
+We are clearly aiming at a fully-automated lifecycle for K8s clusters. The time saving compared to providing machines and Kubernetes by hand are significant. We actually want to be able to compete with offers of public cloud providers, especially regarding speed and usability.
 
 ## Why Bare Metal?
 
-The bare metal approach is especially attractive for the purpose of running K8s on top of it. Bare metal has several advantages over virtualized environments and overcomes several of the drawbacks of virtual machines.
+Bare metal has several advantages over virtualized environments and overcomes several of the drawbacks of virtual machines.
 
 1. Virtual environment drawbacks
    - [Spectre and Meltdown](https://meltdownattack.com/) can only be mitigated with a "cluster per tenant" approach
@@ -49,7 +49,7 @@ Beside these benefits there are also several disadvantages of metal-as-a-service
 - Capacity planning is more difficult (no resource overbooking possible)
 - Higher "AfA"-costs
 
-In the end, we have come to the conclusion that most of the drawbacks of bare metal machines can be mitigated when running K8s on the machines. K8s will take care of high-availability in case of hardware failures and also supervises machine resources. We are certain that the chosen approach can satisfy the needs of the future users to a higher degree than virtual machines could do.
+In the end, we have come to the conclusion that most of the drawbacks of bare metal machines can be mitigated best when running K8s on the machines. K8s will take care of high-availability in case of hardware failures and also supervises machine resources. We are certain that the chosen approach can satisfy the needs of the future users to a higher degree than virtual machines could do.
 
 ## Roadmap
 

docs/src/proposals/MEP1/Distributed.drawio

@@ -0,0 +1 @@
+<mxfile host="www.draw.io" modified="2020-01-13T13:05:59.591Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) snap Chromium/79.0.3945.79 Chrome/79.0.3945.79 Safari/537.36" etag="Pcrs69XaZ4sZO_cn817q" version="12.5.1" type="device"><diagram name="Page-1" id="c4acf3e9-155e-7222-9cf6-157b1a14988f">7V3bcts2EP0aP8pDgPfH2ImbziRTt+m0zVMHpmCJMUUoFG1L/fqC4kUkAEoULwDkRC8WIBIkF2d3z+6C8JV5u9r+kqD18jOZ4+gKGvPtlfn+CtKPY9M/Wc8u7/FtM+9YJOE87wKHji/hf7joNIre53CON40DU0KiNFw3OwMSxzhIG30oSchr87BHEjWvukYLzHV8CVDE9/4dztNl3uvZxqH/Iw4Xy/LKwCh+eUDB0yIhz3FxvStoPu4/+c8rVI5VHL9Zojl5rXWZH67M24SQNP+22t7iKJNtKbb8vLuWX6v7TnCcdjkhWVoPJP5zF3/w/trOvG+vv70+z4rJe0HRMy4fw4noeDePhA5L5YmC/Afn+3N2pzcfcfSC0zBAh67s4dJd1DwuO3+22U/3O3oAgOtt/Qxnkf29R0kapiGJy6vS288vnP9eSK4aHFIhrrOvz6voLkEr+vXmdRmm+Ms6v89XClLat0xXEW0B+nU/QziTgUFb1SRkjYCswqD4HqEHHN1UU3pLIpLQn2ISZ9fYpAl5qvABise7Q6swymD/F07mKEZFd4FxkA2LonAR00ZAJwkn1RO94CTF29aJBBU8qNphssJpsqOHFCfMbLeAVKFywC0x+VpDcNm3rKHX9opOVGjNohr9gBz6pQDPGUACkEPSBif0OWkfHGEayyfzMqlWj2QaI4kUcCK1eJGajkikYASRrrboX/K79Qh+vYe77+Ef8RMBM4+TaECCp4SgYClDoJz0BDJuF6jFCNQ0O8oTGiPI055D4NsPc8+Yo0cAwMy0OJHhOfUDRZMk6ZIsSIyiD4dexnTUZDdHm+W+H3SwHNTE3YXZne5HwfH8Xea1souucZz3NH+v24+OZqZ1xrKHPDpfCY5QGr40naFI9PtT6a2jXe2ANQnjdFMb+T7rOMDAAoxaGdBvOqkzT6Bf8nsQn256LadXd7whz0mAi9MYQFVi6a+zrsCfDsTd4ZhPhKwL0H3DaborEICeU9LE5x50JcyCCG02mZ9rYBEcQ00upCOPWdAGOt4Cp0eOc8ZG4SCDypOdmkE1ADdTpVGlPGFNtTkTUuXQI/yYNTfUvobx4tO+9d50xrKeVhPHlsDBAyiwns5Uzsg5Krt2Dy9fdpUMVMgOuCh4QLZredg2fedhBji5MQT7bObckZJzBNt498OQ7HKm3Wm4jW0zXsbmEWaL6LdlTqWegLdesv1MC+Hp72T8SSgMxxkoN2yhquUYuZubjDP4nImgI6JohtahRmbVYsxqlcBR5pLKkPMtYb4U6uSgh23xmSTQlw9aRz3apJmNT5FGsIeedrA3j1ExzfMC0G6BnZS0gFieloCivcGYDXQN2oBeURu4mLCNtRXqozZwMWEbSy80kJ0ol6ModLv5GbqNgjIuza9B5OYp9zbjs1hJoRub7qVs4tqofWBzwKkp7UUEcmx6TD2hrQrkb0gDJqq/8PUSnk8r1IAKjXoHdWx2XQMVgAKuwerEoXLIhAd8dw3neBum/2R4vva8ovl137SL1vttgfZ9Y1dr3OMkpM+X+eWiNkmfNR8LOGW7NljWPIy2b+3qLXa8TurVllE/Hca4HVWw4fv5SS/7hmZc2KyxYzNoailNCkYymJHY2HhqNb/kDAS3MgFUpFBdDgL+IDkI2DUHAfXKQcCLyUFwpWMABSuZJHu3i8lCcMVjHaR3Mg8hbY3mzxLyVCVkv3Miwp0MZ9omIg4UtuSsX2vkVsxfB/goVXXnAxGRxeMuImHBEzZDoCxybXKZDdRPV/rj3pSUsuBKz9Jxb15GmoKiTD/g84mKywn9gK9f5GfysbRy0zJF5FcuwD8Z+Zn22GZo2PzwkbmmkV/1opk+oYt5PGzWKPCzWFOrgfD4qPln/fnC4z4AtAv7LNEKddYB/Zilh6PpmNOOrGsKU1H9AVg+g6neBQhQJR0lMXhLVIGIN4QCVhuXwr9TKqTvIm2fzKdYGr6f1vqiZKXxdkPhT6h7f822Or/VZnXU7IEqa9sN/Hjsy9tTKxmfHvoJlrPB4koCi8nSf8Pyr53Dx5WLHZ75o3V4nacX6ewFT9ch0chWM6badQSW2pVpqUvd11DXpGbj7dELwS3qw754LjspafPhnobJeMC9YK88Jeko8Uo1j+Oe5XL0UzGna0RTsu7JKwSA8WU+u8fKxLs4OKauxrd1lk/zEElvFtpmv7k7OdCe0Hjm4WNLtc8Onwiu7POMzn2WW9DGTHM1U19Q6QCmVDMtWgS0D9mv12WmcfZwiiHS50+bWjOCtNglU1WgVRMWFMXpk70U4vBxOi8spERYM2hoJy1tV64McMqSVqFwhQ/ZvNfhsww6FuNN/RahlHekcxKUyxSrz4G6auOFqtGtejEtKZS31o0tfPVlhTPTsBlEWdkrTwda6HQyX+fuZMc/QQHa9hvltrLzGmc0t7IbbQM6vjKSJd6Uswb2VU31rMG9JELP5l3U83lXSYJSiRmdPPdosablaKDb1VTyywfdPgH0uZaSf5rjhpJbBi3HTvLhaNNOqglF2bWxUs2keGNnTk7Vvs7ti9+02dfZZsEld19noUQhJ1EVlvSsFZ+MBTwZ0gqfu2AmdVIqPM4aaGQHTc7RV1tHXu45ENoMvxRuZjJZRNo+c5KWew4SHrcBgHLRqdkEY0TtFhSRhMf5KrUb8gost1bYY3WK1NnJNxdUNT181nuaEvi4hhf4ULn1UJvTOrcG3r++PYoy+BehDNLy4sO0wWTLtOq1QZMdPUdELOjKnZUittxtUpkVgr2sEKjZoNKSyTBDnSd1aEDUK43DRheGb9cBcvL4MhvZdrx7/PjBWZ+jIq9ZBmo4E7KlkqHgNUH+2tGpF1rVcw4otfwoliX//6mUqH/FJdzuZKI3cxlT/btycqX5EMGmlhdKNaESrtl5lod67l5GnjPC7P+QZIuaFjx+xkRmmw8ML8Jss2km9Ua73GjuMhIgvWz7iMor2q7uCEDHXzbB/vMJg90zcrzFWWIB6OHjVUwpHDqlw/SUf39Kx1QYYMtr6oN/qDoI7ctPFJm4zpnhiUycrdrECZLOGubZ9FO0Mu/3hnxD18SwWtdwZNe+KdatjVws8UTAtaQCF7414JYb2p0mNbZK5Ir23dMXuRy38UT/JmAk5NJmQrLtlw6uLUHr5Wcyx9kR/wM=</diagram></mxfile>