Merge pull request #285 from wilsonmar/master

Fixes to grammar and sequencing of text

docs/best_practice.md

@@ -6,15 +6,15 @@ version: v1.0.0
 
 When using Helmsman, we recommend the following best practices:
 
-- Add useful metadata in your desired state files (DSFs) so that others (who have access to them) can make understand what your DSF is for. We recommend the following metadata: organization, maintainer (name and email), and description/purpose.
+- Add useful metadata in your desired state files (DSFs) so that others (who have access to them) can make understandable what your DSF is for. We recommend the following metadata: organization, maintainer (name and email), and description/purpose.
 
 - Use environment variables to pass K8S connection secrets (password, certificates paths on the local system or AWS/GCS bucket urls and the API URI). This keeps all sensitive information out of your version controlled source code.
 
 - Define certain namespaces (e.g, production) as protected namespaces (supported in v1.0.0+) and deploy your production-ready releases there.
 
-- If you use multiple desired state files (DSF) with the same cluster, make sure your namespace protection definitions are identical across all DSFs.
+- If you use multiple desired state files (DSFs) with the same cluster, make sure your namespace protection definitions are identical across all DSFs.
 
 - Don't maintain the same release in multiple DSFs.
 
-- While the decision on how many DSFs to use and what each can contain is up to you and depends on your case, we recommend coming up with your own rule for how to split them.
+- While the decision on how many DSFs to use and what each can contain is up to you and depends on your case, we recommend coming up with your own rules for how to split them.
 

docs/cmd_reference.md

@@ -4,7 +4,7 @@ version: v1.11.0
 
 # CMD reference
 
-This is the list of the available CMD options in Helmsman:
+This lists available CMD options in Helmsman:
 
 > you can find the CMD options for the version you are using by typing: `helmsman -h` or `helmsman --help`
 
@@ -15,7 +15,7 @@ This is the list of the available CMD options in Helmsman:
         apply Helmsman labels to Helm state for all defined apps.
 
   `--debug`
-        show the execution logs.
+        show execution logs.
 
   `--destroy`
         delete all deployed releases. Purge delete is used if the purge option is set to true for the releases.
@@ -24,23 +24,32 @@ This is the list of the available CMD options in Helmsman:
         number of lines of context to show around changes in helm diff output.
 
   `--dry-run`
-        apply the dry-run option for helm commands.
+        apply the dry-run (do not update) option for helm commands.
 
   `-e value`
         file(s) to load environment variables from (default .env), may be supplied more than once.
 
   `-f value`
         desired state file name(s), may be supplied more than once to merge state files.
 
+  `--force-upgrades`
+        use --force when upgrading helm releases. May cause resources to be recreated.  
+
   `--keep-untracked-releases`
         keep releases that are managed by Helmsman and are no longer tracked in your desired state.
 
+  `--kubeconfig`
+        path to the kubeconfig file to use for CLI requests.
+
   `--no-banner`
         don't show the banner.
 
   `--no-color`
         don't use colors.
 
+  `--no-env-subst`
+        turn off environment substitution globally.
+
   `--no-fancy`
         don't display the banner and don't use colors.
 
@@ -59,22 +68,13 @@ This is the list of the available CMD options in Helmsman:
   `--suppress-diff-secrets`
         don't show secrets in helm diff output.
 
-  `-v`    show the version.
-
-  `--verbose`
-        show verbose execution logs.
-
-  `--kubeconfig`
-        path to the kubeconfig file to use for CLI requests.
-
   `--target`
         limit execution to specific app.
 
-  `--no-env-subst`
-        turn off environment substitution globally.
-
   `--update-deps`
         run 'helm dep up' for local chart     
 
-   `--force-upgrades`
-        use --force when upgrading helm releases. May cause resources to be recreated.      
+  `-v`    show the version.
+
+  `--verbose`
+        show verbose execution logs.

docs/deployment_strategies.md

@@ -121,19 +121,19 @@ If you use multiple clusters for multiple purposes, you need at least one Helmsm
 
 ## Deploying your dev charts
 
-If you are developing your own applications/services and packaging them in helm charts. It makes sense to automatically deploy these charts to a staging namespace or a dev cluster on every source code commit.
+If you are developing your own applications/services and packaging them in helm charts, it makes sense to automatically deploy these charts to a staging namespace or a dev cluster on every source code commit.
 
 Often, you would have multiple apps developed in separate source code repositories but you would like to test their deployment in the same cluster/namespace. In that case, Helmsman can be used [as part of your CI pipeline](how_to/deployments/ci.md) as described in the diagram below:
 
 > as of v1.1.0 , you can use the `ns-override`flag to force helmsman to deploy/move all apps into a given namespace. For example, you could use this flag in a CI job that gets triggered on commits to the dev branch to deploy all apps into the `staging` namespace.
 
 ![multi-DSF](images/multi-DSF.png)
 
-Each repository will have a Helmsman desired state file (DSF). But it is important to consider the notes below on using multiple desired state files with one cluster.
+Each repository will have a Helmsman desired state file (DSF). But it is important to consider the notes below on using multiple desired state files with a single cluster.
 
