From 3e271a33b5c85fb6d34754fc38fc5c9c59fc39bc Mon Sep 17 00:00:00 2001 From: Sami Alajrami Date: Sun, 26 Nov 2017 11:58:39 +0100 Subject: [PATCH] updated docs for v0.1.3 --- README.md | 36 +++++++---- docs/how_to/define_namespaces.md | 38 ++++++++++++ docs/how_to/manipulate_apps.md | 38 +++++++++++- docs/how_to/move_charts_across_namespaces.md | 59 +++++++++++++++++++ .../how_to/pass_secrets_from env_variables.md | 29 +++++++++ docs/how_to/run_helmsman_in_ci.md | 2 +- .../run_helmsman_with_hosted_cluster.md | 12 ++-- docs/how_to/run_helmsman_with_minikube.md | 6 +- docs/how_to/test_charts.md | 25 ++++++++ docs/how_to/use_local_charts.md | 18 ++++++ docs/how_to/use_private_helm_charts.md | 29 +++++++++ 11 files changed, 270 insertions(+), 22 deletions(-) create mode 100644 docs/how_to/define_namespaces.md create mode 100644 docs/how_to/move_charts_across_namespaces.md create mode 100644 docs/how_to/pass_secrets_from env_variables.md create mode 100644 docs/how_to/test_charts.md create mode 100644 docs/how_to/use_local_charts.md create mode 100644 docs/how_to/use_private_helm_charts.md diff --git a/README.md b/README.md index 254a0f8b..5be67c8c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ --- -version: v0.1.2 +version: v0.1.3 --- # What is Helmsman? @@ -13,19 +13,33 @@ Helmsman was created to ease continous deployment of Helm charts. When you want # Features -- **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 executions due to a specific chart deployment failure, fix your helm chart and execute Helmsman again without needing to rollback the partial successes first. - **Built for CD**: Helmsman can be used as a docker image or a binary. - **Applications as code**: describe your desired applications and manage them from a single version-controlled declarative file. -- **Easy to use**: 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. +- **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. +- **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. + +# 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). +- [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). +- [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). +- [define namespaces to be used in your cluster](https://github.com/Praqma/helmsman/blob/master/docs/how_to/define_namespaces.md). +- [move charts across namespaces](https://github.com/Praqma/helmsman/blob/master/docs/how_to/move_charts_across_namespaces.md). + # Usage Helmsman can be used in three different settings: -- As a binary on local machine [with either a Minikube or a hosted cluster ]. See the docs [here](https://github.com/Praqma/helmsman/blob/master/docs/how_to/run_helmsman_with_minikube.md) for instructions on using Minikube and [here](https://github.com/Praqma/helmsman/blob/master/docs/how_to/run_helmsman_with_hosted_cluster.md) for using hosted cluster. -- As a docker image [in a CI system or local machine]. See the docs [here](https://github.com/Praqma/helmsman/blob/master/docs/how_to/run_helmsman_in_ci.md) for instructions. +- [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). + # How does it work? @@ -33,7 +47,7 @@ Helmsman uses a simple declarative [TOML](https://github.com/toml-lang/toml) fil The desired state file 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. Below is the result of executing the [example.toml](https://github.com/Praqma/helmsman/blob/master/example.toml) +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. To plan without executing: ``` $ helmsman -f example.toml ``` @@ -41,18 +55,20 @@ To plan without executing: To plan and execute the plan: ``` $ helmsman -apply -f example.toml ``` -To debug the planning: +To show debugging details: ``` $ helmsman -debug -apply -f example.toml ``` -Check the documentation for [how to manage an app from the desired state file](https://github.com/Praqma/helmsman/blob/master/docs/how_to/manipulate_apps.md). # Installation Install Helmsman for your OS from the [releases page](https://github.com/Praqma/Helmsman/releases). Available for Linux and MacOS. +Also available as a [docker image](https://hub.docker.com/r/praqma/helmsman/). + # Documentaion Documentation and How-Tos can be found [here](https://github.com/Praqma/helmsman/blob/master/docs/). # Contributing + Contribution and feeback/feature requests are welcome. \ No newline at end of file diff --git a/docs/how_to/define_namespaces.md b/docs/how_to/define_namespaces.md new file mode 100644 index 00000000..ea80937d --- /dev/null +++ b/docs/how_to/define_namespaces.md @@ -0,0 +1,38 @@ +--- +version: v0.1.3 +--- + +# define namespaces + +You can define namespaces to be used in your cluster. If they don't exist, Helmsman will create them for you. + +``` +... + +[namespaces] +staging = "staging" +production = "default" +myOtherNamespace = "namespaceX" + +... +``` + +You can then tell Helmsman to put specific releases in a specific namespace: + +``` +... +[apps] + + [apps.jenkins] + name = "jenkins" + description = "jenkins" + namespace = "myOtherNamespace" # this is the pointer to the namespace defined above -- i.e. it deploys to namespace 'namespaceX' + enabled = true + chart = "stable/jenkins" + version = "0.9.1" + valuesFile = "" + purge = false + test = true + +... +``` \ No newline at end of file diff --git a/docs/how_to/manipulate_apps.md b/docs/how_to/manipulate_apps.md index f17c1ee0..980e67cb 100644 --- a/docs/how_to/manipulate_apps.md +++ b/docs/how_to/manipulate_apps.md @@ -1,7 +1,8 @@ --- -version: v0.1.2 +version: v0.1.3 --- +# install releases You can run helmsman with the [example.toml](https://github.com/Praqma/helmsman/blob/master/example.toml) file. @@ -28,10 +29,14 @@ artifactory 1 Sun Nov 19 18:18:06 2017 DEPLOYED artifactory-6.2.0 staging jenkins 1 Sun Nov 19 18:18:03 2017 DEPLOYED jenkins-0.9.1 staging ``` +# delete releases + You can then change your desire, for example to disable the Jenkins release that was created above by setting `enabled = false` : 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. + ``` $ helmsman -apply -f example.toml 2017/11/19 18:28:27 Parsed [[ example.toml ]] successfully and found [ 2 ] apps. @@ -52,6 +57,30 @@ NAME REVISION UPDATED STATUS CHART NAMESPA artifactory 2 Sun Nov 19 18:29:11 2017 DEPLOYED artifactory-6.2.0 staging ``` +If you would like the release to be deleted along with its history, you can use the `purge` key in your desired state file as follows: + +> NOTE: purge deleting a release means you can't roll it back. + +``` +... +[apps] + + [apps.jenkins] + name = "jenkins" + description = "jenkins" + namespace = "staging" + enabled = false # this tells helmsman to delete it + chart = "stable/jenkins" + version = "0.9.1" + valuesFile = "" + purge = true # this means purge delete this release whenever it is required to be deleted + test = flase + +... +``` + +# rollback releases + Similarly, if you change `enabled` back to `true`, it will figure out that you would like to roll it back. ``` @@ -68,5 +97,10 @@ DECISION: release [ artifactory ] is desired to be upgraded. Planing this for yo 2017/11/19 18:30:50 INFO: attempting: -- upgrading release [ artifactory ] ``` -Similarly, You can also change the chart or chart version and specify a values.yaml file to override the default chart values. +# upgrade releases + +Everytime you run Helmsman, 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. + diff --git a/docs/how_to/move_charts_across_namespaces.md b/docs/how_to/move_charts_across_namespaces.md new file mode 100644 index 00000000..3b242693 --- /dev/null +++ b/docs/how_to/move_charts_across_namespaces.md @@ -0,0 +1,59 @@ +--- +version: v0.1.3 +--- + +# move charts across namespaces + +If you have a workflow for testing a release first in the `staging` namespace then move to the `production` namespace, Helmsman can help you. + +``` +... + +[namespaces] +staging = "staging" +production = "default" +myOtherNamespace = "namespaceX" + +[apps] + + [apps.jenkins] + name = "jenkins" + description = "jenkins" + namespace = "staging" # this is where it is deployed + enabled = true + chart = "stable/jenkins" + version = "0.9.1" + valuesFile = "" + purge = false + test = true + +... +``` + +Then if you change the namespace key for jenkins: + +``` +... + +[namespaces] +staging = "staging" +production = "default" +myOtherNamespace = "namespaceX" + +[apps] + + [apps.jenkins] + name = "jenkins" + description = "jenkins" + namespace = "production" # we want to move it to production + enabled = true + chart = "stable/jenkins" + version = "0.9.1" + valuesFile = "" + purge = false + test = true + +... +``` + +Helmsman will delete the jenkins release from the `staging` namespace and install it in the `production` namespace (default in the above setup). \ No newline at end of file diff --git a/docs/how_to/pass_secrets_from env_variables.md b/docs/how_to/pass_secrets_from env_variables.md new file mode 100644 index 00000000..1413ec76 --- /dev/null +++ b/docs/how_to/pass_secrets_from env_variables.md @@ -0,0 +1,29 @@ +--- +version: v0.1.3 +--- + +# pass 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: + +``` +... +[apps] + + [apps.jira] + name = "jira" + description = "jira" + namespace = "staging" + enabled = true + chart = "myrepo/jira" + version = "0.1.5" + valuesFile = "applications/jira-values.yaml" + purge = false + test = true + [apps.jira.set] # the format is [apps.<>.set] + db_username= "$JIRA_DB_USERNAME" # pass any number of key/value pairs where the key is the input expected by the helm charts and the value is an env variable name starting with $ + db_password= "$JIRA_DB_PASSWORD" +... +``` + +These input variables will be passed to the chart when it is deployed/upgraded using helm's `--set <>=<>` \ No newline at end of file diff --git a/docs/how_to/run_helmsman_in_ci.md b/docs/how_to/run_helmsman_in_ci.md index 64b65655..dd2b52bf 100644 --- a/docs/how_to/run_helmsman_in_ci.md +++ b/docs/how_to/run_helmsman_in_ci.md @@ -1,5 +1,5 @@ --- -version: v0.1.2 +version: v0.1.3 --- # Run Helmsman in CI diff --git a/docs/how_to/run_helmsman_with_hosted_cluster.md b/docs/how_to/run_helmsman_with_hosted_cluster.md index 6fba3216..00c55980 100644 --- a/docs/how_to/run_helmsman_with_hosted_cluster.md +++ b/docs/how_to/run_helmsman_with_hosted_cluster.md @@ -1,10 +1,10 @@ --- -version: v0.1.2 +version: v0.1.3 --- 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. Below is an example: -**IMPORTANT**: Only Certificates and private helm repos in S3 buckets are currently supported. Helmsman needs valid AWS access keys to be able to retrieve private charts or certificates from your s3 buckets. It expects the keys to be in the following environemnt variables: +**IMPORTANT**: Certificates can be used from S3 buckets or local file system. If you use s3 buckets, Helmsman needs valid AWS access keys to be able to retrieve private charts or certificates from your s3 buckets. It expects the keys to be in the following environemnt variables: - AWS_ACCESS_KEY_ID - AWS_SECRET_ACCESS_KEY @@ -19,8 +19,8 @@ maintainer = "k8s-admin" # Certificates are used to connect to the cluster. Currently, they can only be retrieved from s3 buckets. [certificates] -caCrt = "s3://your-bucket/ca.crt" -caKey = "s3://your-bucket/ca.key" +caCrt = "s3://your-bucket/ca.crt" # s3 bucket +caKey = "../../ca.key" # relative file path [settings] kubeContext = "mycontext" @@ -41,7 +41,7 @@ myrepo = "s3://my-private-repo/charts" [apps.jenkins] name = "jenkins" description = "jenkins" - env = "staging" + namespace = "staging" enabled = true chart = "stable/jenkins" version = "0.9.1" @@ -53,7 +53,7 @@ myrepo = "s3://my-private-repo/charts" [apps.artifactory] name = "artifactory" description = "artifactory" - env = "staging" + namespace = "staging" enabled = true chart = "stable/artifactory" version = "6.2.0" diff --git a/docs/how_to/run_helmsman_with_minikube.md b/docs/how_to/run_helmsman_with_minikube.md index ef9e969a..7ecd256b 100644 --- a/docs/how_to/run_helmsman_with_minikube.md +++ b/docs/how_to/run_helmsman_with_minikube.md @@ -1,5 +1,5 @@ --- -version: v0.1.2 +version: v0.1.3 --- 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. @@ -25,7 +25,7 @@ incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" [apps.jenkins] name = "jenkins" description = "jenkins" - env = "staging" + namespace = "staging" enabled = true chart = "stable/jenkins" version = "0.9.1" @@ -37,7 +37,7 @@ incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" [apps.artifactory] name = "artifactory" description = "artifactory" - env = "staging" + namespace = "staging" enabled = true chart = "stable/artifactory" version = "6.2.0" diff --git a/docs/how_to/test_charts.md b/docs/how_to/test_charts.md new file mode 100644 index 00000000..c38d6cc0 --- /dev/null +++ b/docs/how_to/test_charts.md @@ -0,0 +1,25 @@ +--- +version: v0.1.3 +--- + +# test charts + +You can specifiy that you would like a chart to be tested whenever it is installed for the first time using the `test` key as follows: + +``` +... +[apps] + + [apps.jenkins] + name = "jenkins" + description = "jenkins" + namespace = "staging" + enabled = true + chart = "stable/jenkins" + version = "0.9.1" + valuesFile = "" + purge = false + test = true # setting this to true, means you want the charts tests to be run on this release when it is intalled. + +... +``` \ No newline at end of file diff --git a/docs/how_to/use_local_charts.md b/docs/how_to/use_local_charts.md new file mode 100644 index 00000000..fc50ac72 --- /dev/null +++ b/docs/how_to/use_local_charts.md @@ -0,0 +1,18 @@ +--- +version: v0.1.3 +--- + +# use local helm charts + +You can use your locally developed charts. But first, you have to serve them on localhost using helm's `serve` option. + +``` +... + +[helmRepos] +stable = "https://kubernetes-charts.storage.googleapis.com" +incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" +local = http://127.0.0.1:8879 + +... +``` \ No newline at end of file diff --git a/docs/how_to/use_private_helm_charts.md b/docs/how_to/use_private_helm_charts.md new file mode 100644 index 00000000..582ee4c1 --- /dev/null +++ b/docs/how_to/use_private_helm_charts.md @@ -0,0 +1,29 @@ +--- +version: v0.1.3 +--- + +# use private helm charts + +Helmsman allows you to use private charts from private repos. Currently only repos hosted in S3 buckets are supported for private repos. +Other hosting options will be supported in the future. + +define your private repo: + +``` +... + +[helmRepos] +stable = "https://kubernetes-charts.storage.googleapis.com" +incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" +myPrivateRepo = s3://this-is-a-private-repo/charts + +... +``` + +If you are using S3 private repos, you need to provide the following AWS env variables: + +- AWS_ACCESS_KEY_ID +- AWS_SECRET_ACCESS_KEY +- AWS_DEFAULT_REGION + +Helmsman uses the [helm s3](https://github.com/hypnoglow/helm-s3) plugin to work with S3 helm repos. \ No newline at end of file