From b4e8aeed0c2768d4a23460bfe98cc0862f8edc63 Mon Sep 17 00:00:00 2001 From: github-actions Date: Thu, 25 Jul 2024 14:59:42 +0000 Subject: [PATCH 01/29] [skip ci] Update commands documentation --- docs/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 54a8fa9..4d5aab8 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -17,8 +17,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. BuiltBy: goreleaser -Commit: 13379d5 -Date: 2024-07-25T14:53:34Z +Commit: 9d85b2c +Date: 2024-07-25T14:59:40Z Target: linux_amd64 **Usage**: From 788001cd33532afb9ec10ab1b7624bbcc5d5066f Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Tue, 20 Aug 2024 12:20:41 +0200 Subject: [PATCH 02/29] #27 - Add initial MKDocs directory structure and configuration files. --- .github/workflows/docs-publish.yaml | 44 ++++++++++++ README.md | 7 ++ docs/.pages | 5 ++ docs/CNAME | 1 + docs/commands.md | 2 +- docs/index.md | 8 +++ docs/quickstart.md | 7 +- docs/release-notes.md | 4 +- docs/requirements.txt | 8 +++ mkdocs.yml | 101 ++++++++++++++++++++++++++++ 10 files changed, 180 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/docs-publish.yaml create mode 100644 docs/.pages create mode 100644 docs/CNAME create mode 100644 docs/index.md create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml new file mode 100644 index 0000000..0fb9a9f --- /dev/null +++ b/.github/workflows/docs-publish.yaml @@ -0,0 +1,44 @@ +name: Build and publish documentation to GitHub Pages + +on: + push: + branches: + - feature/* + - master +# tags: +# - 'v[0-9]+.[0-9]+.[0-9]+' + +jobs: + build: + runs-on: ubuntu-22.04 +# container: +# image: python:3.9 + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Install Python dependencies + run: pip install -r docs/requirements.txt + + - name: Build, validate documentation using MkDocs + run: | +# git config --global --add safe.directory /__w/rmk/rmk + mkdocs build --verbose --clean --strict + rm -r site/ + + - name: Configure Git +# if: startsWith(github.ref, 'refs/tags/') + id: git-configuration + run: | + echo "Configure Git user.name and user.email." + git config user.name github-actions + git config user.email github-actions@github.com + + echo tag=${GITHUB_REF#refs/tags/} >> "${GITHUB_OUTPUT}" + + - name: Build, publish, version documentation using Mike +# if: startsWith(github.ref, 'refs/tags/') + run: | +# mike deploy --update-aliases --push --rebase ${{ steps.git-configuration.outputs.tag }} latest diff --git a/README.md b/README.md index d58d6c9..177b7e0 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ Command line tool for reduced management and provisioning of Kubernetes clusters * [Supported Kubernetes providers](#supported-kubernetes-providers) * [Roadmap](#roadmap) * [License](#license) + * [Code of Conduct](#code-of-conduct) ## Overview @@ -194,3 +195,9 @@ Check the [issues](https://github.com/edenlabllc/rmk/issues) for more informatio ## License RMK is open source software (OSS) licensed under the [Apache 2.0 License](LICENSE). + +## Code of Conduct + +This project adheres to the Contributor Covenant [Сode of Сonduct](https://github.com/edenlabllc/rmk/blob/develop/docs/CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. +Please refer to our [Contributing Guidelines](https://github.com/edenlabllc/rmk/blob/develop/docs/CONTRIBUTING.md) for further information. diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 0000000..d04de88 --- /dev/null +++ b/docs/.pages @@ -0,0 +1,5 @@ +nav: + - index.md + - quickstart.md + - configuration +collapse: false diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..3c1c2db --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +rmk.io diff --git a/docs/commands.md b/docs/commands.md index 068b1cb..e2b2ec6 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -74,7 +74,7 @@ K3D cluster management Create K3D cluster -**--k3d-volume-host-path, --kv**="": host local directory path for mount into K3D cluster (default: "${PWD}/rmk.tools.infra") +**--k3d-volume-host-path, --kv**="": host local directory path for mount into K3D cluster (default: "${PWD}/rmk") #### delete, d diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c4b62f7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +# RMK Documentation + +Hi! You are welcomed to RMK onboard! +This document is useful for beginners and for advanced DevOps specialists. + +Let’s deep dive into fabolous DevOps world with RMK. + +Yours, RMK Team. diff --git a/docs/quickstart.md b/docs/quickstart.md index 6f9b031..192a990 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -6,8 +6,9 @@ create a local cluster based on `K3D`, deploy your first application ([Nginx](ht > Prerequisite: > - An active AWS user with access keys and the `AdministratorAccess` permissions. > - A prepared [project repository](configuration/project-management/preparation-of-project-repository.md#preparation-of-the-project-repository) -> - Installed [RMK](../README.md#installation) -> - The fulfilled [requirements](../README.md#requirements) for proper RMK operation. + +[//]: # (> - Installed [RMK](../README.md#installation)) +[//]: # (> - The fulfilled [requirements](../README.md#requirements) for proper RMK operation.) 0. Create a [project.yaml](configuration/project-management/preparation-of-project-repository.md#projectyaml) file in the root of the project repository with the following content: @@ -103,7 +104,7 @@ inventory: 3. Create a local K3D cluster: - > Before running this step, ensure that Docker is installed in the system according to the [requirements](../README.md#requirements). +[//]: # ( > Before running this step, ensure that Docker is installed in the system according to the [requirements](../README.md#requirements).) ```shell rmk cluster k3d create diff --git a/docs/release-notes.md b/docs/release-notes.md index 8a638b7..7d9a36d 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,3 +1 @@ -- #18 - Fixed links to the OSS repository in project generation. -- #18 - Split the issue template into the bug and feature templates. -- #18 - Updated the Roadmap section of README.md. +- #27 Configured GitHub Pages documentation generation using MkDocs diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c2a4eaa --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,8 @@ +mkdocs==1.5.3 +mkdocs-material==9.4.6 +pymdown-extensions==10.3.1 +mkdocs-git-revision-date-localized-plugin==1.2.1 +mkdocs-awesome-pages-plugin==2.9.2 +mdx_truly_sane_lists==1.3 # https://github.com/radude/mdx_truly_sane_lists +mkdocs-include-markdown-plugin==6.0.3 # https://github.com/mondeja/mkdocs-include-markdown-plugin +mike==1.1.2 # versioned docs: https://github.com/jimporter/mike diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d33a714 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,101 @@ +# Project information +site_name: RMK +site_description: RMK CLI - Reduced Management for Kubernetes by Edenlab LLC. +# todo change to static domain +site_url: https://edenlabllc.github.io/rmk + +copyright: © EDENLAB. ALL RIGHTS RESERVED, 2021 - 2024 + +# Extra Files +extra_javascript: + - static/js/asciinema-player.js + +extra_css: + - static/css/asciinema-player.css + - static/css/extra.css + +# Repo Information +repo_name: edenlabllc/rmk +repo_url: https://github.com/edenlabllc/rmk + +# Edit Link on Site +#edit_uri: edit/main/docs/ + +# Theme +theme: + name: material + language: en + features: + - navigation.top # show back to top button + - search.suggest # search suggestions: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions + - search.highlight # highlight search term on target page: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions + - navigation.expand + - navigation.tabs + - navigation.tabs.sticky # stick navigation tabs below header while scrolling + - navigation.tracking + - navigation.path +# todo review list of features +# - navigation.instant +# - navigation.sections +# - navigation.indexes + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: "black" + accent: "grey" + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: light blue + toggle: + icon: material/toggle-switch + name: Switch to light mode + # todo change icons and logo + logo: https://edenlab.io/wp-content/themes/edenlab/assets/images/fhir_icon.svg + favicon: https://edenlab.io/favicon.ico + icon: + repo: fontawesome/brands/github + +# Navigation +# nav: omitted, because we're using the awesome-pages plugin (https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/) + +# Extensions +markdown_extensions: + - attr_list + - toc: + permalink: true + - admonition # https://squidfunk.github.io/mkdocs-material/extensions/admonition/ + - pymdownx.highlight: # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight + use_pygments: true + - pymdownx.inlinehilite # https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#inlinehilite + - pymdownx.superfences # https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#superfences + - pymdownx.tabbed # https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tabbed + - pymdownx.details # https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#details + - pymdownx.emoji: # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#configuration + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - smarty # https://python-markdown.github.io/extensions/smarty/ + - mdx_truly_sane_lists # https://github.com/radude/mdx_truly_sane_lists -> proper indentation of md list items + +# Plugins +plugins: + - search + - git-revision-date-localized: # https://squidfunk.github.io/mkdocs-material/plugins/revision-date/ + type: date + - awesome-pages # https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/ + - include-markdown # https://github.com/mondeja/mkdocs-include-markdown-plugin + - mike: # Versioned Docs: https://github.com/jimporter/mike + version_selector: true # set to false to leave out the version selector + css_dir: static/css # the directory to put the version selector's CSS + javascript_dir: static/js # the directory to put the version selector's JS + canonical_version: null # the version for ; `null` uses the version specified via `mike deploy` + +# Extra mkdocs-material settings +extra: + version: + provider: mike + +# Other Settings +strict: true # halt processing when a warning is raised From 8d0ddd6104f9a90d4f66034282de4cca80408cdb Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Tue, 20 Aug 2024 13:47:09 +0200 Subject: [PATCH 03/29] #27 - Adapted docs/README.md to MKDocs, fixed relative links in the file. --- docs/.pages | 6 +- docs/CODE_OF_CONDUCT.md | 2 +- docs/README.md | 203 ++++++++++++++++++++++++++++++++++++++++ docs/SECURITY.md | 2 +- docs/index.md | 8 -- mkdocs.yml | 17 +--- 6 files changed, 213 insertions(+), 25 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/index.md diff --git a/docs/.pages b/docs/.pages index d04de88..cd15a0d 100644 --- a/docs/.pages +++ b/docs/.pages @@ -1,5 +1,9 @@ nav: - - index.md + - README.md - quickstart.md - configuration + - commands.md + - development-and-release-flow.md + - release-notes.md + - release-notes.md collapse: false diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md index 6a2a0d5..2ed55ad 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -60,7 +60,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers responsible for enforcement and specified in -[CODEOWNERS](https://github.com/edenlabllc/rmk/blob/master/docs/CODEOWNERS). +[CODEOWNERS](https://github.com/edenlabllc/rmk/blob/master/CODEOWNERS). All complaints will be reviewed and investigated promptly and fairly. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7a503b6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,203 @@ +# RMK CLI - Reduced Management for Kubernetes + +[![Release](https://img.shields.io/github/v/release/edenlabllc/rmk.svg?style=for-the-badge)](https://github.com/edenlabllc/rmk/releases/latest) +[![Software License](https://img.shields.io/github/license/edenlabllc/rmk.svg?style=for-the-badge)](LICENSE) +[![Powered By: Edenlab](https://img.shields.io/badge/powered%20by-edenlab-8A2BE2.svg?style=for-the-badge)](https://edenlab.io) + +Command line tool for reduced management and provisioning of Kubernetes clusters and environments, Helm secrets and releases. + +* [RMK CLI - Reduced Management for Kubernetes](#rmk-cli---reduced-management-for-kubernetes) + * [Overview](#overview) + * [Advantages](#advantages) + * [Edenlab LLC use cases](#edenlab-llc-use-cases) + * [Related OSS repositories](#related-oss-repositories) + * [Requirements](#requirements) + * [Quickstart](quickstart.md) + * [Installation](#installation) + * [Update](#update) + * [General update process](#general-update-process) + * [Update to specific version](#update-to-specific-version) + * Configuration + * [RMK configuration management](configuration/rmk-configuration-management.md) + * Project management + * [Requirement for project repository](configuration/project-management/requirement-for-project-repository.md) + * [Preparation of project repository](configuration/project-management/preparation-of-project-repository.md) + * [Dependencies management and Project inheritance](configuration/project-management/dependencies-management-and-project-inheritance.md) + * [Cluster management](configuration/cluster-management/cluster-management.md) + * [Exported environment variables](configuration/cluster-management/exported-environment-variables.md) + * [Release management](configuration/release-management/release-management.md) + * [Secrets management](configuration/secrets-management/secrets-management.md) + * [Commands](commands.md) + * [Development and release flow](development-and-release-flow.md) + * [Features](#features) + * [Supported Kubernetes providers](#supported-kubernetes-providers) + * [Roadmap](#roadmap) + * [License](#license) + * [Code of Conduct](#code-of-conduct) + +## Overview + +This tool has been designed and developed initially by [Edenlab LLC](https://edenlab.io/) as the main CLI +for managing [Kodjin FHIR Server](https://kodjin.com) on Kubernetes clusters in different environments. + +It is a wrapper around many popular CI/CD and DevOps CLI tools, including: + +- [Helmfile](https://helmfile.readthedocs.io/en/latest/) +- [Helm](https://helm.sh/) +- [kubectl](https://kubernetes.io/reference/kubectl/) +- [SOPS](https://getsops.io/) +- [Terraform](https://www.terraform.io/) +- [K3D](https://k3d.io/) + +The main goal of the tool is to simplify ("reduce") management of Kubernetes clusters and releases. + +**RMK** is an abbreviation which stands for "**R**educed **M**anagement for **K**ubernetes". + +### Advantages + +RMK simplifies the start of any level of complexity of a project using Kubernetes due to the following advantages: +- **Respects the [GitOPS](https://www.gitops.tech/) approach:** Each Git branch is used as a unique identifier for determining the environment, cluster name, + set of configurations and other attributes required for setting up the wrapped tools for project management in the Kubernetes environment. +- **Respects the [GitLabFlow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) workflow**: Supports the standard _develop_, _staging_, _production_ and different ephemeral (e.g, _feature_, _release_) environments. +- **Provides a transparent project structure with a basic set of configurations**: Allows you to correctly reuse configurations between projects + and inherit project configurations from other repositories, e.g., establish parent-child ("upstream-downstream") project relationships. +- **Allows a diverse team to work in the [DevOPS](https://www.atlassian.com/devops) methodology without blocking each other**: Each team or multiple teams + can develop and release their projects separately, later on the result of their work can be combined in a single project. +- **Supports versioning of projects in a CI/CD pipeline**: Each project can be versioned and referenced by static or dynamic tags (e.g., [SemVer2](https://semver.org/)), + which guarantees stable, well-tested and predictable releases. +- **Integrates with any CI/CD tool easily**: The tool is a self-sufficient binary that strictly follows the [12 factor app](https://12factor.net/) methodology. +- **Calls the CLI tools directly instead of using their libraries/SDKs**: RMK executes the tools directly in a way that a typical person would do it, + passing correct sets of CLI arguments and flags to the commands based on a project configuration structure. + This decouples the updating of RMK itself from the wrapped CLI tools, allowing developers to utilize recent functionality and fixes. + +### Edenlab LLC use cases + +At [Edenlab LLC](https://edenlab.io/), RMK is used for deploying the [Kodjin FHIR Server](https://kodjin.com). + +A classic Kodjin installation uses 3-level inheritance: +- **Dependencies (upstream#1)**: Core components like DBs, search engines, caches, load balancers/proxies, operators + etc. +- **Kodjin (downstream#1)**: Kodjin FHIR API ([REST](https://en.wikipedia.org/wiki/REST)) +- **Target installation (downstream#2)**: Products based on Kodjin, such as UI components, user portals and middleware services. + +The additional components used by Kodjin are: +- **\*.provisioner.infra:** Repositories for Kubernetes cluster provisioning. +- **helmfile.hooks.infra:** Shell scrips used as [Helmfile hooks](https://helmfile.readthedocs.io/en/latest/#hooks) in + deps/Kodjin/any other tenant. +- **core.charts.infra:** Helm charts used by the Kodjin services. + +The examples of Kubernetes providers, to which Kodjin has been installed, are: +- [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) +- [Open Telekom Cloud - Cloud Container Engine (CCE)](https://www.open-telekom-cloud.com/en/products-services/core-services/cloud-container-engine) +- [Rancher Kubernetes Platform](https://www.rancher.com/) +- [Kubermatic Kubernetes Platform (KKP)](https://www.kubermatic.com/) +- on-premise installations deployed using [Ansible Kubespray](https://github.com/kubernetes-sigs/kubespray) +- single-machine [K3D](https://k3d.io/) clusters + +#### Related OSS repositories + +- [AWS cluster provider for RMK](https://github.com/edenlabllc/aws.provisioner.infra) +- [Azure cluster provider for RMK](https://github.com/edenlabllc/azure.provisioner.infra) +- [K3D cluster provider for RMK](https://github.com/edenlabllc/k3d.provisioner.infra) +- [Helmfile hooks](https://github.com/edenlabllc/helmfile.hooks.infra) + +## Requirements + +Currently, RMK only supports Unix-like operating systems (OS): +* **OS:** + * **MacOS**: amd64, arm64 (M1, M2 require [Rosetta](https://support.apple.com/en-us/HT211861)) + * **Linux**: amd64 +* **Software:** + * **Python** >= 3.9 + * **[AWS CLI](https://aws.amazon.com/cli/)** + * _For managing local clusters using K3D:_ Version _v5.x.x_ requires [Docker](https://www.docker.com/) => v20.10.5 ([runc](https://github.com/opencontainers/runc) >= v1.0.0-rc93) to work + properly. + +> If this is your first project repository managed by RMK, ensure that the above tools are specified in the [project.yaml](configuration/project-management/preparation-of-project-repository.md#projectyaml) file. + +## Installation + +To install RMK, run the self-installer script using the following command: + +```shell +curl -sL "https://edenlabllc-rmk.s3.eu-north-1.amazonaws.com/rmk/s3-installer" | bash +``` + +Alternatively, you can go directly to https://github.com/edenlabllc/rmk/releases and download the binary. + +As another option, the binary can be [built from source](development-and-release-flow.md#building-from-source). + +## Update + +### General update process + +To update RMK to the latest version, run the following command: + +```shell +rmk update +``` + +### Update to specific version + +You can update to a specific RMK version to maintain backward compatibility or when updating to the latest version is not possible. +> This may be necessary due to specific version requirements or when a bug has been detected. + +To update to a specific version, use the following command: + +```shell +rmk update --version vX.X.X +``` + +## Features + +- **[Reduced and simplified management of Kubernetes projects:](#overview)** Deploy to Kubernetes using Helmfile/Helm, use popular DevOps tools together in a single CI/CD pipeline. +- **[Time-proven project structure:](configuration/project-management/preparation-of-project-repository.md)** Define the project structure using the [GitLabFlow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) methodology. +- **[Hierarchies between different projects:](configuration/project-management/dependencies-management-and-project-inheritance.md)** Define upstream-downstream relationships between sibling projects to reuse releases and services across different installations. +- **[Batch secret management:](configuration/secrets-management/secrets-management.md#generating-all-secrets-from-scratch-in-a-batch-manner-using-the-rmk-secrets-manager)** Template, generate, and encode project secrets for all environments in a batch manner. +- **[Clone environments with one click:](configuration/rmk-configuration-management.md#initialization-of-rmk-configuration-for-feature-or-release-clusters)** Use the special `--config-from-environment` (`--cfe`) flag to create an environment based on an existing one. +- **[Automatic detection of Multi-Factor Authentication](configuration/rmk-configuration-management.md#support-for-multi-factor-authentication-mfa) ([MFA](https://en.wikipedia.org/wiki/Multi-factor_authentication)):** Automatically detect and use an MFA device if one is defined by an [IAM](https://aws.amazon.com/iam/) user (must be supported by the cluster provider, e.g., [AWS](https://aws.amazon.com/)). +- **[Push-based release and downstream project updates:](configuration/release-management/release-management.md#release-update-and-integration-into-the-cd-pipeline)** Easily integrate with CI/CD solutions via webhooks or workflow dispatch events + to update release and service version declarations, automatically commit the changes to Git. +- **[Project structure generation:](configuration/project-management/preparation-of-project-repository.md#automatic-generation-of-the-project-structure-from-scratch)** Generate a complete Kubernetes-based project structure from scratch using RMK, following the best practices. +- **[Documentation generation:](commands.md#doc)** Generate the full command documentation in the Markdown format with one click. +- **[Support for different types of code sources:](configuration/rmk-configuration-management.md#use-upstream-artifact-for-the-downstream-projects-repository)** Use Git when the _artifact-mode_ is _none_, S3 when the _artifact-mode_ is _online_, + switch to fully offline installations when the _artifact-mode_ is _offline_. + +## Supported Kubernetes providers + +By design, RMK can work with any Kubernetes provider. + +Among the providers are: + +- [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) +- [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) +- [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/products/kubernetes-service/) +- [Red Hat OpenShift](https://redhat.com/en/technologies/cloud-computing/openshift) +- [VMware Tanzu Kubernetes Grid](https://tanzu.vmware.com/kubernetes-grid) +- [Rancher Kubernetes Platform](https://www.rancher.com/) +- [Open Telekom Cloud - Cloud Container Engine (CCE)](https://www.open-telekom-cloud.com/en/products-services/core-services/cloud-container-engine) +- [Kubermatic Kubernetes Platform (KKP)](https://www.kubermatic.com/) +- on-premise installations deployed using [Ansible Kubespray](https://github.com/kubernetes-sigs/kubespray) +- single-machine [K3D](https://k3d.io/) clusters + +## Roadmap + +- **Guidelines for contributors:** Create comprehensive guidelines for contributors, including instructions for creating pull requests (PRs). +- **Integration with Helmfile [vals](https://github.com/helmfile/vals)**: Integrate RMK with the **vals** tool for enhanced values and secret management. +- **Major update of the AWS [EKS](https://aws.amazon.com/eks/) cluster provider:** Update the AWS EKS cluster provider to the latest versions to utilize all the supported features of the [Terraform](https://www.terraform.io/) CLI and modules. +- **Implementation of additional RMK cluster providers:** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. +- **Offline artifact mode:** Implement the **offline** artifact mode to install artifacts in fully isolated offline environments. +- **Web documentation generator:** Add an HTML documentation generator based on the **.md** files. +- **Automatic testing of RMK during the CI/CD pipeline:** Ensure that changes to the RMK codebase do not introduce errors or regressions during the CI/CD. + +Check the [issues](https://github.com/edenlabllc/rmk/issues) for more information. + +## License + +RMK is open source software (OSS) licensed under the [Apache 2.0 License](../LICENSE). + +## Code of Conduct + +This project adheres to the Contributor Covenant [Сode of Сonduct](CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. +Please refer to our [Contributing Guidelines](CONTRIBUTING.md) for further information. diff --git a/docs/SECURITY.md b/docs/SECURITY.md index e8e1ed9..97b53a5 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -10,7 +10,7 @@ The security team and community take all security vulnerabilities seriously. Thank you for improving the security of our open source software. We appreciate your efforts and responsible disclosure and will make every effort to acknowledge your contributions. -Report security vulnerabilities by notifying the team specified in [CODEOWNERS](https://github.com/edenlabllc/rmk/blob/master/docs/CODEOWNERS). +Report security vulnerabilities by notifying the team specified in [CODEOWNERS](https://github.com/edenlabllc/rmk/blob/master/CODEOWNERS). The lead maintainers will acknowledge your email and send a more detailed response indicating the next steps in handling your report. After the initial reply to your report, the security team will endeavor to keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index c4b62f7..0000000 --- a/docs/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# RMK Documentation - -Hi! You are welcomed to RMK onboard! -This document is useful for beginners and for advanced DevOps specialists. - -Let’s deep dive into fabolous DevOps world with RMK. - -Yours, RMK Team. diff --git a/mkdocs.yml b/mkdocs.yml index d33a714..76ae23d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,21 +6,10 @@ site_url: https://edenlabllc.github.io/rmk copyright: © EDENLAB. ALL RIGHTS RESERVED, 2021 - 2024 -# Extra Files -extra_javascript: - - static/js/asciinema-player.js - -extra_css: - - static/css/asciinema-player.css - - static/css/extra.css - # Repo Information repo_name: edenlabllc/rmk repo_url: https://github.com/edenlabllc/rmk -# Edit Link on Site -#edit_uri: edit/main/docs/ - # Theme theme: name: material @@ -53,7 +42,7 @@ theme: icon: material/toggle-switch name: Switch to light mode # todo change icons and logo - logo: https://edenlab.io/wp-content/themes/edenlab/assets/images/fhir_icon.svg +# logo: https://edenlab.io/wp-content/themes/edenlab/assets/images/fhir_icon.svg favicon: https://edenlab.io/favicon.ico icon: repo: fontawesome/brands/github @@ -81,16 +70,16 @@ markdown_extensions: # Plugins plugins: - - search + - awesome-pages # https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/ - git-revision-date-localized: # https://squidfunk.github.io/mkdocs-material/plugins/revision-date/ type: date - - awesome-pages # https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/ - include-markdown # https://github.com/mondeja/mkdocs-include-markdown-plugin - mike: # Versioned Docs: https://github.com/jimporter/mike version_selector: true # set to false to leave out the version selector css_dir: static/css # the directory to put the version selector's CSS javascript_dir: static/js # the directory to put the version selector's JS canonical_version: null # the version for ; `null` uses the version specified via `mike deploy` + - search # Extra mkdocs-material settings extra: From 339dd607dd1f32f2d9902a8fe49e53cfe653d7e7 Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Tue, 20 Aug 2024 15:21:37 +0200 Subject: [PATCH 04/29] #27 - Fix relative links in MD files. Uncommented quickstart links. Correct navigation titles. --- README.md | 16 ++++++++-------- docs/.pages | 6 ++---- docs/README.md | 16 ++++++++-------- .../cluster-management/cluster-management.md | 4 ++-- ...management.md => configuration-management.md} | 2 +- .../preparation-of-project-repository.md | 2 +- docs/quickstart.md | 8 ++++---- mkdocs.yml | 1 + 8 files changed, 27 insertions(+), 28 deletions(-) rename docs/configuration/{rmk-configuration-management.md => configuration-management.md} (99%) diff --git a/README.md b/README.md index 177b7e0..fa6d856 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # RMK CLI - Reduced Management for Kubernetes [![Release](https://img.shields.io/github/v/release/edenlabllc/rmk.svg?style=for-the-badge)](https://github.com/edenlabllc/rmk/releases/latest) -[![Software License](https://img.shields.io/github/license/edenlabllc/rmk.svg?style=for-the-badge)](LICENSE) +[![Software License](https://img.shields.io/github/license/edenlabllc/rmk.svg?style=for-the-badge)](https://github.com/edenlabllc/rmk/blob/master/LICENSE) [![Powered By: Edenlab](https://img.shields.io/badge/powered%20by-edenlab-8A2BE2.svg?style=for-the-badge)](https://edenlab.io) Command line tool for reduced management and provisioning of Kubernetes clusters and environments, Helm secrets and releases. @@ -18,7 +18,7 @@ Command line tool for reduced management and provisioning of Kubernetes clusters * [General update process](#general-update-process) * [Update to specific version](#update-to-specific-version) * Configuration - * [RMK configuration management](docs/configuration/rmk-configuration-management.md) + * [Configuration management](docs/configuration/configuration-management.md) * Project management * [Requirement for project repository](docs/configuration/project-management/requirement-for-project-repository.md) * [Preparation of project repository](docs/configuration/project-management/preparation-of-project-repository.md) @@ -154,13 +154,13 @@ rmk update --version vX.X.X - **[Time-proven project structure:](docs/configuration/project-management/preparation-of-project-repository.md)** Define the project structure using the [GitLabFlow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) methodology. - **[Hierarchies between different projects:](docs/configuration/project-management/dependencies-management-and-project-inheritance.md)** Define upstream-downstream relationships between sibling projects to reuse releases and services across different installations. - **[Batch secret management:](docs/configuration/secrets-management/secrets-management.md#generating-all-secrets-from-scratch-in-a-batch-manner-using-the-rmk-secrets-manager)** Template, generate, and encode project secrets for all environments in a batch manner. -- **[Clone environments with one click:](docs/configuration/rmk-configuration-management.md#initialization-of-rmk-configuration-for-feature-or-release-clusters)** Use the special `--config-from-environment` (`--cfe`) flag to create an environment based on an existing one. -- **[Automatic detection of Multi-Factor Authentication](docs/configuration/rmk-configuration-management.md#support-for-multi-factor-authentication-mfa) ([MFA](https://en.wikipedia.org/wiki/Multi-factor_authentication)):** Automatically detect and use an MFA device if one is defined by an [IAM](https://aws.amazon.com/iam/) user (must be supported by the cluster provider, e.g., [AWS](https://aws.amazon.com/)). +- **[Clone environments with one click:](docs/configuration/configuration-management.md#initialization-of-rmk-configuration-for-feature-or-release-clusters)** Use the special `--config-from-environment` (`--cfe`) flag to create an environment based on an existing one. +- **[Automatic detection of Multi-Factor Authentication](docs/configuration/configuration-management.md#support-for-multi-factor-authentication-mfa) ([MFA](https://en.wikipedia.org/wiki/Multi-factor_authentication)):** Automatically detect and use an MFA device if one is defined by an [IAM](https://aws.amazon.com/iam/) user (must be supported by the cluster provider, e.g., [AWS](https://aws.amazon.com/)). - **[Push-based release and downstream project updates:](docs/configuration/release-management/release-management.md#release-update-and-integration-into-the-cd-pipeline)** Easily integrate with CI/CD solutions via webhooks or workflow dispatch events to update release and service version declarations, automatically commit the changes to Git. - **[Project structure generation:](docs/configuration/project-management/preparation-of-project-repository.md#automatic-generation-of-the-project-structure-from-scratch)** Generate a complete Kubernetes-based project structure from scratch using RMK, following the best practices. - **[Documentation generation:](docs/commands.md#doc)** Generate the full command documentation in the Markdown format with one click. -- **[Support for different types of code sources:](docs/configuration/rmk-configuration-management.md#use-upstream-artifact-for-the-downstream-projects-repository)** Use Git when the _artifact-mode_ is _none_, S3 when the _artifact-mode_ is _online_, +- **[Support for different types of code sources:](docs/configuration/configuration-management.md#use-upstream-artifact-for-the-downstream-projects-repository)** Use Git when the _artifact-mode_ is _none_, S3 when the _artifact-mode_ is _online_, switch to fully offline installations when the _artifact-mode_ is _offline_. ## Supported Kubernetes providers @@ -194,10 +194,10 @@ Check the [issues](https://github.com/edenlabllc/rmk/issues) for more informatio ## License -RMK is open source software (OSS) licensed under the [Apache 2.0 License](LICENSE). +RMK is open source software (OSS) licensed under the [Apache 2.0 License](https://github.com/edenlabllc/rmk/blob/master/LICENSE). ## Code of Conduct -This project adheres to the Contributor Covenant [Сode of Сonduct](https://github.com/edenlabllc/rmk/blob/develop/docs/CODE_OF_CONDUCT.md). +This project adheres to the Contributor Covenant [Сode of Сonduct](https://github.com/edenlabllc/rmk/blob/master/docs/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. -Please refer to our [Contributing Guidelines](https://github.com/edenlabllc/rmk/blob/develop/docs/CONTRIBUTING.md) for further information. +Please refer to our [Contributing Guidelines](https://github.com/edenlabllc/rmk/blob/master/docs/CONTRIBUTING.md) for further information. diff --git a/docs/.pages b/docs/.pages index cd15a0d..508728f 100644 --- a/docs/.pages +++ b/docs/.pages @@ -1,9 +1,7 @@ nav: - - README.md + - Overview: README.md - quickstart.md - configuration - - commands.md + - Commands: commands.md - development-and-release-flow.md - - release-notes.md - - release-notes.md collapse: false diff --git a/docs/README.md b/docs/README.md index 7a503b6..246076a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # RMK CLI - Reduced Management for Kubernetes [![Release](https://img.shields.io/github/v/release/edenlabllc/rmk.svg?style=for-the-badge)](https://github.com/edenlabllc/rmk/releases/latest) -[![Software License](https://img.shields.io/github/license/edenlabllc/rmk.svg?style=for-the-badge)](LICENSE) +[![Software License](https://img.shields.io/github/license/edenlabllc/rmk.svg?style=for-the-badge)](https://github.com/edenlabllc/rmk/blob/master/LICENSE) [![Powered By: Edenlab](https://img.shields.io/badge/powered%20by-edenlab-8A2BE2.svg?style=for-the-badge)](https://edenlab.io) Command line tool for reduced management and provisioning of Kubernetes clusters and environments, Helm secrets and releases. @@ -18,7 +18,7 @@ Command line tool for reduced management and provisioning of Kubernetes clusters * [General update process](#general-update-process) * [Update to specific version](#update-to-specific-version) * Configuration - * [RMK configuration management](configuration/rmk-configuration-management.md) + * [Configuration management](configuration/configuration-management.md) * Project management * [Requirement for project repository](configuration/project-management/requirement-for-project-repository.md) * [Preparation of project repository](configuration/project-management/preparation-of-project-repository.md) @@ -154,13 +154,13 @@ rmk update --version vX.X.X - **[Time-proven project structure:](configuration/project-management/preparation-of-project-repository.md)** Define the project structure using the [GitLabFlow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) methodology. - **[Hierarchies between different projects:](configuration/project-management/dependencies-management-and-project-inheritance.md)** Define upstream-downstream relationships between sibling projects to reuse releases and services across different installations. - **[Batch secret management:](configuration/secrets-management/secrets-management.md#generating-all-secrets-from-scratch-in-a-batch-manner-using-the-rmk-secrets-manager)** Template, generate, and encode project secrets for all environments in a batch manner. -- **[Clone environments with one click:](configuration/rmk-configuration-management.md#initialization-of-rmk-configuration-for-feature-or-release-clusters)** Use the special `--config-from-environment` (`--cfe`) flag to create an environment based on an existing one. -- **[Automatic detection of Multi-Factor Authentication](configuration/rmk-configuration-management.md#support-for-multi-factor-authentication-mfa) ([MFA](https://en.wikipedia.org/wiki/Multi-factor_authentication)):** Automatically detect and use an MFA device if one is defined by an [IAM](https://aws.amazon.com/iam/) user (must be supported by the cluster provider, e.g., [AWS](https://aws.amazon.com/)). +- **[Clone environments with one click:](configuration/configuration-management.md#initialization-of-rmk-configuration-for-feature-or-release-clusters)** Use the special `--config-from-environment` (`--cfe`) flag to create an environment based on an existing one. +- **[Automatic detection of Multi-Factor Authentication](configuration/configuration-management.md#support-for-multi-factor-authentication-mfa) ([MFA](https://en.wikipedia.org/wiki/Multi-factor_authentication)):** Automatically detect and use an MFA device if one is defined by an [IAM](https://aws.amazon.com/iam/) user (must be supported by the cluster provider, e.g., [AWS](https://aws.amazon.com/)). - **[Push-based release and downstream project updates:](configuration/release-management/release-management.md#release-update-and-integration-into-the-cd-pipeline)** Easily integrate with CI/CD solutions via webhooks or workflow dispatch events to update release and service version declarations, automatically commit the changes to Git. - **[Project structure generation:](configuration/project-management/preparation-of-project-repository.md#automatic-generation-of-the-project-structure-from-scratch)** Generate a complete Kubernetes-based project structure from scratch using RMK, following the best practices. - **[Documentation generation:](commands.md#doc)** Generate the full command documentation in the Markdown format with one click. -- **[Support for different types of code sources:](configuration/rmk-configuration-management.md#use-upstream-artifact-for-the-downstream-projects-repository)** Use Git when the _artifact-mode_ is _none_, S3 when the _artifact-mode_ is _online_, +- **[Support for different types of code sources:](configuration/configuration-management.md#use-upstream-artifact-for-the-downstream-projects-repository)** Use Git when the _artifact-mode_ is _none_, S3 when the _artifact-mode_ is _online_, switch to fully offline installations when the _artifact-mode_ is _offline_. ## Supported Kubernetes providers @@ -194,10 +194,10 @@ Check the [issues](https://github.com/edenlabllc/rmk/issues) for more informatio ## License -RMK is open source software (OSS) licensed under the [Apache 2.0 License](../LICENSE). +RMK is open source software (OSS) licensed under the [Apache 2.0 License](https://github.com/edenlabllc/rmk/blob/master/LICENSE). ## Code of Conduct -This project adheres to the Contributor Covenant [Сode of Сonduct](CODE_OF_CONDUCT.md). +This project adheres to the Contributor Covenant [Сode of Сonduct](https://github.com/edenlabllc/rmk/blob/master/docs/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. -Please refer to our [Contributing Guidelines](CONTRIBUTING.md) for further information. +Please refer to our [Contributing Guidelines](https://github.com/edenlabllc/rmk/blob/master/docs/CONTRIBUTING.md) for further information. diff --git a/docs/configuration/cluster-management/cluster-management.md b/docs/configuration/cluster-management/cluster-management.md index 10ac237..b849e55 100644 --- a/docs/configuration/cluster-management/cluster-management.md +++ b/docs/configuration/cluster-management/cluster-management.md @@ -47,7 +47,7 @@ Switching to an existing Kubernetes cluster depends on how it has been provision Checkout to the branch from which the K8S cluster was previously created. - An [initialization](../rmk-configuration-management.md#initialization-of-rmk-configuration) might be required, + An [initialization](../configuration-management.md#initialization-of-rmk-configuration) might be required, if the RMK configuration for this cluster has not been created before: ```shell @@ -167,7 +167,7 @@ The CLI will create a cluster according to the declarative instruction for K3D: > Prerequisites: > 1. Create a separate feature branch: `feature/--`. -> 2. [Initialize configuration](../rmk-configuration-management.md#initialization-of-rmk-configuration) for this branch with the `localhost` root domain name: +> 2. [Initialize configuration](../configuration-management.md#initialization-of-rmk-configuration) for this branch with the `localhost` root domain name: > ```shell > rmk config init --root-domain=localhost > ``` diff --git a/docs/configuration/rmk-configuration-management.md b/docs/configuration/configuration-management.md similarity index 99% rename from docs/configuration/rmk-configuration-management.md rename to docs/configuration/configuration-management.md index deea571..a0c3c3d 100644 --- a/docs/configuration/rmk-configuration-management.md +++ b/docs/configuration/configuration-management.md @@ -1,4 +1,4 @@ -# RMK configuration management +# Configuration management To start working with Kubernetes clusters, RMK needs to initialize the configuration for the current environment. At the time of configuration initialization launch, RMK prepares diff --git a/docs/configuration/project-management/preparation-of-project-repository.md b/docs/configuration/project-management/preparation-of-project-repository.md index 7c4cc8b..669b926 100644 --- a/docs/configuration/project-management/preparation-of-project-repository.md +++ b/docs/configuration/project-management/preparation-of-project-repository.md @@ -5,7 +5,7 @@ > - Clone the project repository. For example: **project.bootstrap.infra** OR `git init && git remote add && git commit -m "init commit"` > - Checkout the needed branch. For example: `develop|staging|production`. > - Make sure there is a file in the root of the repository named [project.yaml](#projectyaml), which contains the project configuration. -> - [Initialize the configuration](../rmk-configuration-management.md#initialization-of-rmk-configuration). +> - [Initialize the configuration](../configuration-management.md#initialization-of-rmk-configuration). ## Automatic generation of the project structure from scratch diff --git a/docs/quickstart.md b/docs/quickstart.md index 192a990..092a1aa 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -7,8 +7,8 @@ create a local cluster based on `K3D`, deploy your first application ([Nginx](ht > - An active AWS user with access keys and the `AdministratorAccess` permissions. > - A prepared [project repository](configuration/project-management/preparation-of-project-repository.md#preparation-of-the-project-repository) -[//]: # (> - Installed [RMK](../README.md#installation)) -[//]: # (> - The fulfilled [requirements](../README.md#requirements) for proper RMK operation.) +> - Installed [RMK](README.md#installation) +> - The fulfilled [requirements](README.md#requirements) for proper RMK operation. 0. Create a [project.yaml](configuration/project-management/preparation-of-project-repository.md#projectyaml) file in the root of the project repository with the following content: @@ -85,7 +85,7 @@ inventory: rename: true ``` -1. Run the [RMK configuration initialization](configuration/rmk-configuration-management.md#initialization-of-rmk-configuration) command for the repository: +1. Run the [RMK configuration initialization](configuration/configuration-management.md#initialization-of-rmk-configuration) command for the repository: ```shell rmk config init --root-domain=localhost --github-token= @@ -104,7 +104,7 @@ inventory: 3. Create a local K3D cluster: -[//]: # ( > Before running this step, ensure that Docker is installed in the system according to the [requirements](../README.md#requirements).) + > Before running this step, ensure that Docker is installed in the system according to the [requirements](README.md#requirements). ```shell rmk cluster k3d create diff --git a/mkdocs.yml b/mkdocs.yml index 76ae23d..9520414 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,6 +85,7 @@ plugins: extra: version: provider: mike + default: latest # Other Settings strict: true # halt processing when a warning is raised From 38e1be129ab84cc53125120c795656c83289acd8 Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Tue, 20 Aug 2024 17:08:48 +0200 Subject: [PATCH 05/29] #27 - Fix global styling, code blocks, lists across all MD files to display correctly as a published website. --- .github/workflows/docs-publish.yaml | 6 +- README.md | 21 ++++--- docs/README.md | 21 ++++--- .../cluster-management/cluster-management.md | 59 +++++++++++-------- .../configuration/configuration-management.md | 4 +- ...cies-management-and-project-inheritance.md | 22 ++++--- .../preparation-of-project-repository.md | 2 + .../requirement-for-project-repository.md | 6 +- .../release-management/release-management.md | 4 ++ .../secrets-management/secrets-management.md | 4 +- 10 files changed, 95 insertions(+), 54 deletions(-) diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml index 0fb9a9f..b212422 100644 --- a/.github/workflows/docs-publish.yaml +++ b/.github/workflows/docs-publish.yaml @@ -36,9 +36,11 @@ jobs: git config user.name github-actions git config user.email github-actions@github.com - echo tag=${GITHUB_REF#refs/tags/} >> "${GITHUB_OUTPUT}" + # todo remove tag hardcode used for tests + # echo tag=${GITHUB_REF#refs/tags/} >> "${GITHUB_OUTPUT}" + echo tag=v0.43.0 >> "${GITHUB_OUTPUT}" - name: Build, publish, version documentation using Mike # if: startsWith(github.ref, 'refs/tags/') run: | -# mike deploy --update-aliases --push --rebase ${{ steps.git-configuration.outputs.tag }} latest + mike deploy --update-aliases --push --rebase ${{ steps.git-configuration.outputs.tag }} latest diff --git a/README.md b/README.md index fa6d856..09e7a95 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,7 @@ The main goal of the tool is to simplify ("reduce") management of Kubernetes clu ### Advantages RMK simplifies the start of any level of complexity of a project using Kubernetes due to the following advantages: + - **Respects the [GitOPS](https://www.gitops.tech/) approach:** Each Git branch is used as a unique identifier for determining the environment, cluster name, set of configurations and other attributes required for setting up the wrapped tools for project management in the Kubernetes environment. - **Respects the [GitLabFlow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) workflow**: Supports the standard _develop_, _staging_, _production_ and different ephemeral (e.g, _feature_, _release_) environments. @@ -75,18 +76,21 @@ RMK simplifies the start of any level of complexity of a project using Kubernete At [Edenlab LLC](https://edenlab.io/), RMK is used for deploying the [Kodjin FHIR Server](https://kodjin.com). A classic Kodjin installation uses 3-level inheritance: + - **Dependencies (upstream#1)**: Core components like DBs, search engines, caches, load balancers/proxies, operators etc. - **Kodjin (downstream#1)**: Kodjin FHIR API ([REST](https://en.wikipedia.org/wiki/REST)) - **Target installation (downstream#2)**: Products based on Kodjin, such as UI components, user portals and middleware services. The additional components used by Kodjin are: + - **\*.provisioner.infra:** Repositories for Kubernetes cluster provisioning. - **helmfile.hooks.infra:** Shell scrips used as [Helmfile hooks](https://helmfile.readthedocs.io/en/latest/#hooks) in deps/Kodjin/any other tenant. - **core.charts.infra:** Helm charts used by the Kodjin services. The examples of Kubernetes providers, to which Kodjin has been installed, are: + - [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) - [Open Telekom Cloud - Cloud Container Engine (CCE)](https://www.open-telekom-cloud.com/en/products-services/core-services/cloud-container-engine) - [Rancher Kubernetes Platform](https://www.rancher.com/) @@ -104,14 +108,15 @@ The examples of Kubernetes providers, to which Kodjin has been installed, are: ## Requirements Currently, RMK only supports Unix-like operating systems (OS): -* **OS:** - * **MacOS**: amd64, arm64 (M1, M2 require [Rosetta](https://support.apple.com/en-us/HT211861)) - * **Linux**: amd64 -* **Software:** - * **Python** >= 3.9 - * **[AWS CLI](https://aws.amazon.com/cli/)** - * _For managing local clusters using K3D:_ Version _v5.x.x_ requires [Docker](https://www.docker.com/) => v20.10.5 ([runc](https://github.com/opencontainers/runc) >= v1.0.0-rc93) to work - properly. + +- **OS:** + - **MacOS**: amd64, arm64 (M1, M2 require [Rosetta](https://support.apple.com/en-us/HT211861)) + - **Linux**: amd64 +- **Software:** + - **Python** >= 3.9 + - **[AWS CLI](https://aws.amazon.com/cli/)** + - _For managing local clusters using K3D:_ Version _v5.x.x_ requires [Docker](https://www.docker.com/) => v20.10.5 ([runc](https://github.com/opencontainers/runc) >= v1.0.0-rc93) to work + properly. > If this is your first project repository managed by RMK, ensure that the above tools are specified in the [project.yaml](docs/configuration/project-management/preparation-of-project-repository.md#projectyaml) file. diff --git a/docs/README.md b/docs/README.md index 246076a..b641b11 100644 --- a/docs/README.md +++ b/docs/README.md @@ -56,6 +56,7 @@ The main goal of the tool is to simplify ("reduce") management of Kubernetes clu ### Advantages RMK simplifies the start of any level of complexity of a project using Kubernetes due to the following advantages: + - **Respects the [GitOPS](https://www.gitops.tech/) approach:** Each Git branch is used as a unique identifier for determining the environment, cluster name, set of configurations and other attributes required for setting up the wrapped tools for project management in the Kubernetes environment. - **Respects the [GitLabFlow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) workflow**: Supports the standard _develop_, _staging_, _production_ and different ephemeral (e.g, _feature_, _release_) environments. @@ -75,18 +76,21 @@ RMK simplifies the start of any level of complexity of a project using Kubernete At [Edenlab LLC](https://edenlab.io/), RMK is used for deploying the [Kodjin FHIR Server](https://kodjin.com). A classic Kodjin installation uses 3-level inheritance: + - **Dependencies (upstream#1)**: Core components like DBs, search engines, caches, load balancers/proxies, operators etc. - **Kodjin (downstream#1)**: Kodjin FHIR API ([REST](https://en.wikipedia.org/wiki/REST)) - **Target installation (downstream#2)**: Products based on Kodjin, such as UI components, user portals and middleware services. The additional components used by Kodjin are: + - **\*.provisioner.infra:** Repositories for Kubernetes cluster provisioning. - **helmfile.hooks.infra:** Shell scrips used as [Helmfile hooks](https://helmfile.readthedocs.io/en/latest/#hooks) in deps/Kodjin/any other tenant. - **core.charts.infra:** Helm charts used by the Kodjin services. The examples of Kubernetes providers, to which Kodjin has been installed, are: + - [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) - [Open Telekom Cloud - Cloud Container Engine (CCE)](https://www.open-telekom-cloud.com/en/products-services/core-services/cloud-container-engine) - [Rancher Kubernetes Platform](https://www.rancher.com/) @@ -104,14 +108,15 @@ The examples of Kubernetes providers, to which Kodjin has been installed, are: ## Requirements Currently, RMK only supports Unix-like operating systems (OS): -* **OS:** - * **MacOS**: amd64, arm64 (M1, M2 require [Rosetta](https://support.apple.com/en-us/HT211861)) - * **Linux**: amd64 -* **Software:** - * **Python** >= 3.9 - * **[AWS CLI](https://aws.amazon.com/cli/)** - * _For managing local clusters using K3D:_ Version _v5.x.x_ requires [Docker](https://www.docker.com/) => v20.10.5 ([runc](https://github.com/opencontainers/runc) >= v1.0.0-rc93) to work - properly. + +- **OS:** + - **MacOS**: amd64, arm64 (M1, M2 require [Rosetta](https://support.apple.com/en-us/HT211861)) + - **Linux**: amd64 +- **Software:** + - **Python** >= 3.9 + - **[AWS CLI](https://aws.amazon.com/cli/)** + - _For managing local clusters using K3D:_ Version _v5.x.x_ requires [Docker](https://www.docker.com/) => v20.10.5 ([runc](https://github.com/opencontainers/runc) >= v1.0.0-rc93) to work + properly. > If this is your first project repository managed by RMK, ensure that the above tools are specified in the [project.yaml](configuration/project-management/preparation-of-project-repository.md#projectyaml) file. diff --git a/docs/configuration/cluster-management/cluster-management.md b/docs/configuration/cluster-management/cluster-management.md index b849e55..1012299 100644 --- a/docs/configuration/cluster-management/cluster-management.md +++ b/docs/configuration/cluster-management/cluster-management.md @@ -5,6 +5,7 @@ RMK uses [Terraform](https://www.terraform.io/) and [K3D](https://k3d.io) for cl RMK is suitable for both simple and complex Kubernetes deployments, enabling multi-level project inheritance through native Helmfile functionality. The 2 scenarios are: + - **A cluster has already been provisioned via a 3rd-party tool/service:** An existing Kubernetes context will be used by RMK. - **A cluster will be provisioned from scratch using RMK**: Any of the supported cluster providers for RMK, such as AWS, K3D, etc. will be utilized. @@ -38,6 +39,7 @@ Switching to an existing Kubernetes cluster depends on how it has been provision > If there are **more than one** Kubernetes context which match the regular expression **simultaneously**, > an **error** will be thrown indicating a conflict. For example, the following names will conflict: + > > ```shell > project1-develop > k3d-project1-develop @@ -77,6 +79,7 @@ rmk release list ## Use RMK cluster providers to provision and destroy Kubernetes clusters Currently, the following cluster providers are supported by RMK: + - [aws.provisioner.infra](https://github.com/edenlabllc/aws.provisioner.infra): Configuration for managing AWS EKS clusters using Terraform. Kubernetes clusters can be provisioned from scratch and destroyed via the `rmk cluster provision`, `rmk cluster destroy` commands. @@ -94,9 +97,12 @@ This enhancement will include the introduction of new RMK commands and cluster p Before provisioning the K8S cluster, modify the core configurations for the on-demand cluster. The core configurations are divided into two types: -- **variables** (common AWS cluster management): \ - _Path:_ `etc/clusters/aws//values/variables.auto.tfvars` \ +- **variables** (common AWS cluster management): + + _Path:_ `etc/clusters/aws//values/variables.auto.tfvars` + _Frequently changed values:_ + ```terraform # k8s user list k8s_master_usernames = [] # list of AWS IAM users for K8S cluster management @@ -104,9 +110,14 @@ The core configurations are divided into two types: # ... ``` -- **worker-groups** (resources for AWS worker nodes): \ - _Path:_ `etc/clusters/aws//values/worker-groups.auto.tfvars` \ + > Full list of input Terraform variables: `.PROJECT/inventory/clusters/aws.provisioner.infra-/terraform/variables.tf` + +- **worker-groups** (resources for AWS worker nodes): + + _Path:_ `etc/clusters/aws//values/worker-groups.auto.tfvars` + _Frequently changed values:_ + ```terraform worker_groups = [ { @@ -120,26 +131,24 @@ The core configurations are divided into two types: # ... ] ``` - - - `instance_type`: [AWS EC2 instance type](https://aws.amazon.com/ec2/instance-types) - - `asg_desired_capacity`: Number of nodes of a specific group. - - `ami_id`: Identifier of AWS AMI image for EKS. - - > Each AWS region requires its own AMI image ID. To determine the appropriate ID for a specific region, run the following command: - > ```shell - > AWS_PROFILE=$(rmk --lf=json config view | yq '.config.Profile') \ - > AWS_CONFIG_FILE="${HOME}/.aws/config_$(rmk --lf=json config view | yq '.config.Profile')" \ - > AWS_SHARED_CREDENTIALS_FILE="${HOME}/.aws/credentials_$(rmk --lf=json config view | yq '.config.Profile')" \ - > AWS_PAGER= \ - > aws ssm get-parameter \ - > --name /aws/service/eks/optimized-ami//amazon-linux-2/recommended/image_id \ - > --region "$(rmk --lf=json config view | yq '.config.Region')" \ - > --output text \ - > --query Parameter.Value - > ``` - > > Replace `` with a correct version. - -Full list of input Terraform variables: `.PROJECT/inventory/clusters/aws.provisioner.infra-/terraform/variables.tf` + + - `instance_type`: [AWS EC2 instance type](https://aws.amazon.com/ec2/instance-types) + - `asg_desired_capacity`: Number of nodes of a specific group. + - `ami_id`: Identifier of AWS AMI image for EKS. + > Each AWS region requires its own AMI image ID. To determine the appropriate ID for a specific region, run the following command: + > + > ```shell + > AWS_PROFILE=$(rmk --lf=json config view | yq '.config.Profile') \ + > AWS_CONFIG_FILE="${HOME}/.aws/config_$(rmk --lf=json config view | yq '.config.Profile')" \ + > AWS_SHARED_CREDENTIALS_FILE="${HOME}/.aws/credentials_$(rmk --lf=json config view | yq '.config.Profile')" \ + > AWS_PAGER= \ + > aws ssm get-parameter \ + > --name /aws/service/eks/optimized-ami//amazon-linux-2/recommended/image_id \ + > --region "$(rmk --lf=json config view | yq '.config.Region')" \ + > --output text \ + > --query Parameter.Value + > ``` + > > Replace `` with a correct version. To start provisioning a Kubernetes cluster, run the commands: @@ -166,8 +175,10 @@ The CLI will create a cluster according to the declarative instruction for K3D: `.PROJECT/inventory/clusters/k3d.provisioner.infra-/k3d.yaml`. > Prerequisites: +> > 1. Create a separate feature branch: `feature/--`. > 2. [Initialize configuration](../configuration-management.md#initialization-of-rmk-configuration) for this branch with the `localhost` root domain name: +> > ```shell > rmk config init --root-domain=localhost > ``` diff --git a/docs/configuration/configuration-management.md b/docs/configuration/configuration-management.md index a0c3c3d..3cd0613 100644 --- a/docs/configuration/configuration-management.md +++ b/docs/configuration/configuration-management.md @@ -28,8 +28,9 @@ aws: ## Initialization of RMK configuration > Prerequisites: +> > - The `GITHUB_TOKEN` variable or `--github-token` flag are required: [GitHub Personal Access Tokens (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). -> The token should have the `repo: full control` permissions. +> > The token should have the `repo: full control` permissions. > - [Project repository](project-management/requirement-for-project-repository.md) has already been created and initialized. > - At least one Git branch for the environment exists already. @@ -133,6 +134,7 @@ rmk config init --artifact-mode=online ``` > Currently, only two artifact modes are supported: +> > - `none`: The standard mode of RMK which is used for development normally, the codebase will be downloaded from GitHub repositories. > The mode does not require the presence of the special "license" credentials. > - `online`: Switches RMK to work with artifacts. In this mode, RMK will not use any credentials for GitHub diff --git a/docs/configuration/project-management/dependencies-management-and-project-inheritance.md b/docs/configuration/project-management/dependencies-management-and-project-inheritance.md index 99aef15..441395a 100644 --- a/docs/configuration/project-management/dependencies-management-and-project-inheritance.md +++ b/docs/configuration/project-management/dependencies-management-and-project-inheritance.md @@ -8,6 +8,7 @@ in the root directory according to the sections described in the [project.yaml]( > To override inherited versions of dependencies and add-ons described in the inventory, > you need to specify the entire block with all the required fields. +> > ```yaml > inventory: > # ... @@ -47,16 +48,18 @@ RMK allows to avoid controlling the versioning of the `Helmfile` hooks through t instead of it, RMK allows inheriting these version hooks from the upstream project's repository. It also supports multi-versioning of the `Helmfile` hooks as part of the inheritance from several upstream projects by a downstream project. -> In order for these features to work, you need to use the `HELMFILE__HOOKS_DIR` variable in `helmfile.yaml.gotmpl`. -> For example: -> ```yaml -> commonLabels: -> # ... -> bin: {{ env "HELMFILE_KODJIN_HOOKS_DIR" }}/bin -> # ... -> ``` +In order for these features to work, you need to use the `HELMFILE__HOOKS_DIR` variable in `helmfile.yaml.gotmpl`. +For example: + +```yaml +commonLabels: +# ... + bin: {{ env "HELMFILE_KODJIN_HOOKS_DIR" }}/bin +# ... +``` Let's look at the following examples of the inheritance: + 1. **Hook version inheritance from the upstream project's repository:** The [project.yaml](preparation-of-project-repository.md#projectyaml) file of the downstream project is the following: @@ -101,6 +104,7 @@ Let's look at the following examples of the inheritance: > of the `deps.bootstrap.infra` repository, since there is no inheritance. This configuration scheme is **the most common** and has the following inheritance scheme for the `Helmfile` hooks: + ```textmate Project repo name: deps.bootstrap.infra ---------> kodjin.bootstrap.infra -------> .bootstrap.infra Project repo version: v2.19.0 v4.4.0 @@ -165,8 +169,10 @@ Let's look at the following examples of the inheritance: > The downstream project's repository will inherit the latest version of `Helmfile` hooks, specifically from the `deps.bootstrap.infra` repository. > As a result, in the downstream project's repository, we will have the two loaded versions of `Helmfile` hooks: + > > - One will be relevant for the `deps.bootstrap.infra` repository and the downstream project's repository. > - Another will be relevant for the `kodjin.bootstrap.infra` repository. + > > This mechanism allows for multi-versioning support of the `Helmfile` hooks at different levels of the inheritance. 3. **Hook version inheritance from the upstream project's repository in case the downstream project diff --git a/docs/configuration/project-management/preparation-of-project-repository.md b/docs/configuration/project-management/preparation-of-project-repository.md index 669b926..2eb4e45 100644 --- a/docs/configuration/project-management/preparation-of-project-repository.md +++ b/docs/configuration/project-management/preparation-of-project-repository.md @@ -1,6 +1,7 @@ # Preparation of the project repository > Prerequisite: +> > - Create a remote repository in your Version Control System (GitHub) according to the following [requirements](requirement-for-project-repository.md#requirement-for-project-repository). > - Clone the project repository. For example: **project.bootstrap.infra** OR `git init && git remote add && git commit -m "init commit"` > - Checkout the needed branch. For example: `develop|staging|production`. @@ -214,5 +215,6 @@ The project file supports placeholders, they are required for correct URL format > The field `rename` of the boolean type is required to correct the name of the binary file of the downloaded tool > according to the value of the `name` field. This is mainly required for the cases, when the artifact is not the archive. > For example: +> > - The initial file name after the download: `helmfile_darwin_amd64`. > - After applying the `rename` instruction it gets a value of the `name` field: `helmfile`. diff --git a/docs/configuration/project-management/requirement-for-project-repository.md b/docs/configuration/project-management/requirement-for-project-repository.md index a529f79..6197e1b 100644 --- a/docs/configuration/project-management/requirement-for-project-repository.md +++ b/docs/configuration/project-management/requirement-for-project-repository.md @@ -4,11 +4,14 @@ For example: `kodjin.bootstrap.infra` or `kodjin.infra`. 2. The project's repository exists within [GitLabFlow](https://docs.gitlab.co.jp/ee/topics/gitlab_flow.html) only and therefor supports the following set of static branches: + - `develop` - `staging` - `production` + Each branch corresponds to its own environment with a separately deployed K8S cluster. RMK supports these branches as well as the feature or release branches: + - A feature branch should have the following naming: `feature/--`. For example: `feature/FFS-1446-example`. RMK will use `` and `` as the feature cluster name. - A release branch should have the following naming: `release/-rc` or `release/` @@ -91,7 +94,8 @@ hooks: # ... ``` -> globals.yaml.gotmpl is used in two cases: +> globals.yaml.gotmpl is used in two cases: +> > 1. When values, configurations or environment variables need to be declared globally for multiple releases. > 2. When the current project is planned to be inherited by a downstream project and the overrides should be supported. diff --git a/docs/configuration/release-management/release-management.md b/docs/configuration/release-management/release-management.md index 773aadd..3c217d9 100644 --- a/docs/configuration/release-management/release-management.md +++ b/docs/configuration/release-management/release-management.md @@ -73,9 +73,11 @@ rmk release destroy Among the `Helmfile` selectors, the following [predefined keys](https://helmfile.readthedocs.io/en/stable/#labels-overview) are provided out of the box: + - Release name. - Release namespace. - Chart name. + For example: ```shell @@ -146,6 +148,7 @@ it can be integrated with almost any CI/CD system: GitHub Actions, GitLab, Drone ### Example of integration with GitHub Actions: > Prerequisites: +> > - The project repository has already been generated and [prepared](../project-management/preparation-of-project-repository.md) using RMK. Create the following workflow in your project repository at `.github/workflows/release-update.yaml`. @@ -192,6 +195,7 @@ jobs: ``` In this example, we have prepared a `GitHub Action` that expects two input parameters: + - `image_repository_full_name` - `version` diff --git a/docs/configuration/secrets-management/secrets-management.md b/docs/configuration/secrets-management/secrets-management.md index 62e593e..e8f807a 100644 --- a/docs/configuration/secrets-management/secrets-management.md +++ b/docs/configuration/secrets-management/secrets-management.md @@ -71,8 +71,8 @@ Also, before generating the secret files, you must create or complete a secret ` The additional functions which included in the template functions are: -- **{{`{{ requiredEnv "ENV_NAME" }}`}}:** The function requires an input of the specified mandatory variable. -- **{{`{{ prompt "password" }}`}}:** The function asks for interactive input. Useful for entering sensitive data. +- **{{\`{{ requiredEnv "ENV_NAME" }}\`}}:** The function requires an input of the specified mandatory variable. +- **{{\`{{ prompt "password" }}\`}}:** The function asks for interactive input. Useful for entering sensitive data. Example of the files needed for the generation: From 589ef66e2076930fe7b60ab2d4f74b8c22dabd28 Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Tue, 20 Aug 2024 17:10:11 +0200 Subject: [PATCH 06/29] #27 - Fix docs-publish.yaml workflow syntax. --- .github/workflows/docs-publish.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml index b212422..3ccb129 100644 --- a/.github/workflows/docs-publish.yaml +++ b/.github/workflows/docs-publish.yaml @@ -24,7 +24,8 @@ jobs: - name: Build, validate documentation using MkDocs run: | -# git config --global --add safe.directory /__w/rmk/rmk + # todo check if it is needed + # git config --global --add safe.directory /__w/rmk/rmk mkdocs build --verbose --clean --strict rm -r site/ From fd37027492f52e2e854a21ea8052f6c2eba97aac Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Wed, 21 Aug 2024 13:37:16 +0200 Subject: [PATCH 07/29] #27 - Remove CNAME. Improve docs-publish.yaml workflow. Refactor theme.features in mkdocs.yml. --- .github/workflows/docs-publish.yaml | 34 ++++++++++++----------------- .github/workflows/release.yml | 1 + docs/CNAME | 1 - mkdocs.yml | 24 ++++++++++---------- 4 files changed, 26 insertions(+), 34 deletions(-) delete mode 100644 docs/CNAME diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml index 3ccb129..ee0460b 100644 --- a/.github/workflows/docs-publish.yaml +++ b/.github/workflows/docs-publish.yaml @@ -1,18 +1,20 @@ -name: Build and publish documentation to GitHub Pages +name: Build, validate, publish, version documentation for GitHub Pages on: push: branches: - - feature/* - master -# tags: -# - 'v[0-9]+.[0-9]+.[0-9]+' + - develop + - feature/* + - release/* + - hotfix/* + tags: + - 'v[0-9]+.[0-9]+.[0-9]+' jobs: - build: + publish: + name: Build, validate, publish, version documentation for GitHub Pages runs-on: ubuntu-22.04 -# container: -# image: python:3.9 steps: - name: Checkout uses: actions/checkout@v4 @@ -24,24 +26,16 @@ jobs: - name: Build, validate documentation using MkDocs run: | - # todo check if it is needed - # git config --global --add safe.directory /__w/rmk/rmk mkdocs build --verbose --clean --strict rm -r site/ - - name: Configure Git -# if: startsWith(github.ref, 'refs/tags/') - id: git-configuration + - name: Build, publish, version documentation using Mike (only for stable tags) + if: startsWith(github.ref, 'refs/tags/') run: | echo "Configure Git user.name and user.email." git config user.name github-actions git config user.email github-actions@github.com - # todo remove tag hardcode used for tests - # echo tag=${GITHUB_REF#refs/tags/} >> "${GITHUB_OUTPUT}" - echo tag=v0.43.0 >> "${GITHUB_OUTPUT}" - - - name: Build, publish, version documentation using Mike -# if: startsWith(github.ref, 'refs/tags/') - run: | - mike deploy --update-aliases --push --rebase ${{ steps.git-configuration.outputs.tag }} latest + VERSION=${GITHUB_REF#refs/tags/} + + mike deploy --update-aliases --push --rebase "${VERSION}" latest diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d8d71a8..c330756 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,6 +15,7 @@ env: jobs: goreleaser: + name: Release RMK using GoReleaser runs-on: ubuntu-22.04 steps: - name: Checkout diff --git a/docs/CNAME b/docs/CNAME deleted file mode 100644 index 3c1c2db..0000000 --- a/docs/CNAME +++ /dev/null @@ -1 +0,0 @@ -rmk.io diff --git a/mkdocs.yml b/mkdocs.yml index 9520414..05869a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,6 @@ # Project information site_name: RMK site_description: RMK CLI - Reduced Management for Kubernetes by Edenlab LLC. -# todo change to static domain site_url: https://edenlabllc.github.io/rmk copyright: © EDENLAB. ALL RIGHTS RESERVED, 2021 - 2024 @@ -15,34 +14,33 @@ theme: name: material language: en features: - - navigation.top # show back to top button - - search.suggest # search suggestions: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions - - search.highlight # highlight search term on target page: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions + # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/ + - search.highlight + - search.share + - search.suggest + # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/ - navigation.expand + - navigation.indexes + - navigation.instant - navigation.tabs - navigation.tabs.sticky # stick navigation tabs below header while scrolling + - navigation.top # show back to top button - navigation.tracking - navigation.path -# todo review list of features -# - navigation.instant -# - navigation.sections -# - navigation.indexes palette: - media: "(prefers-color-scheme: light)" scheme: default - primary: "black" - accent: "grey" + primary: black + accent: grey toggle: icon: material/toggle-switch-off-outline name: Switch to dark mode - media: "(prefers-color-scheme: dark)" scheme: slate - primary: light blue + primary: black toggle: icon: material/toggle-switch name: Switch to light mode - # todo change icons and logo -# logo: https://edenlab.io/wp-content/themes/edenlab/assets/images/fhir_icon.svg favicon: https://edenlab.io/favicon.ico icon: repo: fontawesome/brands/github From a1879237b80ff6caedaf9ce693e0f8555cd486d1 Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Wed, 21 Aug 2024 15:22:44 +0200 Subject: [PATCH 08/29] #27 - Minor fixes to .pages navigation. --- docs/.pages | 2 +- mkdocs.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/.pages b/docs/.pages index 508728f..9854473 100644 --- a/docs/.pages +++ b/docs/.pages @@ -1,7 +1,7 @@ nav: - Overview: README.md - quickstart.md - - configuration + - Configuration and management: configuration - Commands: commands.md - development-and-release-flow.md collapse: false diff --git a/mkdocs.yml b/mkdocs.yml index 05869a1..1913e67 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ # Project information site_name: RMK -site_description: RMK CLI - Reduced Management for Kubernetes by Edenlab LLC. +site_description: RMK CLI - Reduced Management for Kubernetes by Edenlab LLC site_url: https://edenlabllc.github.io/rmk copyright: © EDENLAB. ALL RIGHTS RESERVED, 2021 - 2024 From efb49ac9a7689dc969738680b4bceefce8a35803 Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Thu, 22 Aug 2024 09:33:17 +0200 Subject: [PATCH 09/29] #27 - Remove unneeded H1 headers in commands.md. Fix list in preparation-of-project-repository.md. --- .github/workflows/docs-publish.yaml | 5 +- docs/commands.md | 120 +++++++++--------- .../preparation-of-project-repository.md | 2 +- docs/quickstart.md | 4 +- 4 files changed, 66 insertions(+), 65 deletions(-) diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml index ee0460b..350edbb 100644 --- a/.github/workflows/docs-publish.yaml +++ b/.github/workflows/docs-publish.yaml @@ -30,12 +30,13 @@ jobs: rm -r site/ - name: Build, publish, version documentation using Mike (only for stable tags) - if: startsWith(github.ref, 'refs/tags/') +# if: startsWith(github.ref, 'refs/tags/') run: | echo "Configure Git user.name and user.email." git config user.name github-actions git config user.email github-actions@github.com - VERSION=${GITHUB_REF#refs/tags/} +# VERSION=${GITHUB_REF#refs/tags/} + VERSION=v0.43.0 mike deploy --update-aliases --push --rebase "${VERSION}" latest diff --git a/docs/commands.md b/docs/commands.md index 34ff637..8e0ac43 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -2,7 +2,7 @@ rmk - Reduced management for Kubernetes -# SYNOPSIS +## SYNOPSIS rmk @@ -13,7 +13,7 @@ rmk [--version|-v] ``` -# DESCRIPTION +## DESCRIPTION Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. BuiltBy: goreleaser @@ -27,7 +27,7 @@ Target: linux_amd64 rmk [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] ``` -# GLOBAL OPTIONS +## GLOBAL OPTIONS **--help, -h**: show help @@ -38,109 +38,109 @@ rmk [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] **--version, -v**: print the version -# COMMANDS +## COMMANDS -## cluster +### cluster Cluster management -### container-registry, c +#### container-registry, c Container registry management -#### login +##### login Log in to container registry **--get-token, -g**: get ECR token for authentication -#### logout +##### logout Log out from container registry -### destroy, d +#### destroy, d Destroy AWS cluster using Terraform -### list, l +#### list, l List all Terraform available workspaces -### k3d, k +#### k3d, k K3D cluster management -#### create, c +##### create, c Create K3D cluster **--k3d-volume-host-path, --kv**="": host local directory path for mount into K3D cluster (default: present working directory) -#### delete, d +##### delete, d Delete K3D cluster -#### import, i +##### import, i Import images from docker to K3D cluster **--k3d-import-image, --ki**="": list images for import into K3D cluster -#### list, l +##### list, l List K3D clusters -#### start, s +##### start, s Start K3D cluster -#### stop +##### stop Stop K3D cluster -### provision, p +#### provision, p Provision AWS cluster using Terraform **--plan, -p**: creates an execution Terraform plan -### state, t +#### state, t State cluster management using Terraform -#### delete, d +##### delete, d Delete resource from Terraform state **--resource-address, --ra**="": resource address for delete from Terraform state -#### list, l +##### list, l List resources from Terraform state -#### refresh, r +##### refresh, r Update state file for AWS cluster using Terraform -### switch, s +#### switch, s Switch Kubernetes context for tenant cluster **--force, -f**: force update Kubernetes context from remote cluster -## completion +### completion Completion management -### zsh, z +#### zsh, z View Zsh completion scripts -## config +### config Configuration management -### init, i +#### init, i Initialize configuration for current tenant and selected environment @@ -180,51 +180,51 @@ Initialize configuration for current tenant and selected environment **--slack-webhook, --sw**="": URL for Slack webhook -### delete, d +#### delete, d Delete configuration for selected environment -### list, l +#### list, l List available configurations for current tenant **--all, -a**: list all tenant configurations -### view, v +#### view, v View configuration for selected environment -## doc +### doc Documentation management **--help, -h**: show help -### generate, g +#### generate, g Generate documentation by commands and flags in Markdown format **--help, -h**: show help -#### help, h +##### help, h Shows a list of commands or help for one command -### help, h +#### help, h Shows a list of commands or help for one command -## project +### project Project management -### generate, g +#### generate, g Generate project directories and files structure **--create-sops-age-keys, -c**: create SOPS age keys for generated project structure -### update, u +#### update, u Update project file with specific dependencies version @@ -236,11 +236,11 @@ Update project file with specific dependencies version **--version, -v**="": specific dependency version for updating project file -## release +### release Release components list from state file (Helmfile) -### build, b +#### build, b Build releases @@ -252,7 +252,7 @@ Build releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### destroy, d +#### destroy, d Destroy releases @@ -266,7 +266,7 @@ Destroy releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### list, l +#### list, l List releases @@ -280,7 +280,7 @@ List releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### rollback, r +#### rollback, r Rollback specific releases to latest stable state @@ -288,7 +288,7 @@ Rollback specific releases to latest stable state **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### sync, s +#### sync, s Sync releases @@ -300,7 +300,7 @@ Sync releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### template, t +#### template, t Template releases @@ -312,7 +312,7 @@ Template releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### update, u +#### update, u Update releases file with specific environment values @@ -328,15 +328,15 @@ Update releases file with specific environment values **--tag, -t**="": specific tag for updating releases file -## secret +### secret secrets management -### manager, m +#### manager, m batch secrets management -#### decrypt, d +##### decrypt, d Decrypt secrets batch for selected scope and environment @@ -344,7 +344,7 @@ Decrypt secrets batch for selected scope and environment **--scope, -s**="": specific scopes for selected secrets -#### encrypt, e +##### encrypt, e Encrypt secrets batch for selected scope and environment @@ -352,7 +352,7 @@ Encrypt secrets batch for selected scope and environment **--scope, -s**="": specific scopes for selected secrets -#### generate, g +##### generate, g Generate secrets batch for selected scope and environment @@ -362,39 +362,39 @@ Generate secrets batch for selected scope and environment **--scope, -s**="": specific scopes for selected secrets -### keys, k +#### keys, k SOPS age keys management -#### create, c +##### create, c Create SOPS age keys -#### download, d +##### download, d Download SOPS age keys from S3 bucket -#### upload, u +##### upload, u Upload SOPS age keys to S3 bucket -### encrypt, e +#### encrypt, e Encrypt secret file -### decrypt, d +#### decrypt, d Decrypt secret file -### view, v +#### view, v View secret file -### edit +#### edit Edit secret file -## update +### update Update RMK CLI to a new version @@ -402,6 +402,6 @@ Update RMK CLI to a new version **--version, -v**="": RMK special version. (default: empty value corresponds latest version) -## help, h +### help, h Shows a list of commands or help for one command diff --git a/docs/configuration/project-management/preparation-of-project-repository.md b/docs/configuration/project-management/preparation-of-project-repository.md index 2eb4e45..ed9e42b 100644 --- a/docs/configuration/project-management/preparation-of-project-repository.md +++ b/docs/configuration/project-management/preparation-of-project-repository.md @@ -1,6 +1,6 @@ # Preparation of the project repository -> Prerequisite: +> Prerequisites: > > - Create a remote repository in your Version Control System (GitHub) according to the following [requirements](requirement-for-project-repository.md#requirement-for-project-repository). > - Clone the project repository. For example: **project.bootstrap.infra** OR `git init && git remote add && git commit -m "init commit"` diff --git a/docs/quickstart.md b/docs/quickstart.md index 092a1aa..75a0217 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -3,10 +3,10 @@ This guide demonstrates how to use `RMK` to prepare the structure of a new project in five steps, create a local cluster based on `K3D`, deploy your first application ([Nginx](https://nginx.org/)) using `Helmfile` releases. -> Prerequisite: +> Prerequisites: +> > - An active AWS user with access keys and the `AdministratorAccess` permissions. > - A prepared [project repository](configuration/project-management/preparation-of-project-repository.md#preparation-of-the-project-repository) - > - Installed [RMK](README.md#installation) > - The fulfilled [requirements](README.md#requirements) for proper RMK operation. From b7dd8a280c2de972c92e285aa1cdfc8f50960bcd Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Thu, 22 Aug 2024 09:34:05 +0200 Subject: [PATCH 10/29] #27 - Tmp commit to docs-publish.yaml to republish docs. --- .github/workflows/docs-publish.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml index 350edbb..970d0c3 100644 --- a/.github/workflows/docs-publish.yaml +++ b/.github/workflows/docs-publish.yaml @@ -36,7 +36,7 @@ jobs: git config user.name github-actions git config user.email github-actions@github.com -# VERSION=${GITHUB_REF#refs/tags/} + # VERSION=${GITHUB_REF#refs/tags/} VERSION=v0.43.0 mike deploy --update-aliases --push --rebase "${VERSION}" latest From b988aa60e5929b4270b95d2b4cd796880d3f0a76 Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Thu, 22 Aug 2024 09:36:00 +0200 Subject: [PATCH 11/29] #27 - Revert: Tmp commit to docs-publish.yaml to republish docs. --- .github/workflows/docs-publish.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml index 970d0c3..ee0460b 100644 --- a/.github/workflows/docs-publish.yaml +++ b/.github/workflows/docs-publish.yaml @@ -30,13 +30,12 @@ jobs: rm -r site/ - name: Build, publish, version documentation using Mike (only for stable tags) -# if: startsWith(github.ref, 'refs/tags/') + if: startsWith(github.ref, 'refs/tags/') run: | echo "Configure Git user.name and user.email." git config user.name github-actions git config user.email github-actions@github.com - # VERSION=${GITHUB_REF#refs/tags/} - VERSION=v0.43.0 + VERSION=${GITHUB_REF#refs/tags/} mike deploy --update-aliases --push --rebase "${VERSION}" latest From f483d4b37542db62069b561a5bd5a4c8330d5350 Mon Sep 17 00:00:00 2001 From: Aliaksandr Panasiuk Date: Mon, 2 Sep 2024 14:50:19 +0200 Subject: [PATCH 12/29] #42 - fix markdown headers in rmk doc generate command --- docs/release-notes.md | 4 ++-- main.go | 3 +++ system/dictionary.go | 33 +++++++++++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 2 deletions(-) diff --git a/docs/release-notes.md b/docs/release-notes.md index cbd77a9..ca81488 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,2 +1,2 @@ -- #33 - Added a new GitHub action for RMK commands documentation generation. -- #34 - Added support for Terraform outputs of a boolean type. +- #27 Configured GitHub Pages documentation generation using MkDocs Materials, mike. +- #42 Fixed markdown headers in rmk doc generate command. diff --git a/main.go b/main.go index 0335397..e45db71 100644 --- a/main.go +++ b/main.go @@ -10,6 +10,7 @@ import ( "rmk/commands" "rmk/logger" + "rmk/system" ) var ( @@ -39,6 +40,8 @@ GLOBAL OPTIONS: GLOBAL OPTIONS: ` + output + `{{range $index, $option := .VisibleFlags}}{{if eq $option.Name "help"}}{{" "}}{{$option}}{{end}}{{end}} ` + + cli.MarkdownDocTemplate = system.CustomMarkdownDocTemplate } func runCLI() *cli.App { diff --git a/system/dictionary.go b/system/dictionary.go index b33e428..46a8525 100644 --- a/system/dictionary.go +++ b/system/dictionary.go @@ -87,4 +87,37 @@ _cli_zsh_autocomplete() { } compdef _cli_zsh_autocomplete $PROG` + + CustomMarkdownDocTemplate = `{{if gt .SectionNum 0}}% {{ .App.Name }} {{ .SectionNum }} + +{{end}}# NAME + +{{ .App.Name }}{{ if .App.Usage }} - {{ .App.Usage }}{{ end }} + +## SYNOPSIS + +{{ .App.Name }} +{{ if .SynopsisArgs }} +` + "```" + ` +{{ range $v := .SynopsisArgs }}{{ $v }}{{ end }}` + "```" + ` +{{ end }}{{ if .App.Description }} +## DESCRIPTION + +{{ .App.Description }} +{{ end }} +**Usage**: + +` + "```" + `{{ if .App.UsageText }} +{{ .App.UsageText }} +{{ else }} +{{ .App.Name }} [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] +{{ end }}` + "```" + ` +{{ if .GlobalArgs }} +## GLOBAL OPTIONS +{{ range $v := .GlobalArgs }} +{{ $v }}{{ end }} +{{ end }}{{ if .Commands }} +## COMMANDS +{{ range $v := .Commands }} +#{{ $v }}{{ end }}{{ end }}` ) From 75535030e6560c084af06436c34b22ab12fa2446 Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Mon, 2 Sep 2024 15:34:22 +0200 Subject: [PATCH 13/29] #27 - Remove offline artifact mode from documentation and code. --- README.md | 4 ++-- commands/flags.go | 2 +- commands/project_generation_category.go | 2 +- docs/README.md | 4 +--- docs/commands.md | 4 ++-- docs/configuration/configuration-management.md | 3 +-- 6 files changed, 8 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 09e7a95..634b926 100644 --- a/README.md +++ b/README.md @@ -190,8 +190,8 @@ Among the providers are: - **Guidelines for contributors:** Create comprehensive guidelines for contributors, including instructions for creating pull requests (PRs). - **Integration with Helmfile [vals](https://github.com/helmfile/vals)**: Integrate RMK with the **vals** tool for enhanced values and secret management. - **Major update of the AWS [EKS](https://aws.amazon.com/eks/) cluster provider:** Update the AWS EKS cluster provider to the latest versions to utilize all the supported features of the [Terraform](https://www.terraform.io/) CLI and modules. -- **Implementation of additional RMK cluster providers:** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. -- **Offline artifact mode:** Implement the **offline** artifact mode to install artifacts in fully isolated offline environments. +- **Implementation of additional Terraform-based RMK cluster providers:** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. using [Terraform](https://www.terraform.io/). +- **Implementation of additional Kubernetes Cluster API-based RMK cluster providers:** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. using [Kubernetes Cluster API](https://cluster-api.sigs.k8s.io/introduction). - **Web documentation generator:** Add an HTML documentation generator based on the **.md** files. - **Automatic testing of RMK during the CI/CD pipeline:** Ensure that changes to the RMK codebase do not introduce errors or regressions during the CI/CD. diff --git a/commands/flags.go b/commands/flags.go index e875706..b4f385d 100644 --- a/commands/flags.go +++ b/commands/flags.go @@ -13,7 +13,7 @@ func flagsConfig() []cli.Flag { altsrc.NewStringFlag( &cli.StringFlag{ Name: "artifact-mode", - Usage: "choice of artifact usage model, available: none, online, offline", + Usage: "choice of artifact usage model, available: none, online", Aliases: []string{"am"}, EnvVars: []string{"RMK_ARTIFACT_MODE"}, Value: system.ArtifactModeDefault, diff --git a/commands/project_generation_category.go b/commands/project_generation_category.go index 0b7ffee..cfb8a96 100644 --- a/commands/project_generation_category.go +++ b/commands/project_generation_category.go @@ -201,7 +201,7 @@ develop ------> staging ------> production release/vN.N.N-rc release/vN.N.N ` + "```" + ` -### Generating the Project Structure +### Generating project structure > Note: The generated project structure using the RMK tools is mandatory and is required for the interaction of the RMK with the code base. > All generated files have example content and can be supplemented according to project requirements. diff --git a/docs/README.md b/docs/README.md index b641b11..b503fb4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -165,8 +165,7 @@ rmk update --version vX.X.X to update release and service version declarations, automatically commit the changes to Git. - **[Project structure generation:](configuration/project-management/preparation-of-project-repository.md#automatic-generation-of-the-project-structure-from-scratch)** Generate a complete Kubernetes-based project structure from scratch using RMK, following the best practices. - **[Documentation generation:](commands.md#doc)** Generate the full command documentation in the Markdown format with one click. -- **[Support for different types of code sources:](configuration/configuration-management.md#use-upstream-artifact-for-the-downstream-projects-repository)** Use Git when the _artifact-mode_ is _none_, S3 when the _artifact-mode_ is _online_, - switch to fully offline installations when the _artifact-mode_ is _offline_. +- **[Support for different types of code sources:](configuration/configuration-management.md#use-upstream-artifact-for-the-downstream-projects-repository)** Use Git when the _artifact-mode_ is _none_, S3 when the _artifact-mode_ is _online_. ## Supported Kubernetes providers @@ -191,7 +190,6 @@ Among the providers are: - **Integration with Helmfile [vals](https://github.com/helmfile/vals)**: Integrate RMK with the **vals** tool for enhanced values and secret management. - **Major update of the AWS [EKS](https://aws.amazon.com/eks/) cluster provider:** Update the AWS EKS cluster provider to the latest versions to utilize all the supported features of the [Terraform](https://www.terraform.io/) CLI and modules. - **Implementation of additional RMK cluster providers:** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. -- **Offline artifact mode:** Implement the **offline** artifact mode to install artifacts in fully isolated offline environments. - **Web documentation generator:** Add an HTML documentation generator based on the **.md** files. - **Automatic testing of RMK during the CI/CD pipeline:** Ensure that changes to the RMK codebase do not introduce errors or regressions during the CI/CD. diff --git a/docs/commands.md b/docs/commands.md index 8e0ac43..451648e 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -144,7 +144,7 @@ Configuration management Initialize configuration for current tenant and selected environment -**--artifact-mode, --am**="": choice of artifact usage model, available: none, online, offline (default: "none") +**--artifact-mode, --am**="": choice of artifact usage model, available: none, online (default: "none") **--aws-ecr-host, --aeh**="": AWS ECR host (default: "288509344804.dkr.ecr.eu-north-1.amazonaws.com") @@ -154,7 +154,7 @@ Initialize configuration for current tenant and selected environment **--aws-reconfigure, -r**: force AWS profile creation -**--aws-reconfigure-artifact-license, -l**: force AWS profile creation for artifact license, used only if RMK config option artifact-mode has values: online, offline +**--aws-reconfigure-artifact-license, -l**: force AWS profile creation for artifact license, used only if RMK config option artifact-mode has the values: online **--cloudflare-token, --cft**="": Cloudflare API token for provision NS records diff --git a/docs/configuration/configuration-management.md b/docs/configuration/configuration-management.md index 3cd0613..70c2a98 100644 --- a/docs/configuration/configuration-management.md +++ b/docs/configuration/configuration-management.md @@ -129,7 +129,7 @@ project: Set the `version` field to the version of the upstream project for the current project. For example: ```shell -# artifact usage modes: none|online|offline (default: "none") +# artifact usage modes: none|online (default: "none") rmk config init --artifact-mode=online ``` @@ -140,7 +140,6 @@ rmk config init --artifact-mode=online > - `online`: Switches RMK to work with artifacts. In this mode, RMK will not use any credentials for GitHub > (e.g., personal access tokens), but will request additional license AWS credentials to download and unpack > the artifact from a repository like AWS S3. -> The `offline` mode is currently unsupported and will be implemented in future releases. To change the "license" AWS credentials when in the online artifact mode, use the following command: From 7695de3d4676b177e8dda30e5f9127c72c79b349 Mon Sep 17 00:00:00 2001 From: Aliaksandr Panasiuk Date: Mon, 2 Sep 2024 16:37:25 +0200 Subject: [PATCH 14/29] #42 - refactoring --- main.go | 40 ++++++++++++++++++++++++++++++++++++++-- system/dictionary.go | 33 --------------------------------- 2 files changed, 38 insertions(+), 35 deletions(-) diff --git a/main.go b/main.go index e45db71..43b93f6 100644 --- a/main.go +++ b/main.go @@ -4,13 +4,13 @@ import ( "fmt" "os" "sort" + "strings" "github.com/urfave/cli/v2" "go.uber.org/zap" "rmk/commands" "rmk/logger" - "rmk/system" ) var ( @@ -41,7 +41,43 @@ GLOBAL OPTIONS: ` + output + `{{range $index, $option := .VisibleFlags}}{{if eq $option.Name "help"}}{{" "}}{{$option}}{{end}}{{end}} ` - cli.MarkdownDocTemplate = system.CustomMarkdownDocTemplate + cli.MarkdownDocTemplate = `{{if gt .SectionNum 0}}% {{ .App.Name }} {{ .SectionNum }} + +{{end}}# NAME + +` + strings.ToUpper(name) + ` CLI{{ if .App.Usage }} - {{ .App.Usage }}{{ end }} + +## SYNOPSIS + +{{ .App.Name }} +{{ if .SynopsisArgs }} +` + "```" + ` +{{ range $v := .SynopsisArgs }}{{ $v }}{{ end }}` + "```" + ` +{{ end }}{{ if .App.Description }} +## DESCRIPTION + +Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. + +**BuiltBy:** ` + builtBy + ` \ +**Commit:** ` + commit + ` \ +**Date:** ` + date + ` \ +**Target:** ` + target + ` +{{ end }} +**Usage**: + +` + "```" + `{{ if .App.UsageText }} +{{ .App.UsageText }} +{{ else }} +{{ .App.Name }} [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] +{{ end }}` + "```" + ` +{{ if .GlobalArgs }} +## GLOBAL OPTIONS +{{ range $v := .GlobalArgs }} +{{ $v }}{{ end }} +{{ end }}{{ if .Commands }} +## COMMANDS +{{ range $v := .Commands }} +#{{ $v }}{{ end }}{{ end }}` } func runCLI() *cli.App { diff --git a/system/dictionary.go b/system/dictionary.go index 46a8525..b33e428 100644 --- a/system/dictionary.go +++ b/system/dictionary.go @@ -87,37 +87,4 @@ _cli_zsh_autocomplete() { } compdef _cli_zsh_autocomplete $PROG` - - CustomMarkdownDocTemplate = `{{if gt .SectionNum 0}}% {{ .App.Name }} {{ .SectionNum }} - -{{end}}# NAME - -{{ .App.Name }}{{ if .App.Usage }} - {{ .App.Usage }}{{ end }} - -## SYNOPSIS - -{{ .App.Name }} -{{ if .SynopsisArgs }} -` + "```" + ` -{{ range $v := .SynopsisArgs }}{{ $v }}{{ end }}` + "```" + ` -{{ end }}{{ if .App.Description }} -## DESCRIPTION - -{{ .App.Description }} -{{ end }} -**Usage**: - -` + "```" + `{{ if .App.UsageText }} -{{ .App.UsageText }} -{{ else }} -{{ .App.Name }} [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] -{{ end }}` + "```" + ` -{{ if .GlobalArgs }} -## GLOBAL OPTIONS -{{ range $v := .GlobalArgs }} -{{ $v }}{{ end }} -{{ end }}{{ if .Commands }} -## COMMANDS -{{ range $v := .Commands }} -#{{ $v }}{{ end }}{{ end }}` ) From 455acd045b6234415f839b6094fad5438e52480b Mon Sep 17 00:00:00 2001 From: Aliaksandr Panasiuk Date: Mon, 2 Sep 2024 16:42:52 +0200 Subject: [PATCH 15/29] #42 - refactoring --- docs/release-notes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/release-notes.md b/docs/release-notes.md index ca81488..d45832e 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,2 +1,2 @@ -- #27 Configured GitHub Pages documentation generation using MkDocs Materials, mike. -- #42 Fixed markdown headers in rmk doc generate command. +- #27 - Configured GitHub Pages documentation generation using MkDocs Materials, mike. +- #42 - Fixed markdown headers in rmk doc generate command. From 56d25b2ebbe962767215383adbf17d53fbb0fd17 Mon Sep 17 00:00:00 2001 From: github-actions Date: Mon, 2 Sep 2024 14:46:06 +0000 Subject: [PATCH 16/29] [skip ci] Update commands documentation --- docs/commands.md | 131 ++++++++++++++++++++++++----------------------- 1 file changed, 66 insertions(+), 65 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 4d5aab8..09abede 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,8 +1,8 @@ # NAME -rmk - Reduced management for Kubernetes +RMK CLI - Reduced management for Kubernetes -# SYNOPSIS +## SYNOPSIS rmk @@ -13,13 +13,14 @@ rmk [--version|-v] ``` -# DESCRIPTION +## DESCRIPTION Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. -BuiltBy: goreleaser -Commit: 9d85b2c -Date: 2024-07-25T14:59:40Z -Target: linux_amd64 + +**BuiltBy:** goreleaser \ +**Commit:** edbe501 \ +**Date:** 2024-09-02T14:44:39Z \ +**Target:** linux_amd64 **Usage**: @@ -27,7 +28,7 @@ Target: linux_amd64 rmk [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] ``` -# GLOBAL OPTIONS +## GLOBAL OPTIONS **--help, -h**: show help @@ -38,109 +39,109 @@ rmk [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] **--version, -v**: print the version -# COMMANDS +## COMMANDS -## cluster +### cluster Cluster management -### container-registry, c +#### container-registry, c Container registry management -#### login +##### login Log in to container registry **--get-token, -g**: get ECR token for authentication -#### logout +##### logout Log out from container registry -### destroy, d +#### destroy, d Destroy AWS cluster using Terraform -### list, l +#### list, l List all Terraform available workspaces -### k3d, k +#### k3d, k K3D cluster management -#### create, c +##### create, c Create K3D cluster **--k3d-volume-host-path, --kv**="": host local directory path for mount into K3D cluster (default: present working directory) -#### delete, d +##### delete, d Delete K3D cluster -#### import, i +##### import, i Import images from docker to K3D cluster **--k3d-import-image, --ki**="": list images for import into K3D cluster -#### list, l +##### list, l List K3D clusters -#### start, s +##### start, s Start K3D cluster -#### stop +##### stop Stop K3D cluster -### provision, p +#### provision, p Provision AWS cluster using Terraform **--plan, -p**: creates an execution Terraform plan -### state, t +#### state, t State cluster management using Terraform -#### delete, d +##### delete, d Delete resource from Terraform state **--resource-address, --ra**="": resource address for delete from Terraform state -#### list, l +##### list, l List resources from Terraform state -#### refresh, r +##### refresh, r Update state file for AWS cluster using Terraform -### switch, s +#### switch, s Switch Kubernetes context for tenant cluster **--force, -f**: force update Kubernetes context from remote cluster -## completion +### completion Completion management -### zsh, z +#### zsh, z View Zsh completion scripts -## config +### config Configuration management -### init, i +#### init, i Initialize configuration for current tenant and selected environment @@ -180,51 +181,51 @@ Initialize configuration for current tenant and selected environment **--slack-webhook, --sw**="": URL for Slack webhook -### delete, d +#### delete, d Delete configuration for selected environment -### list, l +#### list, l List available configurations for current tenant **--all, -a**: list all tenant configurations -### view, v +#### view, v View configuration for selected environment -## doc +### doc Documentation management **--help, -h**: show help -### generate, g +#### generate, g Generate documentation by commands and flags in Markdown format **--help, -h**: show help -#### help, h +##### help, h Shows a list of commands or help for one command -### help, h +#### help, h Shows a list of commands or help for one command -## project +### project Project management -### generate, g +#### generate, g Generate project directories and files structure **--create-sops-age-keys, -c**: create SOPS age keys for generated project structure -### update, u +#### update, u Update project file with specific dependencies version @@ -236,11 +237,11 @@ Update project file with specific dependencies version **--version, -v**="": specific dependency version for updating project file -## release +### release Release components list from state file (Helmfile) -### build, b +#### build, b Build releases @@ -252,7 +253,7 @@ Build releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### destroy, d +#### destroy, d Destroy releases @@ -266,7 +267,7 @@ Destroy releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### list, l +#### list, l List releases @@ -280,7 +281,7 @@ List releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### rollback, r +#### rollback, r Rollback specific releases to latest stable state @@ -288,7 +289,7 @@ Rollback specific releases to latest stable state **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### sync, s +#### sync, s Sync releases @@ -300,7 +301,7 @@ Sync releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### template, t +#### template, t Template releases @@ -312,7 +313,7 @@ Template releases **--skip-context-switch, -s**: skip context switch for not provisioned cluster -### update, u +#### update, u Update releases file with specific environment values @@ -328,15 +329,15 @@ Update releases file with specific environment values **--tag, -t**="": specific tag for updating releases file -## secret +### secret secrets management -### manager, m +#### manager, m batch secrets management -#### decrypt, d +##### decrypt, d Decrypt secrets batch for selected scope and environment @@ -344,7 +345,7 @@ Decrypt secrets batch for selected scope and environment **--scope, -s**="": specific scopes for selected secrets -#### encrypt, e +##### encrypt, e Encrypt secrets batch for selected scope and environment @@ -352,7 +353,7 @@ Encrypt secrets batch for selected scope and environment **--scope, -s**="": specific scopes for selected secrets -#### generate, g +##### generate, g Generate secrets batch for selected scope and environment @@ -362,39 +363,39 @@ Generate secrets batch for selected scope and environment **--scope, -s**="": specific scopes for selected secrets -### keys, k +#### keys, k SOPS age keys management -#### create, c +##### create, c Create SOPS age keys -#### download, d +##### download, d Download SOPS age keys from S3 bucket -#### upload, u +##### upload, u Upload SOPS age keys to S3 bucket -### encrypt, e +#### encrypt, e Encrypt secret file -### decrypt, d +#### decrypt, d Decrypt secret file -### view, v +#### view, v View secret file -### edit +#### edit Edit secret file -## update +### update Update RMK CLI to a new version @@ -402,7 +403,7 @@ Update RMK CLI to a new version **--version, -v**="": RMK special version. (default: empty value corresponds latest version) -## help, h +### help, h Shows a list of commands or help for one command From b686ea682a2fc71375d6d3398f7db22d9215cf3c Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Tue, 3 Sep 2024 12:46:48 +0200 Subject: [PATCH 17/29] #27 - Rename development guidelines file to development-and-release-flows.md. Strip the main README.md, rename the main web documentation file to index.md. --- README.md | 128 +----------------- docs/.pages | 4 +- ...ow.md => development-and-release-flows.md} | 0 docs/{README.md => index.md} | 15 +- docs/quickstart.md | 6 +- 5 files changed, 20 insertions(+), 133 deletions(-) rename docs/{development-and-release-flow.md => development-and-release-flows.md} (100%) rename docs/{README.md => index.md} (94%) diff --git a/README.md b/README.md index 634b926..4bd9886 100644 --- a/README.md +++ b/README.md @@ -6,34 +6,7 @@ Command line tool for reduced management and provisioning of Kubernetes clusters and environments, Helm secrets and releases. -* [RMK CLI - Reduced Management for Kubernetes](#rmk-cli---reduced-management-for-kubernetes) - * [Overview](#overview) - * [Advantages](#advantages) - * [Edenlab LLC use cases](#edenlab-llc-use-cases) - * [Related OSS repositories](#related-oss-repositories) - * [Requirements](#requirements) - * [Quickstart](docs/quickstart.md) - * [Installation](#installation) - * [Update](#update) - * [General update process](#general-update-process) - * [Update to specific version](#update-to-specific-version) - * Configuration - * [Configuration management](docs/configuration/configuration-management.md) - * Project management - * [Requirement for project repository](docs/configuration/project-management/requirement-for-project-repository.md) - * [Preparation of project repository](docs/configuration/project-management/preparation-of-project-repository.md) - * [Dependencies management and Project inheritance](docs/configuration/project-management/dependencies-management-and-project-inheritance.md) - * [Cluster management](docs/configuration/cluster-management/cluster-management.md) - * [Exported environment variables](docs/configuration/cluster-management/exported-environment-variables.md) - * [Release management](docs/configuration/release-management/release-management.md) - * [Secrets management](docs/configuration/secrets-management/secrets-management.md) - * [Commands](docs/commands.md) - * [Development and release flow](docs/development-and-release-flow.md) - * [Features](#features) - * [Supported Kubernetes providers](#supported-kubernetes-providers) - * [Roadmap](#roadmap) - * [License](#license) - * [Code of Conduct](#code-of-conduct) +Full documentation is available at https://edenlabllc.github.io/rmk/latest/ ## Overview @@ -84,118 +57,31 @@ A classic Kodjin installation uses 3-level inheritance: The additional components used by Kodjin are: -- **\*.provisioner.infra:** Repositories for Kubernetes cluster provisioning. +- **\*.provisioner.infra:** RMK cluster provider repositories for Kubernetes cluster provisioning. - **helmfile.hooks.infra:** Shell scrips used as [Helmfile hooks](https://helmfile.readthedocs.io/en/latest/#hooks) in deps/Kodjin/any other tenant. - **core.charts.infra:** Helm charts used by the Kodjin services. -The examples of Kubernetes providers, to which Kodjin has been installed, are: +The examples of Kubernetes providers, to which Kodjin has been installed already, are: - [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) +- [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/products/kubernetes-service/) - [Open Telekom Cloud - Cloud Container Engine (CCE)](https://www.open-telekom-cloud.com/en/products-services/core-services/cloud-container-engine) - [Rancher Kubernetes Platform](https://www.rancher.com/) - [Kubermatic Kubernetes Platform (KKP)](https://www.kubermatic.com/) - on-premise installations deployed using [Ansible Kubespray](https://github.com/kubernetes-sigs/kubespray) - single-machine [K3D](https://k3d.io/) clusters -#### Related OSS repositories +### Related OSS repositories - [AWS cluster provider for RMK](https://github.com/edenlabllc/aws.provisioner.infra) - [Azure cluster provider for RMK](https://github.com/edenlabllc/azure.provisioner.infra) - [K3D cluster provider for RMK](https://github.com/edenlabllc/k3d.provisioner.infra) - [Helmfile hooks](https://github.com/edenlabllc/helmfile.hooks.infra) -## Requirements - -Currently, RMK only supports Unix-like operating systems (OS): - -- **OS:** - - **MacOS**: amd64, arm64 (M1, M2 require [Rosetta](https://support.apple.com/en-us/HT211861)) - - **Linux**: amd64 -- **Software:** - - **Python** >= 3.9 - - **[AWS CLI](https://aws.amazon.com/cli/)** - - _For managing local clusters using K3D:_ Version _v5.x.x_ requires [Docker](https://www.docker.com/) => v20.10.5 ([runc](https://github.com/opencontainers/runc) >= v1.0.0-rc93) to work - properly. - -> If this is your first project repository managed by RMK, ensure that the above tools are specified in the [project.yaml](docs/configuration/project-management/preparation-of-project-repository.md#projectyaml) file. - -## Installation - -To install RMK, run the self-installer script using the following command: - -```shell -curl -sL "https://edenlabllc-rmk.s3.eu-north-1.amazonaws.com/rmk/s3-installer" | bash -``` - -Alternatively, you can go directly to https://github.com/edenlabllc/rmk/releases and download the binary. - -As another option, the binary can be [built from source](docs/development-and-release-flow.md#building-from-source). - -## Update - -### General update process - -To update RMK to the latest version, run the following command: - -```shell -rmk update -``` - -### Update to specific version - -You can update to a specific RMK version to maintain backward compatibility or when updating to the latest version is not possible. -> This may be necessary due to specific version requirements or when a bug has been detected. - -To update to a specific version, use the following command: - -```shell -rmk update --version vX.X.X -``` - -## Features - -- **[Reduced and simplified management of Kubernetes projects:](#overview)** Deploy to Kubernetes using Helmfile/Helm, use popular DevOps tools together in a single CI/CD pipeline. -- **[Time-proven project structure:](docs/configuration/project-management/preparation-of-project-repository.md)** Define the project structure using the [GitLabFlow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) methodology. -- **[Hierarchies between different projects:](docs/configuration/project-management/dependencies-management-and-project-inheritance.md)** Define upstream-downstream relationships between sibling projects to reuse releases and services across different installations. -- **[Batch secret management:](docs/configuration/secrets-management/secrets-management.md#generating-all-secrets-from-scratch-in-a-batch-manner-using-the-rmk-secrets-manager)** Template, generate, and encode project secrets for all environments in a batch manner. -- **[Clone environments with one click:](docs/configuration/configuration-management.md#initialization-of-rmk-configuration-for-feature-or-release-clusters)** Use the special `--config-from-environment` (`--cfe`) flag to create an environment based on an existing one. -- **[Automatic detection of Multi-Factor Authentication](docs/configuration/configuration-management.md#support-for-multi-factor-authentication-mfa) ([MFA](https://en.wikipedia.org/wiki/Multi-factor_authentication)):** Automatically detect and use an MFA device if one is defined by an [IAM](https://aws.amazon.com/iam/) user (must be supported by the cluster provider, e.g., [AWS](https://aws.amazon.com/)). -- **[Push-based release and downstream project updates:](docs/configuration/release-management/release-management.md#release-update-and-integration-into-the-cd-pipeline)** Easily integrate with CI/CD solutions via webhooks or workflow dispatch events - to update release and service version declarations, automatically commit the changes to Git. -- **[Project structure generation:](docs/configuration/project-management/preparation-of-project-repository.md#automatic-generation-of-the-project-structure-from-scratch)** Generate a complete Kubernetes-based project structure from scratch using RMK, following the best practices. -- **[Documentation generation:](docs/commands.md#doc)** Generate the full command documentation in the Markdown format with one click. -- **[Support for different types of code sources:](docs/configuration/configuration-management.md#use-upstream-artifact-for-the-downstream-projects-repository)** Use Git when the _artifact-mode_ is _none_, S3 when the _artifact-mode_ is _online_, - switch to fully offline installations when the _artifact-mode_ is _offline_. - -## Supported Kubernetes providers - -By design, RMK can work with any Kubernetes provider. - -Among the providers are: - -- [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) -- [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) -- [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/products/kubernetes-service/) -- [Red Hat OpenShift](https://redhat.com/en/technologies/cloud-computing/openshift) -- [VMware Tanzu Kubernetes Grid](https://tanzu.vmware.com/kubernetes-grid) -- [Rancher Kubernetes Platform](https://www.rancher.com/) -- [Open Telekom Cloud - Cloud Container Engine (CCE)](https://www.open-telekom-cloud.com/en/products-services/core-services/cloud-container-engine) -- [Kubermatic Kubernetes Platform (KKP)](https://www.kubermatic.com/) -- on-premise installations deployed using [Ansible Kubespray](https://github.com/kubernetes-sigs/kubespray) -- single-machine [K3D](https://k3d.io/) clusters - -## Roadmap - -- **Guidelines for contributors:** Create comprehensive guidelines for contributors, including instructions for creating pull requests (PRs). -- **Integration with Helmfile [vals](https://github.com/helmfile/vals)**: Integrate RMK with the **vals** tool for enhanced values and secret management. -- **Major update of the AWS [EKS](https://aws.amazon.com/eks/) cluster provider:** Update the AWS EKS cluster provider to the latest versions to utilize all the supported features of the [Terraform](https://www.terraform.io/) CLI and modules. -- **Implementation of additional Terraform-based RMK cluster providers:** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. using [Terraform](https://www.terraform.io/). -- **Implementation of additional Kubernetes Cluster API-based RMK cluster providers:** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. using [Kubernetes Cluster API](https://cluster-api.sigs.k8s.io/introduction). -- **Web documentation generator:** Add an HTML documentation generator based on the **.md** files. -- **Automatic testing of RMK during the CI/CD pipeline:** Ensure that changes to the RMK codebase do not introduce errors or regressions during the CI/CD. +## Development -Check the [issues](https://github.com/edenlabllc/rmk/issues) for more information. +The guidelines are available at https://edenlabllc.github.io/rmk/latest/https://edenlabllc.github.io/rmk/latest/development-and-release-flows/ ## License diff --git a/docs/.pages b/docs/.pages index 9854473..3964471 100644 --- a/docs/.pages +++ b/docs/.pages @@ -1,7 +1,7 @@ nav: - - Overview: README.md + - Overview: index.md - quickstart.md - Configuration and management: configuration - Commands: commands.md - - development-and-release-flow.md + - development-and-release-flows.md collapse: false diff --git a/docs/development-and-release-flow.md b/docs/development-and-release-flows.md similarity index 100% rename from docs/development-and-release-flow.md rename to docs/development-and-release-flows.md diff --git a/docs/README.md b/docs/index.md similarity index 94% rename from docs/README.md rename to docs/index.md index b503fb4..cffb3a1 100644 --- a/docs/README.md +++ b/docs/index.md @@ -28,7 +28,7 @@ Command line tool for reduced management and provisioning of Kubernetes clusters * [Release management](configuration/release-management/release-management.md) * [Secrets management](configuration/secrets-management/secrets-management.md) * [Commands](commands.md) - * [Development and release flow](development-and-release-flow.md) + * [Development and release flows](development-and-release-flows.md) * [Features](#features) * [Supported Kubernetes providers](#supported-kubernetes-providers) * [Roadmap](#roadmap) @@ -84,21 +84,22 @@ A classic Kodjin installation uses 3-level inheritance: The additional components used by Kodjin are: -- **\*.provisioner.infra:** Repositories for Kubernetes cluster provisioning. +- **\*.provisioner.infra:** RMK cluster provider repositories for Kubernetes cluster provisioning. - **helmfile.hooks.infra:** Shell scrips used as [Helmfile hooks](https://helmfile.readthedocs.io/en/latest/#hooks) in deps/Kodjin/any other tenant. - **core.charts.infra:** Helm charts used by the Kodjin services. -The examples of Kubernetes providers, to which Kodjin has been installed, are: +The examples of Kubernetes providers, to which Kodjin has been installed already, are: - [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) +- [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/products/kubernetes-service/) - [Open Telekom Cloud - Cloud Container Engine (CCE)](https://www.open-telekom-cloud.com/en/products-services/core-services/cloud-container-engine) - [Rancher Kubernetes Platform](https://www.rancher.com/) - [Kubermatic Kubernetes Platform (KKP)](https://www.kubermatic.com/) - on-premise installations deployed using [Ansible Kubespray](https://github.com/kubernetes-sigs/kubespray) - single-machine [K3D](https://k3d.io/) clusters -#### Related OSS repositories +### Related OSS repositories - [AWS cluster provider for RMK](https://github.com/edenlabllc/aws.provisioner.infra) - [Azure cluster provider for RMK](https://github.com/edenlabllc/azure.provisioner.infra) @@ -130,7 +131,7 @@ curl -sL "https://edenlabllc-rmk.s3.eu-north-1.amazonaws.com/rmk/s3-installer" | Alternatively, you can go directly to https://github.com/edenlabllc/rmk/releases and download the binary. -As another option, the binary can be [built from source](development-and-release-flow.md#building-from-source). +As another option, the binary can be [built from source](development-and-release-flows.md#building-from-source). ## Update @@ -174,8 +175,8 @@ By design, RMK can work with any Kubernetes provider. Among the providers are: - [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/) -- [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) - [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/products/kubernetes-service/) +- [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) - [Red Hat OpenShift](https://redhat.com/en/technologies/cloud-computing/openshift) - [VMware Tanzu Kubernetes Grid](https://tanzu.vmware.com/kubernetes-grid) - [Rancher Kubernetes Platform](https://www.rancher.com/) @@ -189,7 +190,7 @@ Among the providers are: - **Guidelines for contributors:** Create comprehensive guidelines for contributors, including instructions for creating pull requests (PRs). - **Integration with Helmfile [vals](https://github.com/helmfile/vals)**: Integrate RMK with the **vals** tool for enhanced values and secret management. - **Major update of the AWS [EKS](https://aws.amazon.com/eks/) cluster provider:** Update the AWS EKS cluster provider to the latest versions to utilize all the supported features of the [Terraform](https://www.terraform.io/) CLI and modules. -- **Implementation of additional RMK cluster providers:** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. +- **Implementation of additional RMK cluster providers using [Kubernetes Cluster API](https://cluster-api.sigs.k8s.io/):** Implement support for additional cluster providers for popular Kubernetes services such as [GKE](https://cloud.google.com/kubernetes-engine), [AKS](https://azure.microsoft.com/en-us/products/kubernetes-service/), etc. - **Web documentation generator:** Add an HTML documentation generator based on the **.md** files. - **Automatic testing of RMK during the CI/CD pipeline:** Ensure that changes to the RMK codebase do not introduce errors or regressions during the CI/CD. diff --git a/docs/quickstart.md b/docs/quickstart.md index 75a0217..60dacc1 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -7,8 +7,8 @@ create a local cluster based on `K3D`, deploy your first application ([Nginx](ht > > - An active AWS user with access keys and the `AdministratorAccess` permissions. > - A prepared [project repository](configuration/project-management/preparation-of-project-repository.md#preparation-of-the-project-repository) -> - Installed [RMK](README.md#installation) -> - The fulfilled [requirements](README.md#requirements) for proper RMK operation. +> - Installed [RMK](index.md#installation) +> - The fulfilled [requirements](index.md#requirements) for proper RMK operation. 0. Create a [project.yaml](configuration/project-management/preparation-of-project-repository.md#projectyaml) file in the root of the project repository with the following content: @@ -104,7 +104,7 @@ inventory: 3. Create a local K3D cluster: - > Before running this step, ensure that Docker is installed in the system according to the [requirements](README.md#requirements). + > Before running this step, ensure that Docker is installed in the system according to the [requirements](index.md#requirements). ```shell rmk cluster k3d create From 67e5099b7de41f78608797653e0ff551eb5d63fd Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Tue, 3 Sep 2024 13:38:21 +0200 Subject: [PATCH 18/29] #27 - Improve release-management.md flags description. --- .../configuration/release-management/release-management.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/configuration/release-management/release-management.md b/docs/configuration/release-management/release-management.md index 3c217d9..000990a 100644 --- a/docs/configuration/release-management/release-management.md +++ b/docs/configuration/release-management/release-management.md @@ -9,11 +9,16 @@ Additionally, flags are provided for the commands, which allow extending capabil For example: ```shell -rmk release build --selector app=name +rmk release build +rmk release list --selector app=name +rmk release template --selector app=name --skip-context-switch rmk release sync --helmfile-log-level=debug --selector app=name rmk release destroy ``` +> The `--skip-context-switch` (`-s`) flag can be used for the commands like `rmk release template` to skip switching to a Kubernetes cluster. +> This might be useful in the situations, when a cluster has not been provisioned yet and its releases and values are being developed. + In a project repository, all the release values files are stored in the `etc///values/` directories. For example: From 3598e56bfd7f9097a16cdde42fc58c4ea47d8b2e Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 12:48:29 +0000 Subject: [PATCH 19/29] [skip ci] Update commands documentation --- docs/commands.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 43e4956..3e13b83 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,8 +18,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. **BuiltBy:** goreleaser \ -**Commit:** edbe501 \ -**Date:** 2024-09-02T14:44:39Z \ +**Commit:** 79f9f05 \ +**Date:** 2024-09-03T12:48:24Z \ **Target:** linux_amd64 **Usage**: @@ -155,7 +155,7 @@ Initialize configuration for current tenant and selected environment **--aws-reconfigure, -r**: force AWS profile creation -**--aws-reconfigure-artifact-license, -l**: force AWS profile creation for artifact license, used only if RMK config option artifact-mode has the values: online +**--aws-reconfigure-artifact-license, -l**: force AWS profile creation for artifact license, used only if RMK config option artifact-mode has values: online, offline **--cloudflare-token, --cft**="": Cloudflare API token for provision NS records @@ -406,3 +406,4 @@ Update RMK CLI to a new version ### help, h Shows a list of commands or help for one command + From 03f8918173a1540c9682aa8af7d629ca555367c5 Mon Sep 17 00:00:00 2001 From: Aliaksandr Panasiuk Date: Tue, 3 Sep 2024 16:38:40 +0200 Subject: [PATCH 20/29] #42 - refactoring GitHub workflow --- .github/workflows/docs-commands-generate.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs-commands-generate.yml b/.github/workflows/docs-commands-generate.yml index 918a6db..700200e 100644 --- a/.github/workflows/docs-commands-generate.yml +++ b/.github/workflows/docs-commands-generate.yml @@ -8,6 +8,7 @@ on: jobs: docs-commands-generate: + if: "!contains(github.event.head_commit.message, '[skip ci docs commands generate]')" runs-on: ubuntu-22.04 steps: - name: Checkout @@ -37,7 +38,7 @@ jobs: echo "Generate new commands documentation." ./dist/rmk_linux_amd64_v1/rmk doc generate > ./docs/commands.md - if (git commit --all --message="[skip ci] Update commands documentation"); then + if (git commit --all --message="[skip ci docs commands generate] Update commands documentation"); then git push echo "The new commands documentation has been committed." fi From 56a0f1b7132af6bd7121cc7fff96db4f92a25033 Mon Sep 17 00:00:00 2001 From: Aliaksandr Panasiuk Date: Tue, 3 Sep 2024 16:55:04 +0200 Subject: [PATCH 21/29] #42 - refactoring --- ...-commands-generate.yml => docs-commands-update.yml} | 10 +++++----- .github/workflows/docs-publish.yaml | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) rename .github/workflows/{docs-commands-generate.yml => docs-commands-update.yml} (75%) diff --git a/.github/workflows/docs-commands-generate.yml b/.github/workflows/docs-commands-update.yml similarity index 75% rename from .github/workflows/docs-commands-generate.yml rename to .github/workflows/docs-commands-update.yml index 700200e..959ca29 100644 --- a/.github/workflows/docs-commands-generate.yml +++ b/.github/workflows/docs-commands-update.yml @@ -1,4 +1,4 @@ -name: Generate commands documentation +name: Generate, update commands documentation on: push: @@ -7,8 +7,8 @@ on: - hotfix/* jobs: - docs-commands-generate: - if: "!contains(github.event.head_commit.message, '[skip ci docs commands generate]')" + docs-commands-update: + if: "!contains(github.event.head_commit.message, '[skip docs commands generate]')" runs-on: ubuntu-22.04 steps: - name: Checkout @@ -29,7 +29,7 @@ jobs: version: v1.23.0 args: build --clean --skip=validate - - name: Generate and commit new commands documentation + - name: Update and commit new commands documentation run: | echo "Configure Git user.name and user.email." git config user.name github-actions @@ -38,7 +38,7 @@ jobs: echo "Generate new commands documentation." ./dist/rmk_linux_amd64_v1/rmk doc generate > ./docs/commands.md - if (git commit --all --message="[skip ci docs commands generate] Update commands documentation"); then + if (git commit --all --message="[skip docs commands update] Update commands documentation"); then git push echo "The new commands documentation has been committed." fi diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml index ee0460b..2e2e7f5 100644 --- a/.github/workflows/docs-publish.yaml +++ b/.github/workflows/docs-publish.yaml @@ -12,7 +12,7 @@ on: - 'v[0-9]+.[0-9]+.[0-9]+' jobs: - publish: + docs-publish: name: Build, validate, publish, version documentation for GitHub Pages runs-on: ubuntu-22.04 steps: From 1f9679a6ba54363431692ff3a1bb2785e1dabc9a Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 14:56:52 +0000 Subject: [PATCH 22/29] [skip docs commands update] Update commands documentation --- docs/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 3e13b83..6a4989e 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,8 +18,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. **BuiltBy:** goreleaser \ -**Commit:** 79f9f05 \ -**Date:** 2024-09-03T12:48:24Z \ +**Commit:** 2b37748 \ +**Date:** 2024-09-03T14:56:50Z \ **Target:** linux_amd64 **Usage**: From 44a29bf719b96aaf39275b37e936916b1c36aa28 Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 14:57:20 +0000 Subject: [PATCH 23/29] [skip docs commands update] Update commands documentation --- docs/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 6a4989e..55f1ece 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,8 +18,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. **BuiltBy:** goreleaser \ -**Commit:** 2b37748 \ -**Date:** 2024-09-03T14:56:50Z \ +**Commit:** 1f9679a \ +**Date:** 2024-09-03T14:57:18Z \ **Target:** linux_amd64 **Usage**: From e820e6c8c4c125a58de06cbd9a01cbc8e58a9f0a Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 14:57:57 +0000 Subject: [PATCH 24/29] [skip docs commands update] Update commands documentation --- docs/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 55f1ece..0b49a26 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,8 +18,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. **BuiltBy:** goreleaser \ -**Commit:** 1f9679a \ -**Date:** 2024-09-03T14:57:18Z \ +**Commit:** 44a29bf \ +**Date:** 2024-09-03T14:57:50Z \ **Target:** linux_amd64 **Usage**: From 676a503a61f6754283642a5a3a9df60f03b03bba Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 14:58:24 +0000 Subject: [PATCH 25/29] [skip docs commands update] Update commands documentation --- docs/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 0b49a26..ae832ee 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,8 +18,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. **BuiltBy:** goreleaser \ -**Commit:** 44a29bf \ -**Date:** 2024-09-03T14:57:50Z \ +**Commit:** e820e6c \ +**Date:** 2024-09-03T14:58:18Z \ **Target:** linux_amd64 **Usage**: From 593f2237dec066dbc17d4ed762c5c0fb48627b7f Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 14:58:52 +0000 Subject: [PATCH 26/29] [skip docs commands update] Update commands documentation --- docs/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index ae832ee..9041825 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,8 +18,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. **BuiltBy:** goreleaser \ -**Commit:** e820e6c \ -**Date:** 2024-09-03T14:58:18Z \ +**Commit:** 676a503 \ +**Date:** 2024-09-03T14:58:46Z \ **Target:** linux_amd64 **Usage**: From 217dfc0d56bd0a9453c8b2d00fc93e23b13625c3 Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 14:59:14 +0000 Subject: [PATCH 27/29] [skip docs commands update] Update commands documentation --- docs/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 9041825..3fe4be4 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,8 +18,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. **BuiltBy:** goreleaser \ -**Commit:** 676a503 \ -**Date:** 2024-09-03T14:58:46Z \ +**Commit:** 593f223 \ +**Date:** 2024-09-03T14:59:12Z \ **Target:** linux_amd64 **Usage**: From 2298195f0ace86c5bafeead108662450b6fb3b50 Mon Sep 17 00:00:00 2001 From: Aliaksandr Panasiuk Date: Tue, 3 Sep 2024 17:01:24 +0200 Subject: [PATCH 28/29] #42 - refactoring --- .github/workflows/docs-commands-update.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs-commands-update.yml b/.github/workflows/docs-commands-update.yml index 959ca29..16f3a76 100644 --- a/.github/workflows/docs-commands-update.yml +++ b/.github/workflows/docs-commands-update.yml @@ -8,7 +8,7 @@ on: jobs: docs-commands-update: - if: "!contains(github.event.head_commit.message, '[skip docs commands generate]')" + if: "!contains(github.event.head_commit.message, '[skip docs commands update]')" runs-on: ubuntu-22.04 steps: - name: Checkout From 64db9982372cfe6d66a568856605330064d67daf Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 3 Sep 2024 15:03:17 +0000 Subject: [PATCH 29/29] [skip docs commands update] Update commands documentation --- docs/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 3fe4be4..ae828f9 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -18,8 +18,8 @@ rmk Command line tool for reduced management of the provision of Kubernetes clusters in different environments and management of service releases. **BuiltBy:** goreleaser \ -**Commit:** 593f223 \ -**Date:** 2024-09-03T14:59:12Z \ +**Commit:** 25e5886 \ +**Date:** 2024-09-03T15:03:12Z \ **Target:** linux_amd64 **Usage**: