Merge pull request #104 from telekom-mms/issue_82

mikaEz · web-flow · commit c8ddc592684d · 2023-08-10T13:04:45.000+02:00
Issue 82
diff --git a/README.MD b/README.MD
@@ -2,21 +2,21 @@
 
 The Docker Management Container (or DMC for short) contains a number of plugins and services that are designed to make it easy to create, test, deploy and manage infrastructures. For more information also take a look at our [Blog](https://blog.telekom-mms.com/tech-insights/manage-your-infrastructure-better-with-this-opensource-tool).
 
-<!-- <picture>
+<picture>
   <source
     srcset="https://user-images.githubusercontent.com/3198961/186105564-3901aded-21f1-4191-b323-e943f49ea5ed.png"
     media="(prefers-color-scheme: dark)"
     width="30%" height="30%">
   <img width="30%" height="30%" src="">
-</picture> -->
+</picture>
 
 ## How does the DMC work?
 
 The DMC provides a Dockerfile template (from modular setup) that creates the Dockerfile with the desired tools and versions through a file and script. This Dockerfile is then used for the actual build of the container. The Dockerfile itself does not need to be kept, but is created and discarded after the build of the Dockerfile.
 
 The DMC uses the wakemeops as base setup, for more information about wakemeops look at the [docs](https://docs.wakemeops.com/).
 
-### Try
+### Try it out
 
 For a quick overview and test of the DMC, we have created images based on the [minimal](examples/min_build.yaml) and [full](examples/full_build.yaml) examples that can be used directly.
 
@@ -34,202 +34,39 @@ docker run ghcr.io/telekom-mms/dmc:full
 
 Setup plugins, services, tools, versions and configuration over file with yaml syntax.
 
+Create a build.yaml:
+
 ``` bash
 touch build.yaml
 ```
 
-#### Image
+Then fill it with the settings you need:
+
+* [Image](docs/usage/setup_and_configuration/image.md)
+* [Base](docs/usage/setup_and_configuration/base.md)
+* [Tools](docs/usage/setup_and_configuration/tools.md)
+* [Tool Config](docs/usage/setup_and_configuration/tool_config.md)
+* [Post Build Config](docs/usage/setup_and_configuration/post_build_config.md)
+* [Tool Config](docs/usage/setup_and_configuration/tool_config.md)
+
+Take a look at the examples to see what's possible:
 
-The DMC uses the wakemeops image as base image.
-
-##### Image ARG
-
-* `distribution`
-  * Required: no
-  * Default: `ubuntu`
-  * Description: distribution that should be used, see also [wakemeops](https://hub.docker.com/u/wakemeops)
-  * Examples:
-    * ``` yaml
-      distribution: debian
-      ```
-
-* `version`
-  * Required: no
-  * Default: `latest`
-  * Description: specific version
-  * Examples:
-    * ``` yaml
-      version: buster
-      ```
-
-#### Base
-
-Basic Setup of the DMC.
-
-#### Tools
-
-Tools to be installed within the DMC.
-
-##### Tools ARG
-
-* `packages`
-  * Required: no
-  * Default:
-  * Description: list of packages to be installed
-  * Examples:
-    * ``` yaml
-      packages:
-        - ansible
-        - docker-ce
-        - helm
-        - kubectl
-      ```
-
-* `repositories`
-  * Required: no
-  * Default:
-  * Description: further repositories that should be used, currently the following are defined with defaults **_[hashicorp, docker, microsoft]_**
-  * Examples:
-    * ``` yaml
-      repositories:
-        docker: {}
-        microsoft: {}
-        hashicorp: {}
-      ```
-    * ``` yaml
-      repositories:
-        mongodb:
-          gpg: https://www.mongodb.org/static/pgp/server-6.0.asc
-          entry: https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse
-      ```
-
-* `binaries`
-  * Required: no
-  * Default:
-  * Description: binaries that should be installed, currently the following are supported **_[github, google]_**
-  * Examples:
-    * ``` yaml
-      github:
-        - remotemobprogramming/mob=linux_amd64=v3.2.0
-        - derailed/k9s=Linux_x86_64
-      google:
-        - google-cloud-cli
-      ```
-
-* `repositories_hashicorp_gpg`
-  * Required: no
-  * Default: `https://apt.releases.hashicorp.com/gpg`
-
-* `repositories_hashicorp_entry`
-  * Required: no
-  * Default: `'https://apt.releases.hashicorp.com $(lsb_release -cs) main'`
-
-* `repositories_docker_gpg`
-  * Required: no
-  * Default: `https://download.docker.com/linux/ubuntu/gpg`
-
-* `repositories_docker_entry`
-  * Required: no
-  * Default: `'https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable'`
-
-* `repositories_microsoft_gpg`
-  * Required: no
-  * Default: `https://packages.microsoft.com/keys/microsoft.asc`
-
-* `repositories_microsoft_entry`
-  * Required: no
-  * Default: `'https://packages.microsoft.com/repos/azure-cli/ $(lsb_release -cs) main'`
-
-* `binaries_github_uri`
-  * Required: no
-  * Default: `https://api.github.com/repos`
-
-* `binaries_google_uri`
-  * Required: no
-  * Default: `https://packages.cloud.google.com/apt/dists/cloud-sdk/main/binary-arm64/Packages`
-
-#### Tool Config
-
-Extension of installed tools.
-
-##### Tool Config ARG
-
-* `requirements`
-  * Required: no
-  * Default:
-  * Description: requirements that should be installed for the used tools, currently the following are supported **_[pip, ansible(roles, collections)]_**
-  * Examples:
-    * ``` yaml
-      requirements:
-        pip:
-          packages:
-            - awsume
-          requirements:
-            - https://raw.githubusercontent.com/ansible-collections/azure/v1.15.0/requirements-azure.txt
-        ansible:
-          roles:
-            - telekom_mms.grafana
-          collections:
-            - telekom_mms.acme=2.3.1
-            - telekom_mms.icinga_director=1.28.0
-          requirements:
-            - https://raw.githubusercontent.com/T-Systems-MMS/ansible-role-maxscale/master/requirements.yml
-      ```
-
-* `extensions`
-  * Required: no
-  * Default:
-  * Description: extensions that should be installed for the used tools, currently the following are supported **_[az, google, helm]_**
-  * Examples:
-    * ``` yaml
-      extensions:
-        az:
-          - front-door=1.0.15
-        google:
-          - gsutil
-          - gke-gcloud-auth-plugin
-          - kubectl
-        helm:
-          - https://github.com/databus23/helm-diff=3.5.0
-          - https://github.com/jkroepke/helm-secrets
-      ```
-
-#### Post Build Config
-
-System configuration and further setups to finish the DMC build.
-
-##### Post Build Config ARG
-
-* `profiles`
-  * Required: no
-  * Default:
-  * Description: configuration for profile settings
-  * Examples:
-    * ``` yaml
-      profiles:
-        .vimrc:
-          - filetype on
-        .bash_aliases:
-          - alias ll='ls -la'
-      ```
-
-* `post_build_commands`
-  * Required: no
-  * Default:
-  * Description: commands to run after the image build to finish the setup
-  * Examples:
-    * ``` yaml
-      post_build_commands:
-        - awsume-configure
-      ```
-
-### Build Dockerfile
-
-To create the Dockerfile from Template you have simply to run the following steps.
-
-1. create build.yaml with your needed settings
-2. run the script `render.sh`
-3. build Docker Image
+## Examples
+
+Examples for the `build.yaml` could be found under [examples](examples):
+
+* [minimal](examples/min_build.yaml)
+* [full](examples/full_build.yaml)
+
+### Build
+
+#### Dockerfile
+
+To create the Dockerfile from Template you have to run the following steps.
+
+1. Create `build.yaml` with your needed settings
+2. Run the script `render.sh`
+3. Build the Docker Image
 
 `render.sh`
 
@@ -239,7 +76,7 @@ The build script will create the `Dockerfile` from template.d with your settings
 sh render.sh .
 ```
 
-### Build Image
+#### Image
 
 ``` bash
 docker image build -t dmc:latest .
@@ -261,18 +98,7 @@ Provided build presets can be found under [pipeline](pipeline). The preset also
 }
 ```
 
-##### [gitlab-ci](pipeline/gitlab-ci.yml)
-
-##### Inputs
-
-| variable | description | default |
-| --- | --- | --- |
-| GITHUB_DMC_TAG | version of the dmc release | latest version |
-| DMC_NAME | name of the container | dmc |
-| DMC_IMAGE | full image name  | `$CI_REGISTRY_IMAGE/${DMC_NAME}` |
-
-The preset needs a `.docker-login`-extend. In it you have to define your docker registry information.
-To include the preset see [gitlab-ci](examples/pipeline/gitlab-ci.yml)
+* [gitlab-ci](docs/build/image/preset/gitlab-ci.md)
 
 ### Run Image
 
@@ -352,7 +178,8 @@ We provide a [renovate-preset](https://docs.renovatebot.com/key-concepts/presets
 If you use it renovate can update the versions in your `build.yaml`
 
 Include it like this:
-```
+
+``` json
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
@@ -364,7 +191,7 @@ Include it like this:
 
 Change your `build.yaml` like this to use it:
 
-```
+``` yaml
 packages:
   # renovate: datasource=repology depName=ubuntu_22_04/ansible versioning=loose
   - ansible=2.10.7+merged+base+2.10.8+dfsg-1
@@ -375,7 +202,6 @@ packages:
       - telekom_mms.acme=2.3.1
 ```
 
-
 ## Migration
 
 With Version 2.0.0 there's a breaking change in the configuration and usage of the DMC.
@@ -387,13 +213,6 @@ To support the migration we provide a script to migrate from the old .docker_bui
 sh migrate.sh .
 ```
 
-## Examples
-
-Examples for the `build.yaml` could be found under [examples](examples):
-
-* [minimal](examples/min_build.yaml)
-* [full](examples/full_build.yaml)
-
 ## Others
 
 Feedback, suggestions for improvement and expansion, and of course collaboration are expressly desired.
diff --git a/docs/build/image/preset/gitlab-ci.md b/docs/build/image/preset/gitlab-ci.md
@@ -0,0 +1,12 @@
+# [gitlab-ci](pipeline/gitlab-ci.yml)
+
+## Inputs
+
+| variable | description | default |
+| --- | --- | --- |
+| GITHUB_DMC_TAG | version of the dmc release | latest version |
+| DMC_NAME | name of the container | dmc |
+| DMC_IMAGE | full image name  | `$CI_REGISTRY_IMAGE/${DMC_NAME}` |
+
+The preset needs a `.docker-login`-extend. In it you have to define your docker registry information.
+To include the preset see [gitlab-ci](examples/pipeline/gitlab-ci.yml)
diff --git a/docs/usage/setup_and_configuration/base.md b/docs/usage/setup_and_configuration/base.md
@@ -0,0 +1,3 @@
+# Base
+
+Basic Setup of the DMC.
diff --git a/docs/usage/setup_and_configuration/image.md b/docs/usage/setup_and_configuration/image.md
@@ -0,0 +1,25 @@
+# Image
+
+The DMC uses the wakemeops image as base image.
+
+## Image ARG
+
+* `distribution`
+  * Required: no
+  * Default: `ubuntu`
+  * Description: distribution that should be used, see also [wakemeops](https://hub.docker.com/u/wakemeops)
+  * Examples:
+
+    * ``` yaml
+      distribution: debian
+      ```
+
+* `version`
+  * Required: no
+  * Default: `latest`
+  * Description: specific version
+  * Examples:
+
+    * ``` yaml
+      version: buster
+      ```
diff --git a/docs/usage/setup_and_configuration/post_build_config.md b/docs/usage/setup_and_configuration/post_build_config.md
@@ -0,0 +1,30 @@
+# Post Build Config
+
+System configuration and further setups to finish the DMC build.
+
+## Post Build Config ARG
+
+* `profiles`
+  * Required: no
+  * Default:
+  * Description: configuration for profile settings
+  * Examples:
+
+    * ``` yaml
+      profiles:
+        .vimrc:
+          - filetype on
+        .bash_aliases:
+          - alias ll='ls -la'
+      ```
+
+* `post_build_commands`
+  * Required: no
+  * Default:
+  * Description: commands to run after the image build to finish the setup
+  * Examples:
+
+    * ``` yaml
+      post_build_commands:
+        - awsume-configure
+      ```
diff --git a/docs/usage/setup_and_configuration/tool_config.md b/docs/usage/setup_and_configuration/tool_config.md
diff --git a/docs/usage/setup_and_configuration/tools.md b/docs/usage/setup_and_configuration/tools.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Base`
	`2`	`+`
	`3`	`+Basic Setup of the DMC.`