updating docs for v1.5.0

README.md

@@ -21,10 +21,10 @@ To plan without executing:
 ``` $ helmsman -f example.toml ```
 
 To plan and execute the plan:
-``` $ helmsman -apply -f example.toml ```
+``` $ helmsman --apply -f example.toml ```
 
 To show debugging details:
-``` $ helmsman -debug -apply -f example.toml ```
+``` $ helmsman --debug --apply -f example.toml ```
 
 # Features
 
@@ -46,9 +46,9 @@ To show debugging details:
 Check the [releases page](https://github.com/Praqma/Helmsman/releases) for the different versions.
 ```
 # on Linux
-curl -L https://github.com/Praqma/helmsman/releases/download/v1.4.0-rc/helmsman_1.4.0-rc_linux_amd64.tar.gz | tar zx
+curl -L https://github.com/Praqma/helmsman/releases/download/v1.5.0/helmsman_1.5.0_linux_amd64.tar.gz | tar zx
 # on MacOS
-curl -L https://github.com/Praqma/helmsman/releases/download/v1.4.0-rc/helmsman_1.4.0-rc_darwin_amd64.tar.gz | tar zx
+curl -L https://github.com/Praqma/helmsman/releases/download/v1.5.0/helmsman_1.5.0_darwin_amd64.tar.gz | tar zx
 
 mv helmsman /usr/local/bin/helmsman
 ```
@@ -67,6 +67,7 @@ Helmsman lets you:
 - [install/delete/upgrade/rollback your helm charts from code](https://github.com/Praqma/helmsman/blob/master/docs/how_to/manipulate_apps.md).
 - [work safely in a multitenant cluster](https://github.com/Praqma/helmsman/blob/master/docs/how_to/multitenant_clusters_guide.md).
 - [pass secrets/user input to helm charts from environment variables](https://github.com/Praqma/helmsman/blob/master/docs/how_to/pass_secrets_from_env_variables.md).
+- [send Slack notifications from Helmsman](https://github.com/Praqma/helmsman/blob/master/docs/how_to/send_slack_notifications_from_helmsman.md)
 - [test releases when they are first installed](https://github.com/Praqma/helmsman/blob/master/docs/how_to/test_charts.md).
 - [use public and private helm charts](https://github.com/Praqma/helmsman/blob/master/docs/how_to/use_private_helm_charts.md).
 - [use locally developed helm charts (the tar archives)](https://github.com/Praqma/helmsman/blob/master/docs/how_to/use_local_charts.md).

docs/best_practice.md

@@ -16,5 +16,5 @@ When using Helmsman, we recommend the following best practices:
 
 - 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 that and following it.
+- 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.
 

docs/deplyment_strategies.md

@@ -4,7 +4,7 @@ version: v1.1.0
 
 # Deployment Strategies 
 
-This document describes the different startegies to use Helmsman for maintaining your helm charts deployment to k8s clusters.
+This document describes the different strategies to use Helmsman for maintaining your helm charts deployment to k8s clusters.
 
 ## Deploying 3rd party charts (apps) in a production cluster
 
@@ -122,7 +122,7 @@ 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 automtically 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/run_helmsman_in_ci.md) as described in the diagram below:
 
@@ -136,10 +136,10 @@ If you need supporting applications (charts) for your application (e.g, reverse
 
 ## Notes on using multiple Helmsman desired state files with the same cluster
 
-Helmsman works with a single desired state file at a time 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:
+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/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:
 
-- no releases have the same name in different desired state files pointing to the same cluster. If such conflict exists, Helmsman will not raise any errors but that release would be subject to unexpected behaviour.
+- no releases have the same name in different desired state files pointing to the same cluster. If such conflict exists, Helmsman will not raise any errors but that release would be subject to unexpected behavior.
 
 - protected namespaces are defined protected in all the desired state files. Otherwise, namespace protection can be accidentally compromised if the same release name is used across multiple desired state files.
 
-Also please refere to the [best parctice](best_practice.md) document. 
+Also please refer to the [best practice](best_practice.md) document. 

docs/desired_state_specification.md

@@ -1,5 +1,5 @@
 ---
-version: v1.4.0-rc
+version: v1.5.0
 ---
 
 # Helmsman desired state specification
@@ -8,7 +8,7 @@ This document describes the specification for how to write your Helm charts desi
 
 - [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.
-- [Settings](#settings) -- data about your k8s cluster. 
+- [Settings](#settings) -- data about your k8s cluster and how to deploy Helm on it if needed. 
 - [Namespaces](#namespaces) -- defines the namespaces where you want your Helm charts to be deployed.
 - [Helm Repos](#helm-repos) -- defines the repos where you want to get Helm charts from.
 - [Apps](#apps) -- defines the applications/charts you want to manage in your cluster.
@@ -119,13 +119,14 @@ settings:
 
 Optional : No.
 
-Synopsis: defines the namespaces to be used/created in your k8s cluster and wether they are protected or not. It also defines if Tiller should be deployed in these namespaces and with what configurations (TLS and service account). You can add as many namespaces as you like.
-If a namespaces does not already exist, Helmsman will create it.
+Synopsis: defines the namespaces to be used/created in your k8s cluster and whether they are protected or not. It also defines if Tiller should be deployed in these namespaces and with what configurations (TLS and service account). You can add as many namespaces as you like.
+If a namespace does not already exist, Helmsman will create it.
 
 Options: 
 - protected : defines if a namespace is protected (true or false). Default false.
-- 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. 
-> Tiller will ALWAYS be deployed into `kube-system`, even if you set installTiller for kube-system to false.
+> For the definition of what a protected namespace means, check the [protection guide](how_to/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.
 
 - tillerServiceAccount: defines what service account to use when deploying Tiller. If this is not set, the following options are considered:
 
@@ -141,12 +142,13 @@ Options:
     - clientCert: the SSL certificate for the Helm client.
     - clientKey: the SSL certificate private key for the Helm client.
 
-> For the definition of what a protected namespace means, check the [protection guide](how_to/protect_namespaces_and_releases.md)
-
 Example: 
 
 ```toml
 [namespaces]
+# to prevent deploying Tiller into kube-system, use the two lines below
+# [namespaces.kube-system]
+# installTiller = false # this line can be omitted since installTiller defaults to false
 [namespaces.staging]
 [namespaces.dev]
 protected = false
@@ -163,6 +165,9 @@ clientKey = "s3://mybucket/mydir/helm.key.pem"
 
 ```yaml
 namespaces:
+  # to prevent deploying Tiller into kube-system, use the two lines below
+  # kube-system: 
+  #  installTiller: false # this line can be omitted since installTiller defaults to false
   staging:
   dev:
     protected: false
@@ -238,6 +243,7 @@ Options:
 - description : a release metadata for human readers.
 - valuesFile  : a valid path to custom Helm values.yaml file. File extension must be `yaml`. Cannot be used with valuesFiles together. Leaving it empty uses the default chart values.
 - valuesFiles : array of valid paths to custom Helm values.yaml file. File extension must be `yaml`. Cannot be used with valuesFile together. Leaving it empty uses the default chart values.
+> The values file(s) path is relative from the location of the (first) desired state file you pass in your Helmsman command.
 - purge       : defines whether to use the Helm purge flag when deleting the release. (true/false)
 - test        : defines whether to run the chart tests whenever the release is installed.
 - protected   : defines if the release should be protected against changes. Namespace-level protection has higher priority than this flag. Check the [protection guide](how_to/protect_namespaces_and_releases.md) for more details.

docs/how_to/define_namespaces.md

@@ -1,5 +1,5 @@
 ---
-version: v1.3.0-rc
+version: v1.5.0
 ---
 
 # define namespaces
@@ -29,8 +29,12 @@ namespaces:
 
 >For details on protecting a namespace, please check the [namespace/release protection guide](protect_namespaces_and_releases.md)
 
+## Deploying Tiller into namespaces 
+
 As of `v1.2.0-rc`, you can instruct Helmsman to deploy Tiller into specific namespaces (with or without TLS).
 
+> 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, see the subsection below.
+
 ```toml
 [namespaces]
 [namespaces.production]
@@ -57,6 +61,22 @@ namespaces:
     clientKey: "s3://mybucket/mydir/helm.key.pem"
 ```
 
+### Preventing Tiller deployment in kube-system 
+
+By default Tiller will be deployed into `kube-system` even if you don't define kube-system in the namespaces section. To prevent this, simply add `kube-system` into your namespaces section. Since `installTiller` for namespaces is by default false, Helmsman will not deploy Tiller in `kube-system`.
+
+```toml
+[namespaces]
+[namespaces.kube-system]
+# installTiller = false  # this line is not needed since the default is false, but can be added for human readability.
+```
+```yaml
+namespaces:
+  kube-system:
+    #installTiller: false # this line is not needed since the default is false, but can be added for human readability.
+```
+
+## Deploying releases with specific Tillers
 You can then tell Helmsman to deploy specific releases in a specific namespace:
 
 ```toml

docs/how_to/helmsman_on_windows10.md

@@ -2,9 +2,11 @@
 version: v1.1.0
 ---
 
+> This guide has not been thoroughly tested.
+
 # Using Helmsman from a docker image on Windows 10
 
-If you have Windows 10 with Docker installed, you might be able to run Helmsman in a linux container on Windows.
+If you have Windows 10 with Docker installed, you **might** be able to run Helmsman in a linux container on Windows.
 
 1. Switch to the Linux containers from the docker tray icon.
 2. Configure your local kubectl on Windows to connect to your cluster.

docs/how_to/manipulate_apps.md

@@ -1,5 +1,5 @@
 ---
-version: v1.3.0-rc
+version: v1.5.0
 ---
 
 # install releases 
@@ -8,7 +8,7 @@ You can run helmsman with the [example.toml](https://github.com/Praqma/helmsman/
 
 ``` 
 
-$ helmsman -apply -f example.toml 
+$ helmsman --apply -f example.toml 
 2017/11/19 18:17:57 Parsed [[ example.toml ]] successfully and found [ 2 ] apps.
 2017/11/19 18:17:59 WARN: I could not create namespace [staging ]. It already exists. I am skipping this.
 2017/11/19 18:17:59 WARN: I could not create namespace [default ]. It already exists. I am skipping this.
@@ -35,10 +35,10 @@ You can then change your desire, for example to disable the Jenkins release that
 
 Then run Helmsman again and it will detect that you want to delete Jenkins:
 
-> Note: deleting the jenkins app entry in example.toml WILL NOT resultin deleting the jenkins release. It simply means that Helmsman is no longer responsible for managing it.
+> Note: As of v1.4.0-rc, deleting the jenkins app entry in the desired state file WILL result in deleting the jenkins release. To prevent this, use the `--keep-untracked-releases` flag with your Helmsman command.
 
 ```
-$ helmsman -apply -f example.toml 
+$ helmsman --apply -f example.toml 
 2017/11/19 18:28:27 Parsed [[ example.toml ]] successfully and found [ 2 ] apps.
 2017/11/19 18:28:29 WARN: I could not create namespace [staging ]. It already exists. I am skipping this.
 2017/11/19 18:28:29 WARN: I could not create namespace [default ]. It already exists. I am skipping this.
@@ -98,10 +98,11 @@ apps:
 
 # rollback releases 
 
+> Rollbacks in helm versions 2.8.2 and higher may not work due to a [bug](https://github.com/helm/helm/issues/3722).  
 Similarly, if you change `enabled` back to `true`, it will figure out that you would like to roll it back. 
 
 ```
-$ helmsman -apply -f example.toml 
+$ helmsman --apply -f example.toml 
 2017/11/19 18:30:41 Parsed [[ example.toml ]] successfully and found [ 2 ] apps.
 2017/11/19 18:30:42 WARN: I could not create namespace [staging ]. It already exists. I am skipping this.
 2017/11/19 18:30:43 WARN: I could not create namespace [default ]. It already exists. I am skipping this.
@@ -116,7 +117,7 @@ DECISION: release [ artifactory ] is desired to be upgraded. Planing this for yo
 
 # upgrade releases
 
-Everytime you run Helmsman, (unless the release is [protected or deployed in a protected namespace](protect_namespaces_and_releases.md)) it will upgrade existing deployed releases to the version you specified in the desired state file. It also applies the `values.yaml` file you specify with each install/upgrade. This means that when you don't change anything for a specific release, Helmsman would upgrade with the `values.yaml` file you provide (just in case it is a new file or you changed something there.)
+Every time you run Helmsman, (unless the release is [protected or deployed in a protected namespace](protect_namespaces_and_releases.md)) it will upgrade existing deployed releases to the version you specified in the desired state file. It also applies the `values.yaml` file you specify with each install/upgrade. This means that when you don't change anything for a specific release, Helmsman would upgrade with the `values.yaml` file you provide (just in case it is a new file or you changed something there.)
 
 If you change the chart, the existing release will be deleted and a new one with the same name will be created using the new chart.
 

docs/how_to/merge_desired_state_files.md

@@ -1,10 +1,10 @@
 ---
-version: v1.5.0-rc
+version: v1.5.0
 ---
 
 # supply multiple desired state files
 
-Starting from v1.5.0-rc, Helmsman allows you to pass the `-f` flag multiple times to specify multiple desired state files
+Starting from v1.5.0, Helmsman allows you to pass the `-f` flag multiple times to specify multiple desired state files
 that should be merged. This allows us to do things like specify our non-environment-specific config in a `common.toml` file
 and environment specific info in a `nonprod.toml` or `prod.toml` file. This process uses [this library](https://github.com/imdario/mergo)
 to do the merging, and is subject to the limitations described there.

docs/how_to/move_charts_across_namespaces.md

@@ -111,7 +111,7 @@ Helmsman will delete the jenkins release from the `staging` namespace and instal
 
 Helmsman does not automatically move PVCs across namespaces. You have to follow the steps below to retain your data when moving an app to a different namespace.
 
-Persistent Volumes (PV) are accessed through Persistent Volume Claims (PVC). But **PVCs are namespaced object** which means moving an application from one namespace to another will result in a new PVC created in the new namespace. The old PV -which possibly contains your application data- will still be mounted to the old PVC (the one in the old namespace) even if you have deleted your application helm release.
+Persistent Volumes (PV) are accessed through Persistent Volume Claims (PVC). But **PVCs are namespaced objects** which means moving an application from one namespace to another will result in a new PVC created in the new namespace. The old PV -which possibly contains your application data- will still be mounted to the old PVC (the one in the old namespace) even if you have deleted your application helm release.
 
 Now, the newly created PVC (in the new namespace) will not be able to mount to the old PV and instead it will mount to any other available one or (in the case of dynamic provisioning) will provision a new PV. This means the application in the new namespace does not have the old data. Don't panic, the old PV is still there and contains your old data.
 
@@ -131,7 +131,7 @@ kubectl delete pvc <your-pvc-name> --namespace <the-old-namespace>
 ```
 Since, we changed the Reclaim Policy to Retain, the PV will stay around (with all your data).
 
-3. The PV is now the **Released** state but not yet available for mounting.
+3. The PV is now in the **Released** state but not yet available for mounting.
 
 ```
 kubectl get pv