Update docs. [skip ci] (#418)

Author: Gerrit91

ARCHITECTURE.md

@@ -11,35 +11,12 @@
 * build an image based on the published docker images of OS vendors
 * add necessary packages and services in a Dockerfile for the OS to provide:
   * sudo functionality
-  * a SSH-Server
-  * the FRR-Suite for BGP (the servers act as a BGP router/speaker)
-  * yq for reading YAML-Files
-* provide a `install.sh` file within the image that will be invoked by the `metal-hammer`
-  * writes the `/etc/fstab` based on the UUIDs of the connected disks
-  * setup UEFI-Boot
-  * create an OS user with sudo rights
-  * set the SSH public keys that are allowed to log into the system
-  * sets the hostname
-  * sets the network configuration of the server (IP-Addresses at loopback device, ASN for BGP)
-  * sets the token used for phoning home to the metal-api
-
-The `install.sh` has to be implemented for every OS. Between `install.sh` and the `metal-hammer` component exists this contract:
-
-* the `metal-hammer` writes the file `/etc/metal/install.yaml` which contains data, that is not known during build time and can be customized by users of the `metal-api`
-
-  ```yaml
-  ---
-  hostname: some
-  ipaddress: 10.0.0.2/32
-  asn: 420000001
-  sshpublickeys: ""
-  ```
-
-* `install.sh` is expected to create the file `/etc/metal/boot-info.yaml` which contains data, that the `metal-hammer` will use for the `kexec-reboot` of the server.
-
-  ```yaml
-  ---
-  initrd:
-  cmdline:
-  kernel:
-  ```
+  * an SSH-Server
+  * the [FRR-Suite](https://frrouting.org/) for BGP (the servers act as a BGP router/speaker)
+  * [ignition](https://www.flatcar.org/docs/latest/provisioning/ignition/) for userdata execution
+  * `mdadm` for raid fsl configuration
+  * `lvm` for volume group fsl provisioning
+  * `grub` for bootloader installation
+  * `timesyncd` for NTP time synchronization
+* these services will be configured by the [os-installer](https://github.com/metal-stack/os-installer) invoked during machine provisioning by the metal-hammer
+* for out-of-tree custom images, build owners might want to provide a `/etc/metal/os-installer.yaml` file within the image that can provide special instructions for the os-installer

CONTRIBUTING.md

@@ -4,12 +4,12 @@ The metal-images tarballs are stored on <https://images.metal-stack.io/>. The ta
 The actual directory layout should look like:
 
 ```bash
-<imagesdir>/<os>/<major.minor>/<patch>/img.tar.lz4
-<imagesdir>/<os>/<major.minor>/<patch>/img.tar.lz4.md5
-<imagesdir>/<os>/<major.minor>/<patch>/packages.txt
+<imagesdir>/<os>/<major.minor>/img.tar.lz4
+<imagesdir>/<os>/<major.minor>/img.tar.lz4.md5
+<imagesdir>/<os>/<major.minor>/packages.txt
 ```
 
-Where `<imagesdir>` is `/` for the master branch and `/${CI_COMMIT_REF_SLUG}/` for branches and merge requests.
+Where `<imagesdir>` is `stable` for the master branch, `<patch>` for releases and `pull_requests/<pr-number>-<branch-name>` for pull requests.
 
 `<os>` is the name of the os in use, some images like `firewall` are derived from another os image (in this case the `ubuntu` image).
 

IMAGE_STORE.md

@@ -6,7 +6,7 @@
 [![Build](https://github.com/metal-stack/metal-images/actions/workflows/docker.yaml/badge.svg?branch=master)](https://github.com/metal-stack/metal-images/actions)
 [![Slack](https://img.shields.io/badge/slack-metal--stack-brightgreen.svg?logo=slack)](https://metal-stack.slack.com/)
 
-This project builds operating system images that can be used for bare metal server deployments with [metal-stack](https://metal-stack.io).
+This project builds officially supported operating system images that can be used for bare metal server deployments with [metal-stack](https://metal-stack.io).
 Every OS image is built from a `Dockerfile`, exported to a `lz4` compressed tarball, and uploaded to [images.metal-stack.io](https://images.metal-stack.io/).
 
 More information about the image store is available in [IMAGE_STORE.md](./IMAGE_STORE.md).
@@ -28,6 +28,10 @@ We also publish images that we need for special purposes but do not officially s
 
 1. Almalinux 9
 
+## Building Custom Images (Out-Of-Tree)
+
+It is fully possible to build custom operating system images and provision them through the metal-stack without directly contributing them to this repository. Please find information [in the official docs](https://metal-stack.io/docs/next/operating-systems#building-your-own-images) and in the [image builder contract](./ARCHITECTURE.md).
+
 ### GPU Support
 
 GPU support for workers are available by using the `debian-nvidia` images. Please check our official documentation at [metal-stack.io](https://metal-stack.io/docs/gpu-workers) how to get this running on Kubernetes.