#8 - Improve RMK context switch documentation.

Author: anovikov-el

README.md

@@ -2,7 +2,7 @@
 
 [![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: GoReleaser](https://img.shields.io/badge/powered%20by-edenlab-8A2BE2.svg?style=for-the-badge)](https://edenlab.io)
+[![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.
 

commands/project_generation_category.go

@@ -112,7 +112,7 @@ helmfiles: ` + escapeOpen + `{{ env "HELMFILE_` + escapeClose + `{{ .TenantNameE
 	helmfileCommonLabels = `commonLabels:
   scope: {{ .TenantName }}
   namespace: {{ .TenantName }}
-  bin: ` + escapeOpen + `{{ env "HELMFILE_` + escapeClose + `{{ .TenantNameEnvStyle }}` + escapeOpen + `_HOOKS_DIR" | default (env "HELMFILE_HOOKS_DIR") }}/bin` + escapeClose + `
+  bin: ` + escapeOpen + `{{ env "HELMFILE_` + escapeClose + `{{ .TenantNameEnvStyle }}` + escapeOpen + `_HOOKS_DIR" }}/bin` + escapeClose + `
   repo: core-charts
   appChartVersion: 1.6.0
   host: ` + escapeOpen + `{{ env "ROOT_DOMAIN" }}` + escapeClose + `

docs/configuration/cluster-management/cluster-management.md

@@ -5,10 +5,66 @@ 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:** An existing Kubernetes context will be used by RMK.
-- **A cluster will be provisioned from scratch using RMK**: Any of the supported cluster provider like AWS, K3D etc. will be utilized.
+- **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.
 
-## RMK cluster providers
+## Switch the context to an existing Kubernetes cluster
+
+Switching to an existing Kubernetes cluster depends on how it has been provisioned:
+
+* **Using a 3rd party tool:**
+  
+  Create a context with the name matching the pattern:
+  
+  ```
+  ^<project_name>-<environment>\b
+  ```
+  
+  > The matching is **case-insensitive**. \
+  > `^` means the beginning of text or a line. \
+  > `\b` means the **ASCII word boundary** (`\w` on one side and `\W`, `\A`, or `\z` on the other).
+  
+  For example, if you are in the `project1` repository in the `develop` branch, the following Kubernetes contexts might be accepted:
+  
+  ```
+  project1-develop
+  PROJECT1-DEVELOP
+  project1-develop-eks
+  PROJECT1-DEVELOP-EKS
+  ```
+
+* **Using RMK cluster provider**:
+
+  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,
+  if the RMK configuration for this cluster has not been created before:
+  ```shell
+  rmk config init
+  ```
+   
+  The next command depends on whether a remote cluster provider (e.g., AWS) or a local one (e.g., K3D) has been used:
+
+  * **AWS:**
+
+    ```shell
+    # --force might required to refresh the credentials after a long period of inactivity
+    rmk cluster switch --force
+    ```
+  
+  * **K3D:**
+
+    ```shell
+    rmk cluster switch
+    ```
+  
+Finally, run an RMK release command to verify the preparation of the Kubernetes context, e.g.:
+
+```shell
+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
@@ -88,16 +144,6 @@ To destroy a Kubernetes cluster, run the command:
 rmk cluster destroy
 ```
 
-#### Switch the kubectl context to an already created K8S cluster
-
-Checkout to the branch from which the K8S cluster was previously created, then run the following commands:
-
-```shell
-# required if the RMK configuration for this cluster has not been created before
-rmk config init
-rmk cluster switch --force
-```
-
 ### Create or delete K3D Kubernetes clusters
 
 RMK supports managing single-node Kubernetes clusters using [K3D](https://k3d.io).

docs/configuration/rmk-configuration-management.md

@@ -1,7 +1,7 @@
 # RMK 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, the RMK prepares
+At the time of configuration initialization launch, RMK prepares
 the state in the form of the current environment config with all the required attributes for further work.
 It also downloads and resolves and installs all necessary dependencies and tools described 
 in the [project.yaml](project-management/preparation-of-project-repository.md#projectyaml) file in the root of the project repository.
@@ -50,9 +50,9 @@ based on their values. Otherwise, the interactive mode will begin.
 
 ### Support for Multi-Factor Authentication (MFA)
 
-The RMK automatically check for an MFA device, when the following command is executed: `rmk config init`.
+RMK automatically check for an MFA device, when the following command is executed: `rmk config init`.
 
-To setup an MFA device, if it is required by the administrator, the following actions should be executed:
+To set up an MFA device, if it is required by the administrator, the following actions should be executed:
 
 1. First, sign in to the AWS Management Console.
 2. Then, go to the following page to set up security

docs/configuration/secrets-management/secrets-management.md

@@ -64,7 +64,7 @@ needed for secrets encryption or decryption.
 
 ## Generating all secrets from scratch in a batch manner using the RMK secrets manager
 
-In case of a creating tenant from scratch all the needed directories like `etc/<scope>/<env>/secrets/` should first
+In case of a creating tenant from scratch all the needed directories, such as `etc/<scope>/<env>/secrets/` should first
 be populated with an empty `.sops.yaml` file (acts as an indicator that this scope and environment will have the secrets).
 Also, before generating the secret files, you must create or complete a secret `.spec.yaml.gotmpl` file per each scope.
 `.spec.yaml.gotmpl` is a template that runs the [sprig](https://masterminds.github.io/sprig) engine with additional functions.