-If you need supporting applications (charts) for your application (e.g, reverse proxies, DB, k8s dashboard etc.), you can describe the desired state for these in a separate file which can live in another repository. Adding such file in the pipeline where you create your cluster from code makes total "DevOps" sense.
+If you need supporting applications (charts) for your application (e.g, reverse proxies, DB, k8s dashboard, etc.), you can describe the desired state for these in a separate file which can live in another repository. Adding such a file in the pipeline where you create your cluster from code makes total "DevOps" sense.
 
-## Notes on using multiple Helmsman desired state files with the same cluster
+## Notes on using multiple Helmsman desired state files for the same cluster
 
 Helmsman works with a single desired state file at a time (starting from v1.5.0, you can pass multiple desired state files which get merged at runtime. See the [docs](how_to/misc/merge_desired_state_files.md)) and does not maintain a state anywhere. i.e. it does not have any context awareness about other desired state files used with the same cluster. For this reason, it is the user's responsibility to make sure that:
 

docs/desired_state_specification.md

@@ -4,7 +4,7 @@ version: v1.11.0
 
 # Helmsman desired state specification
 
-This document describes the specification for how to write your Helm charts desired state file. This can be either [Toml](https://github.com/toml-lang/toml) or [Yaml](http://yaml.org/) file. The desired state file consists of:
+This document describes the specification for how to write your Helm charts' desired state file. This can be either a [Toml](https://github.com/toml-lang/toml) or [Yaml](http://yaml.org/) formatted file. The desired state file consists of:
 
 - [Metadata](#metadata) [Optional] -- metadata for any human reader of the desired state file.
 - [Certificates](#certificates) [Optional] -- only needed when you want Helmsman to connect kubectl to your cluster for you.
@@ -145,9 +145,9 @@ Options:
 > For the definition of what a protected namespace means, check the [protection guide](how_to/misc/protect_namespaces_and_releases.md)
 - **installTiller**: defines if Tiller should be deployed in this namespace or not. Default is false. Any chart desired to be deployed into a namespace with a Tiller deployed, will be deployed using that Tiller and not the one in kube-system unless you use the `TillerNamespace` option (see the [Apps](#apps) section below) to use another Tiller.
 > By default Tiller will be deployed into `kube-system` even if you don't define kube-system in the namespaces section. To prevent deploying Tiller into `kube-system, add kube-system in your namespaces section and set its installTiller to false.
-- **tillerMaxHistory**: specify int value of the maximum number of revisions saved per release by Tiller.
+- **tillerMaxHistory**: specifies an int value of the maximum number of revisions saved per release by Tiller.
 > In order to set the kube-system's Tiller's (a default one, main Tiller) max history, define namespace kube-system and set tillerMaxHistory along with installTiller: true
-- **tillerRole**: specify the role to use.  If 'cluster-admin' a clusterrolebinding will be used else a role with a single namespace scope will be created and bound with a rolebinding.
+- **tillerRole**: specifies the role to use.  If 'cluster-admin' a clusterrolebinding will be used else a role with a single namespace scope will be created and bound with a rolebinding.
 - **tillerRoleTemplateFile**: relative path to file templating custom Tiller role. If `installTiller` is true and `tillerRole` is not `cluster-admin`, then helmsman will create namespace specific Tiller role based on the template file passed with this parameter. When `tillerRole` is empty string, role name defaults to `helmsman-tiller`.
 
   If `tillerRoleTemplateFile` is set, it will always try to create namespace-scoped Tiller with conditions like below:
@@ -267,7 +267,7 @@ Authenticating to private helm repos:
     - Or, set `GCLOUD_CREDENTIALS` environment variable to contain the content of the credentials.json file.
 
 Options:
-- you can define any key/value pairs where key is the repo name and value is a valid URI for the repo. Basic auth info can be added in the repo URL as in the example below.
+- you can define any key/value pair where the key is the repo name and value is a valid URI for the repo. Basic auth info can be added in the repo URL as in the example below.
 
 Example:
 

docs/how_to/README.md

@@ -46,5 +46,5 @@ This page contains a list of guides on how to use Helmsman.
     - [Send slack notifications from Helmsman](misc/send_slack_notifications_from_helmsman.md)
     - [Merge multiple desired state files](misc/merge_desired_state_files.md)
     - [Limit Helmsman deployment to specific apps](misc/limit-deployment-to-specific-apps.md)
-    - [Multitenant clusters guide](misc/multitenant_clusters_guide.md)
+    - [Multi-tenant clusters guide](misc/multitenant_clusters_guide.md)
     - [Helmsman on Windows 10](misc/helmsman_on_windows10.md)

docs/why_helmsman.md

@@ -9,34 +9,41 @@ This document describes the reasoning and need behind the inception of Helmsman.
 ## Before Helm
 
 Helmsman was created with continuous deployment in mind.
-When we started using k8s, we deployed applications on our cluster directly from k8s manifest files. Initially, we had a custom shell script added to our CI system to deploy the k8s resources on the cluster. That script could only create the k8s resources from the manifest files. Soon we needed to have a more flexible way to dynamically create/delete those resources. We structured our git repo and used custom file names (adding enabled or disabled into file names) and updated the shell script accordingly. It did not take long before we realized that this does not scale and is difficult to maintain.
+When we started using Kubernetes (k8s), we deployed applications on our cluster directly from k8s manifest files. Initially, we had a custom <strong>shell script</strong> added to our CI system to deploy the k8s resources on the cluster. 
 
 ![CI-pipeline-before-helm](images/CI-pipeline-before-helm.jpg)
 
+That script could only create the k8s resources from the manifest files. Soon we needed to have a more flexible way to dynamically create/delete those resources. We structured our git repo and used custom file names (adding enabled or disabled into file names) and updated the shell script accordingly. It did not take long before we realized that this does not scale and is difficult to maintain.
+
 ## Helm to the rescue?
 
-While looking for solutions for managing the growing number of k8s manifest files from a CI pipeline, we came to know about Helm and quickly realized its potential. By creating Helm charts, we packaged related k8s manifests together into a single entity "a chart". This reduced the amount of files the CI script has to deal with. However, all the CI shell script could do is package a chart and install/upgrade it in our k8s cluster whenever a new commit is done into the chart's files in git.
+While looking for solutions for managing the growing number of k8s manifest files from a CI pipeline, we came to know about Helm and quickly realized its potential. 
+By creating <strong>Helm charts</strong>, we packaged related k8s manifests together into a single entity: "a chart". 
 
 ![CI-pipeline-after-helm](images/CI-pipeline-after-helm.jpg)
 
-But there were a couple of issues here:
-1. Helm has more to it than package and install. Operations such as rollback, running chart tests etc. are only doable from the Helm's CLI client.
+This reduced the amount of files the CI script has to deal with. However, all the CI shell script could do is package a chart and install/upgrade it in our k8s cluster whenever a new commit is done into the chart's files in git.
+
+But there were a few issues:
+1. Helm has more to it than package and install. Operations such as rollback, running chart tests, etc. are only doable from Helm's CLI client.
 2. You have to keep updating your CI script every time you add a chart to k8s.
 3. What if you want to do the same on another cluster? you will have to replicate your CI pipeline and possibly change your CI script accordingly.
 
-We have also decided to split the Helm charts development from the git repositories where they are used. This is simply to let us develop the charts independently from the projects where we used them and to allow us to reuse them in different projects.
+Helm chart development is split from the git repositories where they are used. This is simply to let us develop the charts independently from the projects where we used them and to allow us to reuse them in different projects.
 
-With all this in mind, we needed a flexible and dynamic solution that can let us deploy and manage Helm charts into multiple k8s cluster independently and with minimum human intervention. Such solution should be generic enough to be reusable for many different projects/cluster. And this is where Helmsman was born!
+With all this in mind, we needed a flexible and dynamic solution that can let us deploy and manage Helm charts into multiple k8s clusters independently and with minimum human intervention. Such a solution should be generic enough to be reusable for many different projects/cluster. And this is where Helmsman was born!
 
 ## The Helmsman way
 
-In English, [Helmsman](https://www.merriam-webster.com/dictionary/helmsman) is the person at the helm (in a ship). In k8s and Helm context, Helmsman holds the Helm and maintains your Helm charts' lifecycle in your k8s cluster(s). Helmsman gets its directions to navigate from a [declarative file](desired_state_specification.md) maintained by the user (k8s admin).
+In English, a [Helmsman](https://www.merriam-webster.com/dictionary/helmsman) is the person at the helm (on a ship). In k8s and Helm context, Helmsman holds the Helm and maintains your Helm charts' lifecycle in your k8s cluster(s). Helmsman gets its directions to navigate from a [declarative file](desired_state_specification.md) maintained by the user (k8s admin).
 
 > Although knowledge about Helm and K8S is highly beneficial, such knowledge is NOT required to use Helmsman.
 
-As the diagram below shows, we recommend having a _desired state file_ for each k8s cluster you are managing. Along with that file, you would need to have any custom [values yaml files](https://docs.helm.sh/chart_template_guide/#values-files) for the Helm chart's you deploy on your k8s. Then you could configure your CI pipeline to use Helmsman docker image to process your desired state file whenever a commit is made to it.
+As the diagram below shows, we recommend having a <strong>Helmsman _desired state file_</strong> for each k8s cluster you are managing. 
 
 ![CI-pipeline-helmsman](images/CI-pipeline-helmsman.jpg)
 
+Along with that file, you would need to have any custom [values yaml files](https://docs.helm.sh/chart_template_guide/#values-files) for the Helm charts you deploy on your k8s. Then you could configure your CI pipeline to use Helmsman docker images to process your desired state file whenever a commit is made to it.
+
 
 > Helmsman can also be used manually as a binary tool on a machine which has Helm and Kubectl installed.