diff --git a/README.MD b/README.MD index 0edb093..7b238d2 100644 --- a/README.MD +++ b/README.MD @@ -2,13 +2,13 @@ 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). - + ## How does the DMC work? @@ -16,7 +16,7 @@ The DMC provides a Dockerfile template (from modular setup) that creates the Doc 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 new file mode 100644 index 0000000..89026a2 --- /dev/null +++ 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 new file mode 100644 index 0000000..db83f24 --- /dev/null +++ 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 new file mode 100644 index 0000000..096f398 --- /dev/null +++ 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 new file mode 100644 index 0000000..a9775bd --- /dev/null +++ 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 new file mode 100644 index 0000000..fb4e411 --- /dev/null +++ b/docs/usage/setup_and_configuration/tool_config.md @@ -0,0 +1,47 @@ +# 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 + ``` diff --git a/docs/usage/setup_and_configuration/tools.md b/docs/usage/setup_and_configuration/tools.md new file mode 100644 index 0000000..fec7260 --- /dev/null +++ b/docs/usage/setup_and_configuration/tools.md @@ -0,0 +1,85 @@ +# 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`