blob: 70ed425bdabb58840979b3c7a3d2ed7e5a351048 [file] [log] [blame]
Yuriy Taraday131227e2017-06-22 15:09:34 +04001
Ales Komarekba180382017-09-14 09:42:03 +02002============
3Helm formula
4============
Yuriy Taraday131227e2017-06-22 15:09:34 +04005
Yuriy Taraday434490c2017-08-22 17:40:01 +04006This formula installs Helm client, installs Tiller on Kubernetes cluster and
tmeneaud92f4742017-10-18 09:57:19 -04007manages releases in it.
8
Omer Katzdc445fb2017-11-21 16:03:44 +02009Available States
tmeneaud92f4742017-10-18 09:57:19 -040010===============
11
12The default state applied by this formula (e.g. if just applying `helm`) will
13apply the `helm.releases_managed` state.
14
Petr Michalec2d9dca92017-11-14 09:00:09 +010015.. note:: For backward compatibility till release 2.0 was kept the state client.sls,
16 which just re-call the helm.release_managed
17
tmeneaud92f4742017-10-18 09:57:19 -040018`kubectl_installed`
19------------------
20
21Optionally installs the kubectl binary per the configured pillar values,
Petr Michalec2d9dca92017-11-14 09:00:09 +010022such as the version of `kubectl` to install and the path where the binary should
tmeneaud92f4742017-10-18 09:57:19 -040023be installed.
24
25`kubectl_configured`
26------------------
27
28Manages a kubectl configuration file and gce_token json file per the configured
29pillar values. Note that the available configuration values allow the path of
Pavel Cizinsky183dab22018-12-12 12:01:56 +010030the kube config file to be placed at a different location than the default
31installation path; this is recommended to avoid confusion if the kubectl
tmeneaud92f4742017-10-18 09:57:19 -040032binary on the minion might be manually used with multiple contexts.
33
34**includes**:
35* `kubectl_installed`
36
37`client_installed`
38------------------
39
Pavel Cizinsky183dab22018-12-12 12:01:56 +010040Installs the helm client binary per the configured pillar values, such as where
tmeneaud92f4742017-10-18 09:57:19 -040041helm home should be, which version of the helm binary to install and that path
42for the helm binary.
43
44**includes**:
45* `kubectl_installed
46
47`tiller_installed`
48------------------
49
Petr Michalec2d9dca92017-11-14 09:00:09 +010050Optionally installs a Tiller deployment to the Kubernetes cluster per the
Pavel Cizinsky183dab22018-12-12 12:01:56 +010051`helm:client:tiller:install` pillar value. If the pillar value is set to
tmeneaud92f4742017-10-18 09:57:19 -040052install tiller to the cluster, the version of the tiller installation will
53match the version of the Helm client installed per the `helm:client:version`
54configuration parameter
55
56**includes**:
57* `client_installed`
58* `kubectl_configured`
59
60`repos_managed`
61------------------
62
Pavel Cizinsky183dab22018-12-12 12:01:56 +010063Ensures the repositories configured per the pillar (and only those repositories)
64are registered at the configured helm home, and synchronizes the local cache
tmeneaud92f4742017-10-18 09:57:19 -040065with the remote repository with each state execution.
66
67**includes**:
68* `client_installed`
69
70`releases_managed`
71------------------
72
73Ensures the releases configured with the pillar are in the expected state with
Pavel Cizinsky183dab22018-12-12 12:01:56 +010074the Kubernetes cluster. This state includes change detection to determine
tmeneaud92f4742017-10-18 09:57:19 -040075whether the pillar configurations match the release's state in the cluster.
76
Pavel Cizinsky183dab22018-12-12 12:01:56 +010077Note that changes to an existing release's namespace will trigger a deletion and
tmeneaud92f4742017-10-18 09:57:19 -040078re-installation of the release to the cluster.
79
80**includes**:
81* `client_installed`
82* `tiller_installed`
83* `kubectl_configured`
84* `repos_managed`
85
86Availale Modules
87===============
88
Pavel Cizinsky183dab22018-12-12 12:01:56 +010089To view documentation on the available modules, run:
tmeneaud92f4742017-10-18 09:57:19 -040090
91`salt '{{ tgt }}' sys.doc helm`
Yuriy Taraday131227e2017-06-22 15:09:34 +040092
Ales Komarekba180382017-09-14 09:42:03 +020093
Yuriy Taraday131227e2017-06-22 15:09:34 +040094Sample pillars
95==============
96
Pavel Cizinsky183dab22018-12-12 12:01:56 +010097See the [default reclass pillar configuration](metadata/service/client.yml) for
tmeneau42a2ccd2017-11-01 13:55:49 -040098a documented example pillar file.
tmeneaucf41dc32017-10-16 15:23:05 -040099
100Example Configurations
101======================
102
103_The following examples demonstrate configuring the formula for different
104use cases._
105
Pavel Cizinsky183dab22018-12-12 12:01:56 +0100106The default pillar configuration will install the helm client on the target
107node, and Tiller to the Kubernetes cluster (assuming kubectl config or local
tmeneau0f7e6d42017-10-16 17:18:29 -0400108cluster endpoint have already been configured.
Yuriy Taraday434490c2017-08-22 17:40:01 +0400109
110Change version of helm being downloaded and installed:
111
112.. code-block:: yaml
113
114 helm:
115 client:
tmeneaucf41dc32017-10-16 15:23:05 -0400116 version: 2.6.0 # defaults to 2.6.2 currently
Yuriy Taraday434490c2017-08-22 17:40:01 +0400117 download_hash: sha256=youneedtocalculatehashandputithere
118
119Don't install tiller and use existing one exposed on some well-known address:
120
121.. code-block:: yaml
122
123 helm:
124 client:
125 tiller:
126 install: false
127 host: 10.11.12.13:14151
128
129Change namespace where tiller is isntalled and looked for:
130
131.. code-block:: yaml
132
133 helm:
134 client:
135 tiller:
136 namespace: not-kube-system # kube-system is default
137
138Install Mirantis repository and deploy zookeper chart from it:
139
140.. code-block:: yaml
141
142 helm:
143 client:
144 repos:
145 mirantisworkloads: https://mirantisworkloads.storage.googleapis.com/
146 releases:
147 zoo1:
148 name: my-zookeeper
149 chart: mirantisworkloads/zookeeper # we reference installed repo
150 version: 1.2.0 # select any available version
151 values:
152 logLevel: INFO # any values used by chart can specified here
153
154Delete that release:
155
156.. code-block:: yaml
157
158 helm:
159 client:
160 repos:
161 mirantisworkloads: https://mirantisworkloads.storage.googleapis.com/
162 releases:
163 zoo1:
164 enabled: false
165
166Install kubectl and manage remote cluster:
167
168.. code-block:: yaml
169
170 helm:
171 client:
172 kubectl:
173 install: true # installs kubectl 1.6.7 by default
174 config:
tmeneaucf41dc32017-10-16 15:23:05 -0400175 # directly translated to cluster definition in kubeconfig
Pavel Cizinsky183dab22018-12-12 12:01:56 +0100176 cluster:
Yuriy Taraday434490c2017-08-22 17:40:01 +0400177 server: https://kubernetes.example.com
178 certificate-authority-data: base64_of_ca_certificate
tmeneaucf41dc32017-10-16 15:23:05 -0400179 cluster_name: kubernetes.example
180 # directly translated to user definition in kubeconfig
181 user:
Yuriy Taraday434490c2017-08-22 17:40:01 +0400182 username: admin
183 password: uberadminpass
Pavel Cizinsky183dab22018-12-12 12:01:56 +0100184 user_name: admin
Yuriy Taraday434490c2017-08-22 17:40:01 +0400185
186Change kubectl download URL and use it with GKE-based cluster:
187
188.. code-block:: yaml
189
190 helm:
191 client:
192 kubectl:
193 install: true
194 download_url: https://dl.k8s.io/v1.6.7/kubernetes-client-linux-amd64.tar.gz
195 download_hash: sha256=calculate_hash_here
196 config:
tmeneaucf41dc32017-10-16 15:23:05 -0400197 # directly translated to cluster definition in kubeconfig
198 cluster:
Yuriy Taraday434490c2017-08-22 17:40:01 +0400199 server: https://3.141.59.265
200 certificate-authority-data: base64_of_ca_certificate
tmeneaucf41dc32017-10-16 15:23:05 -0400201 # directly translated to user definition in kubeconfig
Yuriy Taraday434490c2017-08-22 17:40:01 +0400202 user:
203 auth-provider:
204 name: gcp
tmeneaucf41dc32017-10-16 15:23:05 -0400205 user_name: gce_user
Yuriy Taraday434490c2017-08-22 17:40:01 +0400206 gce_service_token: base64_of_json_token_downloaded_from_cloud_console
Yuriy Taraday131227e2017-06-22 15:09:34 +0400207
tmeneaud92f4742017-10-18 09:57:19 -0400208Known Issues
209============
210
2111. Unable to remove all user supplied values
212
Pavel Cizinsky183dab22018-12-12 12:01:56 +0100213If a release previously has had user supplied value overrides (via the
tmeneaud92f4742017-10-18 09:57:19 -0400214release's `values` key in the pillar), subsequently removing all `values`
Pavel Cizinsky183dab22018-12-12 12:01:56 +0100215overrides (so that there is no more `values` key for the release in the
tmeneaud92f4742017-10-18 09:57:19 -0400216pillar) will not actually update the Helm deployment. To get around this,
217specify a fake key/value pair in the release's pillar; Tiller will override
Pavel Cizinsky183dab22018-12-12 12:01:56 +0100218all previously user-supplied values with the new fake key and value. For
tmeneaud92f4742017-10-18 09:57:19 -0400219example:
220
221
222.. code-block:: yaml
223 helm:
224 client:
225 releases:
226 zoo1:
227 enabled: true
228 ...
229 values:
230 fake_key: fake_value
231
Yuriy Taraday131227e2017-06-22 15:09:34 +0400232
Ales Komarekba180382017-09-14 09:42:03 +0200233More Information
234================
Yuriy Taraday131227e2017-06-22 15:09:34 +0400235
Ales Komarekba180382017-09-14 09:42:03 +0200236* https://github.com/kubernetes/charts
237* https://fabric8.io/helm/