Skip to content

Commit

Permalink
Merge pull request #44 from edenlabllc/release/v0.44.0
Browse files Browse the repository at this point in the history
Release/v0.44.0
  • Loading branch information
anovikov-el authored Sep 3, 2024
2 parents f670a9d + 64db998 commit eb8eba5
Show file tree
Hide file tree
Showing 25 changed files with 572 additions and 246 deletions.
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Generate commands documentation
name: Generate, update commands documentation

on:
push:
Expand All @@ -7,7 +7,8 @@ on:
- hotfix/*

jobs:
docs-commands-generate:
docs-commands-update:
if: "!contains(github.event.head_commit.message, '[skip docs commands update]')"
runs-on: ubuntu-22.04
steps:
- name: Checkout
Expand All @@ -28,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
Expand All @@ -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 docs commands update] Update commands documentation"); then
git push
echo "The new commands documentation has been committed."
fi
41 changes: 41 additions & 0 deletions .github/workflows/docs-publish.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
name: Build, validate, publish, version documentation for GitHub Pages

on:
push:
branches:
- master
- develop
- feature/*
- release/*
- hotfix/*
tags:
- 'v[0-9]+.[0-9]+.[0-9]+'

jobs:
docs-publish:
name: Build, validate, publish, version documentation for GitHub Pages
runs-on: ubuntu-22.04
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: |
mkdocs build --verbose --clean --strict
rm -r site/
- 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 [email protected]
VERSION=${GITHUB_REF#refs/tags/}
mike deploy --update-aliases --push --rebase "${VERSION}" latest
1 change: 1 addition & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ env:

jobs:
goreleaser:
name: Release RMK using GoReleaser
runs-on: ubuntu-22.04
steps:
- name: Checkout
Expand Down
138 changes: 18 additions & 120 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,12 @@
# 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.

* [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
* [RMK configuration management](docs/configuration/rmk-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)
Full documentation is available at https://edenlabllc.github.io/rmk/latest/

## Overview

Expand All @@ -55,6 +29,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.
Expand All @@ -74,123 +49,46 @@ 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.

- **\*.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.
## Development

To update to a specific version, use the following command:
The guidelines are available at https://edenlabllc.github.io/rmk/latest/https://edenlabllc.github.io/rmk/latest/development-and-release-flows/

```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/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/)).
- **[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_,
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.
## License

Check the [issues](https://github.com/edenlabllc/rmk/issues) for more information.
RMK is open source software (OSS) licensed under the [Apache 2.0 License](https://github.com/edenlabllc/rmk/blob/master/LICENSE).

## License
## Code of Conduct

RMK is open source software (OSS) licensed under the [Apache 2.0 License](LICENSE).
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/master/docs/CONTRIBUTING.md) for further information.
2 changes: 1 addition & 1 deletion commands/flags.go
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion commands/project_generation_category.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
7 changes: 7 additions & 0 deletions docs/.pages
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
nav:
- Overview: index.md
- quickstart.md
- Configuration and management: configuration
- Commands: commands.md
- development-and-release-flows.md
collapse: false
2 changes: 1 addition & 1 deletion docs/CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading

0 comments on commit eb8eba5

Please sign in to comment.