updating docs

docs/desired_state_specification.md

@@ -1,5 +1,5 @@
 ---
-version: v1.7.4
+version: v1.8.0
 ---
 
 # Helmsman desired state specification
@@ -8,9 +8,9 @@ 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 and how to deploy Helm on it if needed.
+- [Settings](#settings) [Optional] -- 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.
+- [Helm Repos](#helm-repos) [Optional] -- defines the repos where you want to get Helm charts from.
 - [Apps](#apps) -- defines the applications/charts you want to manage in your cluster.
 
 
@@ -43,15 +43,15 @@ metadata:
 
 Optional : Yes, only needed if you want Helmsman to connect kubectl to your cluster for you.
 
-Synopsis: defines where to find the certificates needed for connecting kubectl to a k8s cluster. If connection settings (username/password/clusterAPI) are provided in the Settings section below, then you need AT LEAST to provide caCrt and caKey. You can optionally provide a client certificate (caClient) depending on your cluster connection setup.
+Synopsis: defines where to find the certificates needed for connecting kubectl to a k8s cluster. If connection settings (username/password/clusterAPI) are provided in the Settings section below, then you need **AT LEAST** to provide caCrt and caKey. You can optionally provide a client certificate (caClient) depending on your cluster connection setup.
 
 Options:
 - **caCrt** : a valid S3/GCS/Azure bucket or local relative file path to a certificate file.
 - **caKey** : a valid S3/GCS/Azure bucket or local relative file path to a client key file.
 - **caClient**: a valid S3/GCS/Azure bucket or local relative file path to a client certificate file.
 
 
-> bucket format is: <s3 or gs or az>://bucket-name/dir1/dir2/.../file.extension
+> bucket format is: [s3 or gs or az]://bucket-name/dir1/dir2/.../file.extension
 
 Example:
 
@@ -75,19 +75,23 @@ certificates:
 
 ## Settings
 
-Optional : No.
+Optional : Yes. 
 
 Synopsis: provides settings for connecting to your k8s cluster and configuring Helm's Tiller in the cluster.
 
+> If you don't provide the `settings` stanza, helmsman would use your current kube context and will deploy Tiller(s) without RBAC service accounts.
+
 Options:
-- **kubeContext** : this is always required and defines what context to use in kubectl. Helmsman will try connect to this context first, if it does not exist, it will try to create it (i.e. connect to a k8s cluster) using the options below.
+- **kubeContext** : the kube context you want Helmsman to use or create. Helmsman will try connect to this context first, if it does not exist, it will try to create it (i.e. connect to a k8s cluster) using the options below.
 
-The following options can be skipped if your kubectl context is already created and you don't want Helmsman to connect kubectl to your cluster for you. When using Helmsman in CI pipeline, these details are required to connect to your cluster every time the pipeline is executed.
+The following options can be skipped if your kubectl context is already created and you don't want Helmsman to connect kubectl to your cluster for you. 
 
 - **username**   : the username to be used for kubectl credentials.
 - **password**   : an environment variable name (starting with `$`) where your password is stored. Get the password from your k8s admin or consult k8s docs on how to get/set it.
 - **clusterURI** : the URI for your cluster API or the name of an environment variable (starting with `$`) containing the URI.
-- **serviceAccount**: the name of the service account to use to initiate helm. This should have enough permissions to allow Helm to work and should exist already in the cluster. More details can be found in [helm's RBAC guide](https://github.com/kubernetes/helm/blob/master/docs/rbac.md)
+- **bearerToken**: whether you want helmsman to connect to the cluster using a bearer token. Default is `false`
+- **bearerTokenPath**: optional. If bearer token is used, you can specify a custom location for the token file.
+- **serviceAccount**: the name of the service account to use to deploy Helm Tiller. This should have enough permissions to allow Helm to work. If the service account does not exist, it will be created. More details can be found in [helm's RBAC guide](https://github.com/kubernetes/helm/blob/master/docs/rbac.md)
 - **storageBackend** : by default Helm stores release information in configMaps, using secrets is for storage is recommended for security. Setting this flag to `secret` will deploy/upgrade Tiller with the `--storage=secret`. Other values will be skipped and configMaps will be used.
 - **slackWebhook** : a [Slack](slack.com) Webhook URL to receive Helmsman notifications. This can be passed directly or in an environment variable.
 - **reverseDelete** : if set to `true` it will reverse the priority order whilst deleting.
@@ -220,11 +224,13 @@ namespaces:
 
 ## Helm Repos
 
-Optional : No.
+Optional : Yes.
 
 Synopsis: defines the Helm repos where your charts can be found. You can add as many repos as you like. Public repos can be added without any additional setup. Private repos require authentication.
 
-> AS of version v0.2.0, both AWS S3 and Google GCS buckets can be used for private repos (using the [Helm S3](https://github.com/hypnoglow/helm-s3) and [Helm GCS](https://github.com/nouney/helm-gcs) plugins).
+> As of version v0.2.0, both AWS S3 and Google GCS buckets can be used for private repos (using the [Helm S3](https://github.com/hypnoglow/helm-s3) and [Helm GCS](https://github.com/nouney/helm-gcs) plugins).
+
+> As of version v1.8.0, you can use private repos with basic auth and you can use pre-configured helm repos.
 
 Authenticating to private helm repos:
 - **For S3 repos**: you need to have valid AWS access keys in your environment variables. See [here](https://github.com/hypnoglow/helm-s3#note-on-aws-authentication) for more details.
@@ -233,7 +239,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.
+- 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. 
 
 Example:
 
@@ -243,6 +249,7 @@ stable = "https://kubernetes-charts.storage.googleapis.com"
 incubator = "http://storage.googleapis.com/kubernetes-charts-incubator"
 myS3repo = "s3://my-S3-private-repo/charts"
 myGCSrepo = "gs://my-GCS-private-repo/charts"
+myPrivateRepo = "https://user:[email protected]"
 ```
 
 ```yaml
@@ -251,6 +258,7 @@ helmRepos:
   incubator: "http://storage.googleapis.com/kubernetes-charts-incubator"
   myS3repo: "s3://my-S3-private-repo/charts"
   myGCSrepo: "gs://my-GCS-private-repo/charts"
+  myPrivateRepo: "https://user:[email protected]"
 ```
 
 ## Preconfigured Helm Repos
@@ -259,7 +267,7 @@ Optional : Yes.
 
 Synopsis: defines the list of helm repositories that the helmsman will consider already preconfigured and thus will not try to overwrite it's configuration.
 
-The primary use-case is if you have some helm repositories that require HTTP basic authentication and you don't want to store the password into the helmsman.yaml. In this case you can execute the following sequence to have those repositories configured:
+The primary use-case is if you have some helm repositories that require HTTP basic authentication and you don't want to store the password in the desired state file or as an environment variable. In this case you can execute the following sequence to have those repositories configured:
 
 Set up the helmsman configuration:
 

docs/how_to/README.md

@@ -0,0 +1,50 @@
+---
+version: v1.8.0
+---
+
+# How To Guides
+
+This page contains a list of guides on how to use Helmsman.
+
+- Connecting to Kubernetes clusters
+    - [Using an existing kube context](settings/existing_kube_context.md)
+    - [Using the current kube context](settings/current_kube_context.md)
+    - [Connecting with certificates](settings/creating_kube_context_with_certs.md)
+    - [Connecting with bearer token](settings/creating_kube_context_with_token.md)
+- Defining Namespaces    
+    - [Create namespaces](namespaces/create.md)
+    - [Label namespaces](namespaces/labels_and_annotations.md)
+    - [Set resource limits for namespaces](namespaces/limits.md)
+    - [Protecting namespaces](namespaces/protection.md)
+- Deploying Helm Tiller
+    - [Using existing Tillers](tiller/existing.md) 
+    - [Deploy shared Tiller in kube-system](tiller/shared.md)
+    - [Prevent Deploying Tiller in kube-system](tiller/prevent_tiller_in_kube_system.md)
+    - [Deploy Multiple Tillers with custom setup for each](tiller/multitenancy.md)
+    - [Deploy apps with specific Tillers](deploy_apps_with_specific_tiller.md)
+- Defining Helm repositories
+    - [Using default helm repos](helm_repos/default.md) 
+    - [Using private repos in Google GCS](helm_repos/gcs.md)
+    - [Using private repos in AWS S3](helm_repos/s3.md)    
+    - [Using private repos with basic auth](helm_repos/basic_auth.md)
+    - [Using pre-configured repos](helm_repos/pre_configured.md) 
+    - [Using local charts](helm_repos/local.md)
+- Manipulating Apps
+    - [Basic operations](apps/basic.md)
+    - [Passing secrets from env vars](apps/secrets.md)
+    - [Use multiple values files for apps](apps/multiple_values_files.md)
+    - [Protect releases (apps)](apps/protection.md)
+    - [Moving releases (apps) across namespaces](apps/moving_across_namespaces.md)
+    - [Override defined namespaces](apps/override_namespaces.md)
+    - [Run helm tests for deployed releases (apps)](apps/helm_tests.md)  
+    - [Define the order of apps operations](apps/order.md)  
+    - [Delete all releases (apps)](apps/destroy.md)
+- Running Helmsman in different environments
+    - [Running Helmsman in CI](deployment/ci.md)
+    - [Running Helmsman inside your k8s cluster](inside_k8s.md)
+- Misc
+    - [Authenticating to cloud storage providers](auth_to_storage_providers.md)
+    - [Send slack notifications from Helmsman](send_slack_notifications_from_helmsman.md)
+    - [Merge multiple desired state files](merge_desired_state_files.md)
+    - [Multitenant clusters guide](multitenant_clusters_guide.md)
+    - [Helmsman on Windows 10](helmsman_on_windows10.md)

docs/how_to/move_charts_across_namespaces.md → docs/how_to/apps/moving_across_namespaces.md

@@ -162,4 +162,5 @@ pvc-f791ef92-01ab-11e8-8a7e-02412acf5adc   20Gi       RWO           Retain
 
 Further details:
 https://github.com/kubernetes/kubernetes/issues/48609
-https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/
+https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/
+

docs/how_to/apps/protection.md

@@ -0,0 +1,31 @@
+---
+version: v1.8.0
+---
+
+# Protecting apps (releases)
+
+You can define apps to be protected using the `protected` field. Please check [this doc](../protect_namespaces_and_releases.md) for details about what protection means and the difference between namespace-level and release-level protection.
+
+Here is an example of a protected app:
+
+```toml
+[apps]
+
+    [apps.jenkins]
+    namespace = "staging"
+    enabled = true
+    chart = "stable/jenkins"
+    version = "0.9.1"
+    protected = true # defining this release to be protected.
+```
+
+```yaml
+apps:
+
+  jenkins:
+    namespace: "staging"
+    enabled: true
+    chart: "stable/jenkins"
+    version: "0.9.1"
+    protected: true # defining this release to be protected.
+```

docs/how_to/pass_secrets_from_env_variables.md → docs/how_to/apps/secrets.md

@@ -2,7 +2,7 @@
 version: v1.6.0
 ---
 
-# pass secrets from env. variables:
+# passing secrets from env variables:
 
 Starting from v0.1.3, Helmsman allows you to pass secrets and other user input to helm charts from environment variables as follows:
 
@@ -50,7 +50,8 @@ apps:
 
 These input variables will be passed to the chart when it is deployed/upgraded using helm's `--set <<var_name>>=<<var_value_read_from_env_var>>`
 
-You can also keep these environment variables in files, by default `helmsman` will load variables from a `.env` file but you can also specify files by using the `-e` option:
+# passing secrets from env files
+You can also keep these environment variables in files, by default Helmsman will load variables from a `.env` file but you can also specify files by using the `-e` option:
 
 ```bash
 helmsman -e myVars
@@ -70,3 +71,7 @@ Or you can do YAML(ish) style
 FOO: bar
 BAR: baz
 ```
+
+# passing secrets using helm secrets plugin
+
+You can also use the [helm secrets plugin](https://github.com/futuresimple/helm-secrets) to pass your secrets.

docs/how_to/auth_to_storage_providers.md

@@ -0,0 +1,29 @@
+---
+version: v1.8.0
+---
+
+# Authenticating to cloud storage providers
+
+Helmsman can read files like certificates for connecting to the cluster or TLS certificates for communicating with Tiller from some cloud storage providers; namely: GCS, S3 and Azure blob storage. Below is the authentication requirement for each provider:
+
+## AWS S3
+
+You need to provide ALL the following AWS env variables:
+
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `AWS_DEFAULT_REGION`
+
+## Google GCS
+
+You need to provide ONE of the following env variables:
+
+- `GOOGLE_APPLICATION_CREDENTIALS` the absolute path to your Google cloud credentials.json file.
+- Or, `GCLOUD_CREDENTIALS` the content of the credentials.json file.
+
+## Microsoft Azure
+
+You need to provide ALL of the following env variables:
+
+- `AZURE_STORAGE_ACCOUNT`
+- `AZURE_STORAGE_ACCESS_KEY`