Skip to content

Commit 7342894

Browse files
Gerrit91Gerrit91
committed
Trying out Julia Documenter
0 parents  commit 7342894

12 files changed

+147
-0
lines changed

‎.github/workflows/deploy.yaml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
name: Documentation
3+
4+
on:
5+
push:
6+
branches:
7+
- master
8+
tags: '*'
9+
pull_request:
10+
11+
jobs:
12+
build:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v2
16+
- uses: julia-actions/setup-julia@latest
17+
with:
18+
version: 1.4.2
19+
- name: Build and deploy
20+
env:
21+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
22+
run: julia --project=docs/ docs/make.jl

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs/build

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2020 The metal-stack Authors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Docs
2+
3+
This repository contains the documentation of metal-stack.

‎docs/make.jl

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
import Pkg
2+
Pkg.add("Documenter")
3+
4+
push!(LOAD_PATH,"../src/")
5+
6+
using Documenter, Example
7+
8+
is_ci_build = get(ENV, "CI", nothing) == "true"
9+
10+
makedocs(
11+
sitename="metal-stack",
12+
format = Documenter.HTML(
13+
prettyurls = is_ci_build
14+
),
15+
authors = "metal-stack authors and contributors.",
16+
pages = [
17+
"index.md",
18+
"getting_started.md",
19+
"Architecture" => Any[
20+
"The Stack" => "architecture/the_stack.md",
21+
"Networking" => "architecture/networking.md",
22+
],
23+
"enhancement_proposals.md",
24+
"contributing.md",
25+
]
26+
)
27+
28+
if is_ci_build
29+
deploydocs(
30+
repo = "github.com/metal-stack/docs.git",
31+
)
32+
end

‎docs/src/architecture/networking.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Networking

‎docs/src/architecture/the_stack.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# The Stack

‎docs/src/contributing.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Contributing
2+
3+
## Code Style

‎docs/src/enhancement_proposals.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Enhancement Proposals

‎docs/src/getting_started.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Getting Started
2+
3+
```@contents
4+
```

‎docs/src/index.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Overview
2+
3+
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_.
4+
5+
```@index
6+
```
7+
8+
## Use-Cases
9+
10+
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.
11+
12+
Running this on-premise has several benefits:
13+
14+
- Data sovereignty
15+
- Better price/performance ratio
16+
- Easier connectivity to existing company networks
17+
18+
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?](#why-bare-metal)).
19+
20+
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.
21+
22+
## Why Do You Need a Cloud?
23+
24+
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.
25+
26+
## Why Bare Metal?
27+
28+
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.
29+
30+
1. Virtual environment drawbacks
31+
- [Spectre and Meltdown](https://meltdownattack.com/) can only be mitigated with a "cluster per tenant" approach
32+
- Missing isolation of multi-tenant change impacts
33+
- Licensing restrictions
34+
- "Noisy-neighbor" issues
35+
36+
2. Advantages of a metal-as-a-service platform
37+
- High and guaranteed performance (especially disk i/o)
38+
- Reduced stack depth (Host -> VM -> Application vs. Host -> Container) => reduced attack surface, cost/performance gain, no VM live-migrations
39+
- No need for a central storage system: Local storage governed by K8s to reduce storage costs
40+
- Bigger hardware configuration possible (hypervisors have restrictions, e.g. it is not possible to assign all CPUs to a single VM)
41+
- K8s ships with "enterprise" features (performance, availability, scalability) on commodity hardware
42+
43+
Beside these benefits there are also several disadvantages of metal-as-a-service platforms to consider:
44+
45+
- Hardware defects have direct impact (should be considered by design) and can not be mitigated by live-migration as in virtual environments
46+
- Not many "providers" to choose from
47+
- Bare metal provisioning is slower than provisioning a VM
48+
- Capacity planning is more difficult (no resource overbooking possible)
49+
- Higher "AfA"-costs
50+
51+
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.
52+
53+
## Roadmap
54+
55+
Coming soon.

‎src/Example.jl

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module Example
2+
3+
end

0 commit comments

Comments
 (0)