github.com/appscode/helm@v3.0.0-alpha.1+incompatible/docs/faq.md (about) 1 # Frequently Asked Questions 2 3 This page provides help with the most common questions about Helm. 4 5 **We'd love your help** making this document better. To add, correct, or remove 6 information, [file an issue](https://github.com/helm/helm/issues) or 7 send us a pull request. 8 9 ## Changes since Helm 2 10 11 Here's an exhaustive list of all the major changes introduced in Helm 3. 12 13 ### Removal of Tiller 14 15 During the Helm 2 development cycle, we introduced Tiller. Tiller played an important role for teams working on a shared 16 cluster - it made it possible for multiple different operators to interact with the same set of releases. 17 18 With role-based access controls (RBAC) enabled by default in Kubernetes 1.6, locking down Tiller for use in a production 19 scenario became more difficult to manage. Due to the vast number of possible security policies, our stance was to 20 provide a permissive default configuration. This allowed first-time users to start experimenting with Helm and 21 Kubernetes without having to dive headfirst into the security controls. Unfortunately, this permissive configuration 22 could grant a user a broad range of permissions they weren’t intended to have. DevOps and SREs had to learn additional 23 operational steps when installing Tiller into a multi-tenant cluster. 24 25 After hearing how community members were using Helm in certain scenarios, we found that Tiller’s release management 26 system did not need to rely upon an in-cluster operator to maintain state or act as a central hub for Helm release 27 information. Instead, we could simply fetch information from the Kubernetes API server, render the Charts client-side, 28 and store a record of the installation in Kubernetes. 29 30 Tiller’s primary goal could be accomplished without Tiller, so one of the first decisions we made regarding Helm 3 was 31 to completely remove Tiller. 32 33 With Tiller gone, the security model for Helm is radically simplified. Helm 3 now supports all the modern security, 34 identity, and authorization features of modern Kubernetes. Helm’s permissions are evaluated using your [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/). 35 Cluster administrators can restrict user permissions at whatever granularity they see fit. Releases are still recorded 36 in-cluster, and the rest of Helm’s functionality remains. 37 38 ### Release Names are now scoped to the Namespace 39 40 With the removal of Tiller, the information about each release had to go somewhere. In Helm 2, this was stored in the 41 same namespace as Tiller. In practice, this meant that once a name was used by a release, no other release could use 42 that same name, even if it was deployed in a different namespace. 43 44 In Helm 3, release information about a particular release is now stored in the same namespace as the release itself. 45 This means that users can now `helm install wordpress stable/wordpress` in two separate namespaces, and each can be 46 referred with `helm list` by changing the current namespace context. 47 48 ### Go import path changes 49 50 In Helm 3, Helm switched the Go import path over from `k8s.io/helm` to `helm.sh/helm`. If you intend 51 to upgrade to the Helm 3 Go client libraries, make sure to change your import paths. 52 53 ### Capabilities 54 55 The `.Capabilities` built-in object available during the rendering stage has been simplified. 56 57 [Built-in Objects](chart_template_guide/builtin_objects.md) 58 59 ### Validating Chart Values with JSONSchema 60 61 A JSON Schema can now be imposed upon chart values. This ensures that values provided by the user follow the schema 62 laid out by the chart maintainer, providing better error reporting when the user provides an incorrect set of values for 63 a chart. 64 65 Validation occurs when any of the following commands are invoked: 66 67 * `helm install` 68 * `helm upgrade` 69 * `helm template` 70 * `helm lint` 71 72 See the documentation on [Schema files](charts.md#schema-files) for more information. 73 74 ### Consolidation of requirements.yaml into Chart.yaml 75 76 The Chart dependency management system moved from requirements.yaml and requirements.lock to Chart.yaml and Chart.lock, 77 meaning that charts that relied on the `helm dependency` subcommands will need some tweaking to work in Helm 3. 78 79 In Helm 2, this is how a requirements.yaml looked: 80 81 ``` 82 dependencies: 83 - name: mariadb 84 version: 5.x.x 85 repository: https://kubernetes-charts.storage.googleapis.com/ 86 condition: mariadb.enabled 87 tags: 88 - database 89 ``` 90 91 In Helm 3, the dependency is expressed the same way, but now from your Chart.yaml: 92 93 ``` 94 dependencies: 95 - name: mariadb 96 version: 5.x.x 97 repository: https://kubernetes-charts.storage.googleapis.com/ 98 condition: mariadb.enabled 99 tags: 100 - database 101 ``` 102 103 Charts are still downloaded and placed in the charts/ directory, so subcharts vendored into the charts/ directory will continue to work without modification. 104 105 ### Name (or --generate-name) is now required on install 106 107 In Helm 2, if no name was provided, an auto-generated name would be given. In production, this proved to be more of a 108 nuisance than a helpful feature. In Helm 3, Helm will throw an error if no name is provided with `helm install`. 109 110 For those who still wish to have a name auto-generated for you, you can use the `--generate-name` flag to create one for 111 you. 112 113 ### Pushing Charts to OCI Registries 114 115 At a high level, a Chart Repository is a location where Charts can be stored and shared. The Helm client packs and ships 116 Helm Charts to a Chart Repository. Simply put, a Chart Repository is a basic HTTP server that houses an index.yaml file 117 and some packaged charts. 118 119 While there are several benefits to the Chart Repository API meeting the most basic storage requirements, a few 120 drawbacks have started to show: 121 122 - Chart Repositories have a very hard time abstracting most of the security implementations required in a production environment. Having a standard API for authentication and authorization is very important in production scenarios. 123 - Helm’s Chart provenance tools used for signing and verifying the integrity and origin of a chart are an optional piece of the Chart publishing process. 124 - In multi-tenant scenarios, the same Chart can be uploaded by another tenant, costing twice the storage cost to store the same content. Smarter chart repositories have been designed to handle this, but it’s not a part of the formal specification. 125 - Using a single index file for search, metadata information, and fetching Charts has made it difficult or clunky to design around in secure multi-tenant implementations. 126 127 Docker’s Distribution project (also known as Docker Registry v2) is the successor to the Docker Registry project. Many 128 major cloud vendors have a product offering of the Distribution project, and with so many vendors offering the same 129 product, the Distribution project has benefited from many years of hardening, security best practices, and 130 battle-testing. 131 132 Please have a look at `helm help chart` and `helm help registry` for more information on how to package a chart and 133 push it to a Docker registry. 134 135 ### Removal of helm serve 136 137 `helm serve` ran a local Chart Repository on your machine for development purposes. However, it didn't receive much 138 uptake as a development tool and had numerous issues with its design. In the end, we decided to remove it and split it 139 out as a plugin. 140 141 ### Library chart support 142 143 Helm 3 supports a class of chart called a “library chart”. This is a chart that is shared by other charts, but does not 144 create any release artifacts of its own. A library chart’s templates can only declare `define` elements. Globally scoped 145 non-`define` content is simply ignored. This allows users to re-use and share snippets of code that can be re-used across 146 many charts, avoiding redundancy and keeping charts [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself). 147 148 Library charts are declared in the dependencies directive in Chart.yaml, and are installed and managed like any other 149 chart. 150 151 ``` 152 dependencies: 153 - name: mylib 154 version: 1.x.x 155 repository: quay.io 156 ``` 157 158 We’re very excited to see the use cases this feature opens up for chart developers, as well as any best practices that 159 arise from consuming library charts. 160 161 ### CLI Command Renames 162 163 In order to better align the verbiage from other package managers, `helm delete` was re-named to 164 `helm uninstall`. `helm delete` is still retained as an alias to `helm uninstall`, so either form 165 can be used. 166 167 In Helm 2, in order to purge the release ledger, the `--purge` flag had to be provided. This 168 functionality is now enabled by default. To retain the previous behaviour, use 169 `helm uninstall --keep-history`. 170 171 Additionally, several other commands were re-named to accommodate the same conventions: 172 173 - `helm inspect` -> `helm show` 174 - `helm fetch` -> `helm pull` 175 176 These commands have also retained their older verbs as aliases, so you can continue to use them in either form. 177 178 ## Installing 179 180 ### Why aren't there Debian/Fedora/... native packages of Helm? 181 182 We'd love to provide these or point you toward a trusted provider. If you're 183 interested in helping, we'd love it. This is how the Homebrew formula was 184 started. 185 186 ### Why do you provide a `curl ...|bash` script? 187 188 There is a script in our repository (`scripts/get`) that can be executed as 189 a `curl ..|bash` script. The transfers are all protected by HTTPS, and the script 190 does some auditing of the packages it fetches. However, the script has all the 191 usual dangers of any shell script. 192 193 We provide it because it is useful, but we suggest that users carefully read the 194 script first. What we'd really like, though, are better packaged releases of 195 Helm. 196 197 ### How do I put the Helm client files somewhere other than ~/.helm? 198 199 Set the `$HELM_HOME` environment variable, and then run `helm init`: 200 201 ```console 202 export HELM_HOME=/some/path 203 helm init --client-only 204 ``` 205 206 Note that if you have existing repositories, you will need to re-add them 207 with `helm repo add...`. 208 209 210 ## Uninstalling 211 212 ### I want to delete my local Helm. Where are all its files? 213 214 Along with the `helm` binary, Helm stores some files in `$HELM_HOME`, which is 215 located by default in `~/.helm`. 216 217 218 ## Troubleshooting 219 220 ### On GKE (Google Container Engine) I get "No SSH tunnels currently open" 221 222 ``` 223 Error: Error forwarding ports: error upgrading connection: No SSH tunnels currently open. Were the targets able to accept an ssh-key for user "gke-[redacted]"? 224 ``` 225 226 Another variation of the error message is: 227 228 229 ``` 230 Unable to connect to the server: x509: certificate signed by unknown authority 231 232 ``` 233 234 The issue is that your local Kubernetes config file must have the correct credentials. 235 236 When you create a cluster on GKE, it will give you credentials, including SSL 237 certificates and certificate authorities. These need to be stored in a Kubernetes 238 config file (Default: `~/.kube/config` so that `kubectl` and `helm` can access 239 them. 240 241 ### Why do I get a `unsupported protocol scheme ""` error when trying to pull a chart from my custom repo?** 242 243 (Helm < 2.5.0) This is likely caused by you creating your chart repo index without specifying the `--url` flag. 244 Try recreating your `index.yaml` file with a command like `helm repo index --url http://my-repo/charts .`, 245 and then re-uploading it to your custom charts repo. 246 247 This behavior was changed in Helm 2.5.0.