Skip to content

Commit

Permalink
close #5 updated docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
Sami Alajrami committed Nov 19, 2017
1 parent 99e6f95 commit 572af4c
Show file tree
Hide file tree
Showing 9 changed files with 304 additions and 109 deletions.
106 changes: 33 additions & 73 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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?

Expand All @@ -15,84 +35,24 @@ 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

Install Helmsman for your OS from the [releases page](https://github.com/Praqma/Helmsman/releases). Available for Linux and MacOS.

# 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).
14 changes: 12 additions & 2 deletions dockerfile/README.md
View file
Original file line number Diff line number Diff line change
@@ -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=<k8s_password> \
-e AWS_ACCESS_KEY_ID=<aws_key_id> \
-e AWS_DEFAULT_REGION=<aws_region> \
-e AWS_SECRET_ACCESS_KEY=<acess_key> \
praqma/helmsman:v0.1.2 \
helmsman -debug -apply -f <your_desired_state_file.toml>
```

Check the different versions on [Dockerhub](https://hub.docker.com/r/praqma/helmsman/)
Check the different image tags on [Dockerhub](https://hub.docker.com/r/praqma/helmsman/)
29 changes: 17 additions & 12 deletions docs/desired_state_specification.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -65,7 +69,7 @@ Example:
[settings]
kubeContext = "minikube"
# username = "admin"
# password = "passwd.passwd"
# password = "$PASSWORD"
# clusterURI = "https://192.168.99.100:8443"
```

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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.

Expand Down
72 changes: 72 additions & 0 deletions docs/how_to/manipulate_apps.md
View file
Original file line number Diff line number Diff line change
@@ -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.

31 changes: 31 additions & 0 deletions docs/how_to/run_helmsman_in_ci.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 572af4c

Please sign in to comment.