From b686ea682a2fc71375d6d3398f7db22d9215cf3c Mon Sep 17 00:00:00 2001 From: Anton Novikov Date: Tue, 3 Sep 2024 12:46:48 +0200 Subject: [PATCH] #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