updating docs for v1.0.0

README.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 ![helmsman-logo](docs/images/helmsman.png)
@@ -20,6 +20,7 @@ Helmsman was created to ease continous deployment of Helm charts. When you want
 - **Easy to use**: deep knowledge of Helm CLI and Kubectl is NOT manadatory to use Helmsman. 
 - **Plan, View, apply**: you can run Helmsman to generate and view a plan with/without executing it. 
 - **Portable**: Helmsman can be used to manage charts deployments on any k8s cluster.
+- **Protect Namespaces/Releases**: you can define certain namespaces/releases to be protected against accidental human mistakes.
 - **Idempotency**: As long your desired state file does not change, you can execute Helmsman several times and get the same result. 
 - **Continue from failures**: In the case of partial deployment due to a specific chart deployment failure, fix your helm chart and execute Helmsman again without needing to rollback the partial successes first.
 
@@ -40,14 +41,14 @@ Helmsman can be used in three different settings:
 
 - [As a binary with Minikube](https://github.com/Praqma/helmsman/blob/master/docs/how_to/run_helmsman_with_minikube.md).
 - [As a binary with a hosted cluster](https://github.com/Praqma/helmsman/blob/master/docs/how_to/run_helmsman_with_hosted_cluster.md).
-- [As a docker image in a CI system or local machine](https://github.com/Praqma/helmsman/blob/master/docs/how_to/run_helmsman_in_ci.md).
+- [As a docker image in a CI system or local machine](https://github.com/Praqma/helmsman/blob/master/docs/how_to/run_helmsman_in_ci.md) Always use a tagged docker image from [dockerhub](https://hub.docker.com/r/praqma/helmsman/) as the `latest` image can (at times) be unstable.
 
 
 # How does it work?
 
 Helmsman uses a simple declarative [TOML](https://github.com/toml-lang/toml) file to allow you to describe a desired state for your k8s applications as in the [example file](https://github.com/Praqma/helmsman/blob/master/example.toml).
 
-The desired state file follows the [desired state specification](https://github.com/Praqma/helmsman/blob/master/docs/desired_state_specification.md).
+The desired state file (DSF) follows the [desired state specification](https://github.com/Praqma/helmsman/blob/master/docs/desired_state_specification.md).
 
 Helmsman sees what you desire, validates that your desire makes sense (e.g. that the charts you desire are available in the repos you defined), compares it with the current state of Helm and figures out what to do to make your desire come true. 
 
@@ -73,4 +74,4 @@ Documentation and How-Tos can be found [here](https://github.com/Praqma/helmsman
 
 # Contributing
 
-Contribution and feeback/feature requests are welcome. 
+Pull requests, feeback/feature requests are welcome. 

docs/best_practice.md

@@ -0,0 +1,20 @@
+---
+version: v1.0.0
+---
+
+# Best Practice 
+
+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.
+
+- Use environment variabels 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. 
+
+- Don't maintain the same release in multiple DSFs. 
+
+- While the decison on how many DSFs to use and what each can containt is up to you and dependes on your case, we recommend coming up with your own rule for that and following it.
+

docs/deplyment_strategies.md

@@ -0,0 +1,94 @@
+---
+version: v1.0.0
+---
+
+# Deployment Strategies 
+
+This document describes the different startegies to use Helmsman for maintaining your helm charts deployment to k8s clusters.
+
+## Deploying 3rd party charts (apps) in a production cluster
+
+Suppose you are deploying 3rd party charts (e.g. Jenkins, Jira ... etc.) in your cluster. These applications can be deployed with Helmsman using a single desired state file. The desired state tells helmsman to deploy these apps into certain namespaces in a production cluster.  
+
+You can test 3rd party charts in designated namespaces (e.g, staging) within the same production cluster. This also can be defined in the same desired state file. Below is an example of a desired state file for deploying 3rd party apps in production and staging namespaces:  
+
+```
+[metadata]
+org = "example"
+
+# using a minikube cluster
+[settings]
+kubeContext = "minikube" 
+
+[namespaces]
+  [namespaces.staging]
+  protected = false
+  [namespaces.production]
+  prtoected = true
+
+[helmRepos]
+stable = "https://kubernetes-charts.storage.googleapis.com"
+incubator = "http://storage.googleapis.com/kubernetes-charts-incubator"
+
+[apps]
+
+    [apps.jenkins]
+    name = "jenkins-prod" # should be unique across all apps
+    description = "production jenkins"
+    namespace = "production" 
+    enabled = true 
+    chart = "stable/jenkins" 
+    version = "0.9.1" # chart version
+    valuesFile = "../my-jenkins-production-values.yaml" 
+
+
+    [apps.artifactory]
+    name = "artifactory-prod" # should be unique across all apps
+    description = "production artifactory"
+    namespace = "production" 
+    enabled = true 
+    chart = "stable/artifactory" 
+    version = "6.2.0" # chart version
+    valuesFile = "../my-artificatory-production-values.yaml" 
+   
+
+    # the jenkins release below is being tested in the staging namespace
+    [apps.jenkins-test]
+    name = "jenkins-test" # should be unique across all apps
+    description = "test release of jenkins, testing xyz feature"
+    namespace = "staging" 
+    enabled = true 
+    chart = "stable/jenkins" 
+    version = "0.9.1" # chart version
+    valuesFile = "../my-jenkins-testing-values.yaml" 
+
+```
+
+You can split the desired state file into multiple files if your deployment pipelines requires that, but it is important to read the notes below on using multiple desired state files with one cluster.
+
+## Working with multiple clusters
+
+If you use multiple clusters for multiple purposes, you need at least one Helmsman desired state file for each cluster. 
+
+
+## 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.
+
+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:
+
+![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. 
+
+If you need supporting applications (charts) for your application (e.g, reverse proxies, DB, k8s dashborad 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. 
+
+## 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:
+
+- 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.
+
+- 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. 

docs/desired_state_specification.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 # Helmsman desired state specification
@@ -85,18 +85,23 @@ kubeContext = "minikube"
 
 Optional : No.
 
-Synopsis: defines the namespaces to be used/created in your k8s cluster. You can add as many namespaces as you like.
-If a namespaces does not already exist, Helmsman will be created.
+Synopsis: defines the namespaces to be used/created in your k8s cluster and wether they are protected or not. You can add as many namespaces as you like.
+If a namespaces does not already exist, Helmsman will create it.
 
 Options: 
-- you can define any key/value pairs.
+- protected : defines if a namespace is protected (true or false). Default false.
+
+> For the defintion of what a protected namespace means, check the [protection guide](how_to/protect_namespaces_and_releases.md)
 
 Example: 
 
 ```
 [namespaces]
-staging = "staging" 
-production = "default"
+[namespaces.staging]
+[namespaces.dev]
+protected = false
+[namespaces.production]
+protected = true
 ```
 
 ## Helm Repos
@@ -144,6 +149,7 @@ Options:
 - valuesFile  : a valid path to custom Helm values.yaml file. File extension must be `yaml`. Leaving it empty uses the default chart values.
 - purge       : defines whether to use the Helm purge flag wgen deleting the release. (true/false)
 - test        : defines whether to run the chart tests whenever the release is installed/upgraded/rolledback.
+- 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.
 
 Example: 
 
@@ -162,5 +168,6 @@ Example:
     valuesFile = "" 
     purge = false 
     test = true 
+    protected = false
 ```
 

docs/how_to/move_charts_across_namespaces.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 # move charts across namespaces
@@ -12,9 +12,9 @@ If you have a workflow for testing a release first in the `staging` namespace th
 ...
 
 [namespaces]
-staging = "staging" 
-production = "default"
-myOtherNamespace = "namespaceX"
+[namespaces.staging]
+[namespaces.production]
+
 
 [apps]
 
@@ -38,9 +38,8 @@ Then if you change the namespace key for jenkins:
 ...
 
 [namespaces]
-staging = "staging" 
-production = "default"
-myOtherNamespace = "namespaceX"
+[namespaces.staging]
+[namespaces.production]
 
 [apps]
 

docs/how_to/pass_secrets_from_env_variables.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 # pass secrets from env. variables:

docs/how_to/protect_namespaces_and_releases.md

@@ -0,0 +1,64 @@
+---
+version: v1.0.0
+---
+
+# Namespace and Release Protection 
+
+Since helmsman is used with version controlled code and is often configured to be triggered as part of a CI pipeline, accidental mistakes could happen by the user (e.g, disabling a production application and taking out of service as a result of a mistaken change in the desired state file). 
+
+Helmsman provides the `plan` flag which helps you see the actions that it will take based on your desired state file before actually doing them. We recommend to use a `plan-hold-approve` pipeline when using helmsman with production clusters. 
+
+As of version v1.0.0, helmsman provides a fine-grained mechansim to protect releases/namespaces from accidental desired state file changes. 
+
+## Protection definition 
+
+- When a release (application) is protected, it CANNOT:
+    - deleted
+    - upgraded
+    - moved to another namespace
+
+- A release CAN be moved into protection from a non-protected state.
+- If a protected release need to be updated/changed or even deleted, this is possible, but the protection has to be removed first (i.e. remove the namespace/release from the protected state). This explained further below.
+
+> A release is an instance (installation) of an application which has been packaged as a helm chart. 
+
+## Protection mechanism
+Protection is supported in two forms:
+
+- **Namespace-level Protection**: is defined at the namespace level. A namespace can be declaratively defined to be protected in the desired state file as in the example below:
+
+``` 
+[namespaces]
+  [namespaces.staging]
+  protected = false
+  [namespaces.production]
+  prtoected = true
+
+```
+
+- **Release-level Protection** is defined at the release level as in the example below:
+
+```
+[apps]
+
+    [apps.jenkins]
+    name = "jenkins" 
+    description = "jenkins"
+    namespace = "staging" 
+    enabled = true 
+    chart = "stable/jenkins" 
+    version = "0.9.1" 
+    valuesFile = "" 
+    purge = false 
+    test = false 
+    protected = true # defining this release to be protected.
+```
+
+> All releases in a protected namespace are automatically protected. Namespace protection has higher priority than the relase-level protection.
+
+## Important Notes
+
+- You can combine both types of protection in your desired state file. The namespace-level protection always has a higher priority.
+- Removing the protection from a namespace means all releases deployed in that namespace are no longer protected.
+- We recommend using namespace-level protection for production namespace(s) and release-level protection for releases deployed in other namespaces.
+- Release/namespace protection is only applied on single desired state files. It is your responsibility to make sure that multiple desired state files (if used) do not conflict with each other (e.g, one defines a particular namespace as defined and another defines it unprotected.) If you use multiple desired state files with the same cluster, please refer to [deploymemt strategies](../deplyment_strategies.md) and [best practice](../best_practice.md) documentation.

docs/how_to/run_helmsman_in_ci.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 # Run Helmsman in CI
@@ -13,7 +13,7 @@ jobs:
     
     deploy-apps:
       docker:
-        - image: praqma/helmsman:v0.1.2
+        - image: praqma/helmsman:v1.0.0
       steps:
         - checkout
         - run:

docs/how_to/run_helmsman_with_hosted_cluster.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 You can manage Helm charts deployment on a hosted K8S cluster in the cloud or on-prem. You need to include the required information to connect to the cluster in your state file. 
@@ -46,7 +46,7 @@ password = "$K8S_PASSWORD" # the name of an environment variable containing the
 clusterURI = "$K8S_URI" # cluster API
 
 [namespaces]
-staging = "staging" 
+[namespaces.staging]
 
 [helmRepos]
 stable = "https://kubernetes-charts.storage.googleapis.com"

docs/how_to/run_helmsman_with_minikube.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 You can run Helmsman local as a binary application with Minikube, you just need to skip all the cluster connection settings in your desired state file. Below is the example.toml desired state file adapted to work with Minikube.
@@ -14,7 +14,7 @@ maintainer = "k8s-admin"
 kubeContext = "minikube" 
 
 [namespaces]
-staging = "staging" 
+[namespaces.staging]
 
 [helmRepos]
 stable = "https://kubernetes-charts.storage.googleapis.com"

docs/how_to/test_charts.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 # test charts

docs/how_to/use_local_charts.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 # use local helm charts

docs/how_to/use_private_helm_charts.md

@@ -1,5 +1,5 @@
 ---
-version: v0.2.0
+version: v1.0.0
 ---
 
 # use private helm charts