From 572af4ce1cb9aca84e82d90d961d2cec84323158 Mon Sep 17 00:00:00 2001 From: Sami Alajrami Date: Sun, 19 Nov 2017 19:19:52 +0100 Subject: [PATCH] close #5 updated docs. --- README.md | 106 ++++++------------ dockerfile/README.md | 14 ++- docs/desired_state_specification.md | 29 +++-- docs/how_to/manipulate_apps.md | 72 ++++++++++++ docs/how_to/run_helmsman_in_ci.md | 31 +++++ .../run_helmsman_with_hosted_cluster.md | 63 +++++++++++ docs/how_to/run_helmsman_with_minikube.md | 47 ++++++++ docs/why_helmsman.md | 14 ++- example.toml | 37 +++--- 9 files changed, 304 insertions(+), 109 deletions(-) create mode 100644 docs/how_to/manipulate_apps.md create mode 100644 docs/how_to/run_helmsman_in_ci.md create mode 100644 docs/how_to/run_helmsman_with_hosted_cluster.md create mode 100644 docs/how_to/run_helmsman_with_minikube.md diff --git a/README.md b/README.md index b81840a5..949add83 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,31 @@ +--- +version: v0.1.2 +--- + # What is Helmsman? -Helmsman is a Helm Charts as Code tool which adds another layer of abstraction on top of [Helm](https://helm.sh) (the [Kubernetes](https://kubernetes.io/) package manager). It allows you to automate the deployment/management of your Helm charts (k8s packaged applications). +Helmsman is a Helm Charts (k8s applications) as Code tool which adds a layer of abstraction on top of [Helm](https://helm.sh) (the [Kubernetes](https://kubernetes.io/) package manager). It allows you to automate the deployment/management of your Helm charts. # Why Helmsman? -Helmsman was created to ease continous deployment of Helm charts. When you want to configure a continous deployment pipeline to manage multiple charts deployed on your k8s cluster(s), a CI script will quickly become complex and difficult to maintain. That's where Helmsman comes to rescue. Read more about [how Helmsman can save you time and effort in the docs](https://github.com/Praqma/helmsman/blob/master/docs/why_helmsman.md). +Helmsman was created to ease continous deployment of Helm charts. When you want to configure a continous deployment pipeline to manage multiple charts deployed on your k8s cluster(s), a CI script will quickly become complex and difficult to maintain. That's where Helmsman comes to rescue. Read more about [how Helmsman can save you time and effort](https://github.com/Praqma/helmsman/blob/master/docs/why_helmsman.md). + + +# 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. + +# 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. # How does it work? @@ -15,76 +35,16 @@ The desired state file follows the [desired state specification](https://github. 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 -f example.toml -apply -2017/11/04 17:23:34 Parsed [[ example.toml ]] successfully and found [2] apps -2017/11/04 17:23:49 WARN: I could not create namespace [staging ]. It already exists. I am skipping this. -2017/11/04 17:23:49 WARN: I could not create namespace [default ]. It already exists. I am skipping this. ---------------- -Ok, I have generated a plan for you at: 2017-11-04 17:23:49.649943386 +0100 CET m=+14.976742294 -DECISION: release [ jenkins ] is currently deleted and is desired to be rolledback to namespace [[ staging ]] . No problem! -DECISION: release [ jenkins ] is required to be tested when installed/upgraded/rolledback. Got it! -DECISION: release [ vault ] is not present in the current k8s context. Will install it in namespace [[ staging ]] -DECISION: release [ vault ] is required to be tested when installed/upgraded/rolledback. Got it! -``` - -``` -$ helm list -NAME REVISION UPDATED STATUS CHART NAMESPACE -jenkins 1 Thu Nov 4 17:24:05 2017 DEPLOYED jenkins-0.9.0 staging -vault 1 Thu Nov 4 17:24:55 2017 DEPLOYED vault-0.1.0 staging -``` - -You can then change your desire, for example to disable the Jenkins release that was created above by setting `enabled = false` : - -``` -... -[apps.jenkins] - name = "jenkins" # should be unique across all apps - description = "jenkins" - env = "staging" # maps to the namespace as defined in environmetns above - enabled = false # change to false if you want to delete this app release [empty = flase] - chart = "stable/jenkins" # changing the chart name means delete and recreate this chart - version = "0.9.0" - valuesFile = "" # leaving it empty uses the default chart values - purge = false # will only be considered when there is a delete operation - test = true # run the tests whenever this release is installed/upgraded/rolledback -... - -``` - -Then run Helmsman again and it will detect that you want to delete Jenkins: - -``` -$ helmsman -f example.toml -apply -2017/11/04 17:25:29 Parsed [[ example.toml ]] successfully and found [2] apps -2017/11/04 17:25:44 WARN: I could not create namespace [staging ]. It already exists. I am skipping this. -2017/11/04 17:25:44 WARN: I could not create namespace [default ]. It already exists. I am skipping this. ---------------- -Ok, I have generated a plan for you at: 2017-11-04 17:23:44.649947467 +0100 CET m=+14.976746752 -DECISION: release [ jenkins ] is desired to be deleted and purged!. Planing this for you! -``` - -``` -$ helm list -NAME REVISION UPDATED STATUS CHART NAMESPACE -vault 1 Thu Nov 4 17:24:55 2017 DEPLOYED vault-0.1.0 staging -``` - -Similarly, if you change `enabled` back to `true`, it will figure out that you would like to roll it back. You can also change the chart or chart version and specify a values.yaml file to override the default chart values. - -# Usage - -Helmsman can be used in two ways: - -1. In a continuous deployment pipeline. Helmsman can be used in a docker container run by your CI system to maintain your desired state (which you can store in a version control repository). The docker image is available on [dockerhub](https://hub.docker.com/r/praqma/helmsman/). - -``` -docker run -it --rm -v /local/path/to/your/desired_state_file:/tmp praqma/helmsman -f tmp/example.toml -``` -> The latest docker image will contain the latest build of Helmsman. - -2. As a binary application. Helmsman dependes on [Helm](https://helm.sh) and [Kubectl](https://kubernetes.io/docs/user-guide/kubectl/) being installed. See below for installation. +To plan without executing: +``` $ helmsman -f example.toml ``` + +To plan and execute the plan: +``` $ helmsman -apply -f example.toml ``` + +To debug the planning: +``` $ 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 @@ -92,7 +52,7 @@ Install Helmsman for your OS from the [releases page](https://github.com/Praqma/ # Documentaion -Documentation can be found under the [docs](https://github.com/Praqma/helmsman/blob/master/docs/) directory. +Documentation and How-Tos can be found [here](https://github.com/Praqma/helmsman/blob/master/docs/). # Contributing Contribution and feeback/feature requests are welcome. Please check the [Contribution Guide](https://github.com/Praqma/helmsman/blob/master/CONTRIBUTING.md). \ No newline at end of file diff --git a/dockerfile/README.md b/dockerfile/README.md index b801a956..ae4fe3ca 100644 --- a/dockerfile/README.md +++ b/dockerfile/README.md @@ -1,7 +1,17 @@ +--- +version: v0.1.2 +--- + # Usage ``` -docker run -it --rm -v /local/path/to/your/desired_state_file:/tmp praqma/helmsman -f tmp/example.toml +docker run -v $(pwd):/tmp --rm -it \ +-e KUBECTL_PASSWORD= \ +-e AWS_ACCESS_KEY_ID= \ +-e AWS_DEFAULT_REGION= \ +-e AWS_SECRET_ACCESS_KEY= \ +praqma/helmsman:v0.1.2 \ +helmsman -debug -apply -f ``` -Check the different versions on [Dockerhub](https://hub.docker.com/r/praqma/helmsman/) \ No newline at end of file +Check the different image tags on [Dockerhub](https://hub.docker.com/r/praqma/helmsman/) \ No newline at end of file diff --git a/docs/desired_state_specification.md b/docs/desired_state_specification.md index c8bfbbc7..7432b5a5 100644 --- a/docs/desired_state_specification.md +++ b/docs/desired_state_specification.md @@ -1,9 +1,13 @@ +--- +version: v0.1.2 +--- + # Helmsman desired state specification This document describes the specification for how to write your Helm charts desired state file. The desired state file consists of: - [Metadata](#metadata) [Optional] -- metadata for any human reader of the desired state file. -- [Certifications](#certifications) [Optional] -- only needed when you want Helmsman to connect kubectl to your cluster for you. +- [Certificates](#certificates) [Optional] -- only needed when you want Helmsman to connect kubectl to your cluster for you. - [Settings](#settings) -- data about your k8s cluster. - [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. @@ -26,22 +30,22 @@ scope = "cluster foo" maintainer = "k8s-admin" ``` -## Certifications +## Certificates Optional : Yes, if you don't want Helmsman to connect kubectl to your cluster for you. Synopsis: defines where to find the certifactions needed for connecting kubectl to a k8s cluster. Options: -- caCrt : a valid path to a CRT file. -- caKey : a valid path to a key file. +- caCrt : a valid s3 bucket to a CRT file. +- caKey : a valid s3 bucket to a key file. Example: ``` -[certifications] -caCrt = "ca.crt" -caKey = "ca.key" +[certificates] +caCrt = "s3://mybucket/ca.crt" +caKey = "s3://mybucket/ca.key" ``` ## Settings @@ -56,7 +60,7 @@ Options: 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 everytime the pipeline is executed. - username : the username to be used for kubectl credentials. -- password : a path to a ".passwd" file containing the password to be used for kubectl credentials. Get the password from your k8s admin or consult k8s docs on how to get it. The .passwd file should be added to your .gitignore file in your git repo. +- 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 it. - clusterURI : the URI for your cluster API. Example: @@ -65,7 +69,7 @@ Example: [settings] kubeContext = "minikube" # username = "admin" -# password = "passwd.passwd" +# password = "$PASSWORD" # clusterURI = "https://192.168.99.100:8443" ``` @@ -93,7 +97,7 @@ Optional : No. Purpose: defines the Helm repos where your charts can be found. You can add as many repos as you like. Public repos do not require authentication. Private repos require authentication. -> Currently only AWS S3 buckets can be used for private repos (using the [Helm S3 plugin](https://github.com/hypnoglow/helm-s3)). For that 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. +> AS of version v0.1.2, only AWS S3 buckets can be used for private repos (using the [Helm S3 plugin](https://github.com/hypnoglow/helm-s3)). For that 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. Options: - you can define any key/value pairs. @@ -104,6 +108,7 @@ Example: [helmRepos] stable = "https://kubernetes-charts.storage.googleapis.com" incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" +myrepo = "s3://my-private-repo/charts" ``` ## Apps @@ -118,10 +123,10 @@ Options: - name : the Helm release name. Releases must have unique names within a cluster. - description : a release metadata for human readers. - env : the namespace where the release should be deployed. The namespace should map to one of the ones defined in [namespaces](#namespaces). -- enabled : describes the required state of the release (true for enabled, false for disabled). Change to false if you want to delete this app release [empty = flase]. +- enabled : describes the required state of the release (true for enabled, false for disabled). Once a release is deployed, you can change it to false if you want to delete this app release [empty = flase]. - chart : the chart name. It should contain the repo name as well. Example: repoName/chartName. Changing the chart name means delete and reinstall this release using the new Chart. - version : the chart version. -- valuesFile : a valid path to custom Helm values.yaml file. Leaving it empty uses the default chart values. +- 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. diff --git a/docs/how_to/manipulate_apps.md b/docs/how_to/manipulate_apps.md new file mode 100644 index 00000000..f17c1ee0 --- /dev/null +++ b/docs/how_to/manipulate_apps.md @@ -0,0 +1,72 @@ +--- +version: v0.1.2 +--- + + +You can run helmsman with the [example.toml](https://github.com/Praqma/helmsman/blob/master/example.toml) file. + +``` + +$ 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. +2017/11/19 18:18:02 INFO: Executing the following plan ... +--------------- +Ok, I have generated a plan for you at: 2017-11-19 18:17:59.347859706 +0100 CET m=+2.255430021 +DECISION: release [ jenkins ] is not present in the current k8s context. Will install it in namespace [[ staging ]] +DECISION: release [ artifactory ] is not present in the current k8s context. Will install it in namespace [[ staging ]] +2017/11/19 18:18:02 INFO: attempting: -- installing release [ jenkins ] in namespace [[ staging ]] +2017/11/19 18:18:05 INFO: attempting: -- installing release [ artifactory ] in namespace [[ staging ]] + +``` + +``` +$ helm list --namespace staging +NAME REVISION UPDATED STATUS CHART NAMESPACE +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 +``` + +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: + +``` +$ 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. +2017/11/19 18:29:01 INFO: Executing the following plan ... +--------------- +Ok, I have generated a plan for you at: 2017-11-19 18:28:29.437061909 +0100 CET m=+1.987623555 +DECISION: release [ jenkins ] is desired to be deleted . Planing this for you! +DECISION: release [ artifactory ] is desired to be upgraded. Planing this for you! +2017/11/19 18:29:01 INFO: attempting: -- deleting release [ jenkins ] +2017/11/19 18:29:11 INFO: attempting: -- upgrading release [ artifactory ] +``` + +``` +$ helm list --namespace staging +NAME REVISION UPDATED STATUS CHART NAMESPACE +artifactory 2 Sun Nov 19 18:29:11 2017 DEPLOYED artifactory-6.2.0 staging +``` + +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 +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. +2017/11/19 18:30:49 INFO: Executing the following plan ... +--------------- +Ok, I have generated a plan for you at: 2017-11-19 18:30:43.108693039 +0100 CET m=+1.978435517 +DECISION: release [ jenkins ] is currently deleted and is desired to be rolledback to namespace [[ staging ]] . No problem! +DECISION: release [ artifactory ] is desired to be upgraded. Planing this for you! +2017/11/19 18:30:49 INFO: attempting: -- rolling back release [ jenkins ] +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. + diff --git a/docs/how_to/run_helmsman_in_ci.md b/docs/how_to/run_helmsman_in_ci.md new file mode 100644 index 00000000..64b65655 --- /dev/null +++ b/docs/how_to/run_helmsman_in_ci.md @@ -0,0 +1,31 @@ +--- +version: v0.1.2 +--- + +# Run Helmsman in CI + +You can run Helmsman as a job in your CI system using the [helmsman docker image](https://hub.docker.com/r/praqma/helmsman/). +The following example is a `config.yml` file for CircleCI but can be replicated for other CI systems. + +``` +version: 2 +jobs: + + deploy-apps: + docker: + - image: praqma/helmsman:v0.1.2 + steps: + - checkout + - run: + name: Deploy Helm Packages using helmsman + command: helmsman -debug -apply -f helmsman-deployments.toml + + +workflows: + version: 2 + build: + jobs: + - deploy-apps +``` + +The `helmsman-deployments.toml` is your desired state file which will version controlled in your git repo. \ No newline at end of file diff --git a/docs/how_to/run_helmsman_with_hosted_cluster.md b/docs/how_to/run_helmsman_with_hosted_cluster.md new file mode 100644 index 00000000..6fba3216 --- /dev/null +++ b/docs/how_to/run_helmsman_with_hosted_cluster.md @@ -0,0 +1,63 @@ +--- +version: v0.1.2 +--- + +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: + +- AWS_ACCESS_KEY_ID +- AWS_SECRET_ACCESS_KEY +- AWS_DEFAULT_REGION + +Also, the K8S user password is expected in an environment variable which you can give any name you want and define it in your desired state file. + +``` +[metadata] +org = "orgX" +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" + +[settings] +kubeContext = "mycontext" +username = "<>" +password = "$PASSWORD" # the name of an environment variable containing the k8s password +clusterURI = "<>" # cluster API + +[namespaces] +staging = "staging" + +[helmRepos] +stable = "https://kubernetes-charts.storage.googleapis.com" +incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" +myrepo = "s3://my-private-repo/charts" + +[apps] + + [apps.jenkins] + name = "jenkins" + description = "jenkins" + env = "staging" + enabled = true + chart = "stable/jenkins" + version = "0.9.1" + valuesFile = "" + purge = false + test = false + + + [apps.artifactory] + name = "artifactory" + description = "artifactory" + env = "staging" + enabled = true + chart = "stable/artifactory" + version = "6.2.0" + valuesFile = "" + purge = false + test = false +``` \ No newline at end of file diff --git a/docs/how_to/run_helmsman_with_minikube.md b/docs/how_to/run_helmsman_with_minikube.md new file mode 100644 index 00000000..ef9e969a --- /dev/null +++ b/docs/how_to/run_helmsman_with_minikube.md @@ -0,0 +1,47 @@ +--- +version: v0.1.2 +--- + +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. + + +``` +[metadata] +org = "orgX" +maintainer = "k8s-admin" + +[settings] +kubeContext = "minikube" + +[namespaces] +staging = "staging" + +[helmRepos] +stable = "https://kubernetes-charts.storage.googleapis.com" +incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" + +[apps] + + [apps.jenkins] + name = "jenkins" + description = "jenkins" + env = "staging" + enabled = true + chart = "stable/jenkins" + version = "0.9.1" + valuesFile = "" + purge = false + test = false + + + [apps.artifactory] + name = "artifactory" + description = "artifactory" + env = "staging" + enabled = true + chart = "stable/artifactory" + version = "6.2.0" + valuesFile = "" + purge = false + test = false +``` \ No newline at end of file diff --git a/docs/why_helmsman.md b/docs/why_helmsman.md index 5a88e3af..0f21d4df 100644 --- a/docs/why_helmsman.md +++ b/docs/why_helmsman.md @@ -1,11 +1,15 @@ +--- +version: v0.1.2 +--- + # Why Helmsman? This document describes the reasoning and need behind the inception of Helmsman. ## Before Helm -Helmsman was created with continous deployment automation 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 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. +Helmsman was created with continous 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. ![CI-pipeline-before-helm](images/CI-pipeline-before-helm.jpg) @@ -26,11 +30,11 @@ With all this in mind, we needed a flexible and dynamic solution that can let us ## 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 sets at 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, [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). -> The Helmsman user does not need to know much about Helm and possibly even about k8s. +> 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 container to process your desired state file whenever a commit is made to it. +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. ![CI-pipeline-helmsman](images/CI-pipeline-helmsman.jpg) diff --git a/example.toml b/example.toml index 56871015..b94fb0ff 100644 --- a/example.toml +++ b/example.toml @@ -1,3 +1,4 @@ +# version: v0.1.2 # metadata -- add as many key/value pairs as you want [metadata] org = "orgX" @@ -6,13 +7,13 @@ maintainer = "k8s-admin" # paths to the certificate for connecting to the cluster # You can skip this if you use Helmsman on a machine with kubectl already connected to your k8s cluster. [certificates] -# caCrt = "ca.crt" # s3 bucket path -# caKey = "ca.key" # Or, a path to the file location +# caCrt = "s3://mybucket/ca.crt" # s3 bucket path +# caKey = "s3://mybucket/ca.key" [settings] kubeContext = "minikube" # will try connect to this context first, if it does not exist, it will be created using the details below # username = "admin" -# password = "passwd.passwd" # read it from a .passwd file which you should make it ignored by git. +# password = "$PASSWORD" # the name of an environment variable containing the k8s password # clusterURI = "https://192.168.99.100:8443" # cluster API @@ -25,9 +26,11 @@ production = "default" # define any private/public helm charts repos you would like to get charts from # syntax: repo_name = "repo_url" +# only private repos hosted in s3 buckets are now supported [helmRepos] stable = "https://kubernetes-charts.storage.googleapis.com" incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" +#myrepo = "s3://my-private-repo/charts" # define the desired state of your applications helm charts # each contains the following: @@ -40,19 +43,19 @@ incubator = "http://storage.googleapis.com/kubernetes-charts-incubator" env = "staging" # maps to the namespace as defined in environmetns above enabled = true # change to false if you want to delete this app release [empty = flase] chart = "stable/jenkins" # changing the chart name means delete and recreate this chart - version = "0.9.0" + version = "0.9.1" # chart version valuesFile = "" # leaving it empty uses the default chart values purge = false # will only be considered when there is a delete operation - test = true # run the tests whenever this release is installed/upgraded/rolledback - - - # [apps.vault] - # name = "vault" # should be unique across all apps - # description = "vault" - # env = "staging" # maps to the namespace as defined in environmetns above - # enabled = true # change to false if you want to delete this app release [empty = flase] - # chart = "incubator/vault" # don't change the chart name, create a new release instead - # version = "0.1.0" - # valuesFile = "" # leaving it empty uses the default chart values - # purge = false # will only be considered when there is a delete operation - # test = true # run the tests whenever this release is installed/upgraded/rolledback + test = false # run the tests whenever this release is installed/upgraded/rolledback + + + [apps.vault] + name = "artifactory" # should be unique across all apps + description = "artifactory" + env = "staging" # maps to the namespace as defined in environmetns above + enabled = true # change to false if you want to delete this app release [empty = flase] + chart = "stable/artifactory" # changing the chart name means delete and recreate this chart + version = "6.2.0" # chart version + valuesFile = "" # leaving it empty uses the default chart values + purge = false # will only be considered when there is a delete operation + test = false # run the tests whenever this release is installed/upgraded/rolledback