README.rst - salt-formulas/helm - Gitiles


 ============
 Helm formula
 ============

 This formula installs Helm client, installs Tiller on Kubernetes cluster and
 manages releases in it.

 Available States
 ===============

 The default state applied by this formula (e.g. if just applying `helm`) will
 apply the `helm.releases_managed` state.

 .. note:: For backward compatibility till release 2.0 was kept the state client.sls,
           which just re-call the helm.release_managed

 `kubectl_installed`
 ------------------

 Optionally installs the kubectl binary per the configured pillar values,
 such as the version of `kubectl` to install and the path where the binary should
 be installed.

 `kubectl_configured`
 ------------------

 Manages a kubectl configuration file and gce_token json file per the configured
 pillar values. Note that the available configuration values allow the path of
 the kube config file to be placed at a different location than the default
 installation path; this is recommended to avoid confusion if the kubectl
 binary on the minion might be manually used with multiple contexts.

 **includes**:
 * `kubectl_installed`

 `client_installed`
 ------------------

 Installs the helm client binary per the configured pillar values, such as where
 helm home should be, which version of the helm binary to install and that path
 for the helm binary.

 **includes**:
 * `kubectl_installed

 `tiller_installed`
 ------------------

 Optionally installs a Tiller deployment to the Kubernetes cluster per the
 `helm:client:tiller:install` pillar value. If the pillar value is set to
 install tiller to the cluster, the version of the tiller installation will
 match the version of the Helm client installed per the `helm:client:version`
 configuration parameter

 **includes**:
 * `client_installed`
 * `kubectl_configured`

 `repos_managed`
 ------------------

 Ensures the repositories configured per the pillar (and only those repositories)
 are registered at the configured helm home, and synchronizes the local cache
 with the remote repository with each state execution.

 **includes**:
 * `client_installed`

 `releases_managed`
 ------------------

 Ensures the releases configured with the pillar are in the expected state with
 the Kubernetes cluster. This state includes change detection to determine
 whether the pillar configurations match the release's state in the cluster.

 Note that changes to an existing release's namespace will trigger a deletion and
 re-installation of the release to the cluster.

 **includes**:
 * `client_installed`
 * `tiller_installed`
 * `kubectl_configured`
 * `repos_managed`

 Availale Modules
 ===============

 To view documentation on the available modules, run:

 `salt '{{ tgt }}' sys.doc helm`


 Sample pillars
 ==============

 See the [default reclass pillar configuration](metadata/service/client.yml) for
 a documented example pillar file.

 Example Configurations
 ======================

 _The following examples demonstrate configuring the formula for different
 use cases._

 The default pillar configuration will install the helm client on the target
 node, and Tiller to the Kubernetes cluster (assuming kubectl config or local
 cluster endpoint have already been configured.

 Change version of helm being downloaded and installed:

 .. code-block:: yaml

     helm:
       client:
         version: 2.6.0  # defaults to 2.6.2 currently
         download_hash: sha256=youneedtocalculatehashandputithere

 Don't install tiller and use existing one exposed on some well-known address:

 .. code-block:: yaml

     helm:
       client:
         tiller:
           install: false
           host: 10.11.12.13:14151

 Change namespace where tiller is isntalled and looked for:

 .. code-block:: yaml

     helm:
       client:
         tiller:
           namespace: not-kube-system  # kube-system is default

 Install Mirantis repository and deploy zookeper chart from it:

 .. code-block:: yaml

     helm:
       client:
         repos:
           mirantisworkloads: https://mirantisworkloads.storage.googleapis.com/
         releases:
           zoo1:
             name: my-zookeeper
             chart: mirantisworkloads/zookeeper  # we reference installed repo
             version: 1.2.0  # select any available version
             values:
               logLevel: INFO  # any values used by chart can specified here

 Delete that release:

 .. code-block:: yaml

     helm:
       client:
         repos:
           mirantisworkloads: https://mirantisworkloads.storage.googleapis.com/
         releases:
           zoo1:
             enabled: false

 Install kubectl and manage remote cluster:

 .. code-block:: yaml

     helm:
       client:
         kubectl:
           install: true  # installs kubectl 1.6.7 by default
           config:
             # directly translated to cluster definition in kubeconfig
             cluster:
               server: https://kubernetes.example.com
               certificate-authority-data: base64_of_ca_certificate
             cluster_name: kubernetes.example
             # directly translated to user definition in kubeconfig
             user:
               username: admin
               password: uberadminpass
             user_name: admin

 Change kubectl download URL and use it with GKE-based cluster:

 .. code-block:: yaml

     helm:
       client:
         kubectl:
           install: true
           download_url: https://dl.k8s.io/v1.6.7/kubernetes-client-linux-amd64.tar.gz
           download_hash: sha256=calculate_hash_here
           config:
             # directly translated to cluster definition in kubeconfig
             cluster:
               server: https://3.141.59.265
               certificate-authority-data: base64_of_ca_certificate
             # directly translated to user definition in kubeconfig
             user:
               auth-provider:
                 name: gcp
             user_name: gce_user
             gce_service_token: base64_of_json_token_downloaded_from_cloud_console

 Known Issues
 ============

 1. Unable to remove all user supplied values

 If a release previously has had user supplied value overrides (via the
 release's `values` key in the pillar), subsequently removing all `values`
 overrides (so that there is no more `values` key for the release in the
 pillar) will not actually update the Helm deployment. To get around this,
 specify a fake key/value pair in the release's pillar; Tiller will override
 all previously user-supplied values with the new fake key and value. For
 example:


 .. code-block:: yaml
     helm:
       client:
         releases:
           zoo1:
             enabled: true
             ...
             values:
               fake_key: fake_value


 More Information
 ================

 * https://github.com/kubernetes/charts
 * https://fabric8.io/helm/


 Documentation and Bugs
 ======================

 To learn how to install and update salt-formulas, consult the documentation
 available online at:

     http://salt-formulas.readthedocs.io/

 In the unfortunate event that bugs are discovered, they should be reported to
 the appropriate issue tracker. Use Github issue tracker for specific salt
 formula:

     https://github.com/salt-formulas/salt-formula-helm/issues

 For feature requests, bug reports or blueprints affecting entire ecosystem,
 use Launchpad salt-formulas project:

     https://launchpad.net/salt-formulas

 You can also join salt-formulas-users team and subscribe to mailing list:

     https://launchpad.net/~salt-formulas-users

 Developers wishing to work on the salt-formulas projects should always base
 their work on master branch and submit pull request against specific formula.

     https://github.com/salt-formulas/salt-formula-home-assistant

 Any questions or feedback is always welcome so feel free to join our IRC
 channel:

     #salt-formulas @ irc.freenode.net

	============
	Helm formula
	============

	This formula installs Helm client, installs Tiller on Kubernetes cluster and
	manages releases in it.

	Available States
	===============

	The default state applied by this formula (e.g. if just applying `helm`) will
	apply the `helm.releases_managed` state.

	.. note:: For backward compatibility till release 2.0 was kept the state client.sls,
	which just re-call the helm.release_managed

	`kubectl_installed`
	------------------

	Optionally installs the kubectl binary per the configured pillar values,
	such as the version of `kubectl` to install and the path where the binary should
	be installed.

	`kubectl_configured`
	------------------

	Manages a kubectl configuration file and gce_token json file per the configured
	pillar values. Note that the available configuration values allow the path of
	the kube config file to be placed at a different location than the default
	installation path; this is recommended to avoid confusion if the kubectl
	binary on the minion might be manually used with multiple contexts.

	includes:
	* `kubectl_installed`

	`client_installed`
	------------------

	Installs the helm client binary per the configured pillar values, such as where
	helm home should be, which version of the helm binary to install and that path
	for the helm binary.

	includes:
	* `kubectl_installed

	`tiller_installed`
	------------------

	Optionally installs a Tiller deployment to the Kubernetes cluster per the
	`helm:client:tiller:install` pillar value. If the pillar value is set to
	install tiller to the cluster, the version of the tiller installation will
	match the version of the Helm client installed per the `helm:client:version`
	configuration parameter

	includes:
	* `client_installed`
	* `kubectl_configured`

	`repos_managed`
	------------------

	Ensures the repositories configured per the pillar (and only those repositories)
	are registered at the configured helm home, and synchronizes the local cache
	with the remote repository with each state execution.

	includes:
	* `client_installed`

	`releases_managed`
	------------------

	Ensures the releases configured with the pillar are in the expected state with
	the Kubernetes cluster. This state includes change detection to determine
	whether the pillar configurations match the release's state in the cluster.

	Note that changes to an existing release's namespace will trigger a deletion and
	re-installation of the release to the cluster.

	includes:
	* `client_installed`
	* `tiller_installed`
	* `kubectl_configured`
	* `repos_managed`

	Availale Modules
	===============

	To view documentation on the available modules, run:

	`salt '{{ tgt }}' sys.doc helm`


	Sample pillars
	==============

	See the [default reclass pillar configuration](metadata/service/client.yml) for
	a documented example pillar file.

	Example Configurations
	======================

	_The following examples demonstrate configuring the formula for different
	use cases._

	The default pillar configuration will install the helm client on the target
	node, and Tiller to the Kubernetes cluster (assuming kubectl config or local
	cluster endpoint have already been configured.

	Change version of helm being downloaded and installed:

	.. code-block:: yaml

	helm:
	client:
	version: 2.6.0 # defaults to 2.6.2 currently
	download_hash: sha256=youneedtocalculatehashandputithere

	Don't install tiller and use existing one exposed on some well-known address:

	.. code-block:: yaml

	helm:
	client:
	tiller:
	install: false
	host: 10.11.12.13:14151

	Change namespace where tiller is isntalled and looked for:

	.. code-block:: yaml

	helm:
	client:
	tiller:
	namespace: not-kube-system # kube-system is default

	Install Mirantis repository and deploy zookeper chart from it:

	.. code-block:: yaml

	helm:
	client:
	repos:
	mirantisworkloads: https://mirantisworkloads.storage.googleapis.com/
	releases:
	zoo1:
	name: my-zookeeper
	chart: mirantisworkloads/zookeeper # we reference installed repo
	version: 1.2.0 # select any available version
	values:
	logLevel: INFO # any values used by chart can specified here

	Delete that release:

	.. code-block:: yaml

	helm:
	client:
	repos:
	mirantisworkloads: https://mirantisworkloads.storage.googleapis.com/
	releases:
	zoo1:
	enabled: false

	Install kubectl and manage remote cluster:

	.. code-block:: yaml

	helm:
	client:
	kubectl:
	install: true # installs kubectl 1.6.7 by default
	config:
	# directly translated to cluster definition in kubeconfig
	cluster:
	server: https://kubernetes.example.com
	certificate-authority-data: base64_of_ca_certificate
	cluster_name: kubernetes.example
	# directly translated to user definition in kubeconfig
	user:
	username: admin
	password: uberadminpass
	user_name: admin

	Change kubectl download URL and use it with GKE-based cluster:

	.. code-block:: yaml

	helm:
	client:
	kubectl:
	install: true
	download_url: https://dl.k8s.io/v1.6.7/kubernetes-client-linux-amd64.tar.gz
	download_hash: sha256=calculate_hash_here
	config:
	# directly translated to cluster definition in kubeconfig
	cluster:
	server: https://3.141.59.265
	certificate-authority-data: base64_of_ca_certificate
	# directly translated to user definition in kubeconfig
	user:
	auth-provider:
	name: gcp
	user_name: gce_user
	gce_service_token: base64_of_json_token_downloaded_from_cloud_console

	Known Issues
	============

	1. Unable to remove all user supplied values

	If a release previously has had user supplied value overrides (via the
	release's `values` key in the pillar), subsequently removing all `values`
	overrides (so that there is no more `values` key for the release in the
	pillar) will not actually update the Helm deployment. To get around this,
	specify a fake key/value pair in the release's pillar; Tiller will override
	all previously user-supplied values with the new fake key and value. For
	example:


	.. code-block:: yaml
	helm:
	client:
	releases:
	zoo1:
	enabled: true
	...
	values:
	fake_key: fake_value


	More Information
	================

	* https://github.com/kubernetes/charts
	* https://fabric8.io/helm/


	Documentation and Bugs
	======================

	To learn how to install and update salt-formulas, consult the documentation
	available online at:

	http://salt-formulas.readthedocs.io/

	In the unfortunate event that bugs are discovered, they should be reported to
	the appropriate issue tracker. Use Github issue tracker for specific salt
	formula:

	https://github.com/salt-formulas/salt-formula-helm/issues

	For feature requests, bug reports or blueprints affecting entire ecosystem,
	use Launchpad salt-formulas project:

	https://launchpad.net/salt-formulas

	You can also join salt-formulas-users team and subscribe to mailing list:

	https://launchpad.net/~salt-formulas-users

	Developers wishing to work on the salt-formulas projects should always base
	their work on master branch and submit pull request against specific formula.

	https://github.com/salt-formulas/salt-formula-home-assistant

	Any questions or feedback is always welcome so feel free to join our IRC
	channel:

	#salt-formulas @ irc.freenode.net