github.com/valdemarpavesi/helm@v2.9.1+incompatible/docs/chart_repository.md (about) 1 # The Chart Repository Guide 2 3 This section explains how to create and work with Helm chart repositories. At a 4 high level, a chart repository is a location where packaged charts can be 5 stored and shared. 6 7 The official chart repository is maintained by the 8 [Kubernetes Charts](https://github.com/kubernetes/charts), and we welcome 9 participation. But Helm also makes it easy to create and run your own chart 10 repository. This guide explains how to do so. 11 12 ## Prerequisites 13 14 * Go through the [Quickstart](quickstart.md) Guide 15 * Read through the [Charts](charts.md) document 16 17 ## Create a chart repository 18 19 A _chart repository_ is an HTTP server that houses an `index.yaml` file and 20 optionally some packaged charts. When you're ready to share your charts, the 21 preferred way to do so is by uploading them to a chart repository. 22 23 **Note:** For Helm 2.0.0, chart repositories do not have any intrinsic 24 authentication. There is an [issue tracking progress](https://github.com/kubernetes/helm/issues/1038) 25 in GitHub. 26 27 Because a chart repository can be any HTTP server that can serve YAML and tar 28 files and can answer GET requests, you have a plethora of options when it comes 29 down to hosting your own chart repository. For example, you can use a Google 30 Cloud Storage (GCS) bucket, Amazon S3 bucket, Github Pages, or even create your 31 own web server. 32 33 ### The chart repository structure 34 35 A chart repository consists of packaged charts and a special file called 36 `index.yaml` which contains an index of all of the charts in the repository. 37 Frequently, the charts that `index.yaml` describes are also hosted on the same 38 server, as are the [provenance files](provenance.md). 39 40 For example, the layout of the repository `https://example.com/charts` might 41 look like this: 42 43 ``` 44 charts/ 45 | 46 |- index.yaml 47 | 48 |- alpine-0.1.2.tgz 49 | 50 |- alpine-0.1.2.tgz.prov 51 ``` 52 53 In this case, the index file would contain information about one chart, the Alpine 54 chart, and provide the download URL `https://example.com/charts/alpine-0.1.2.tgz` 55 for that chart. 56 57 It is not required that a chart package be located on the same server as the 58 `index.yaml` file. However, doing so is often the easiest. 59 60 ### The index file 61 62 The index file is a yaml file called `index.yaml`. It 63 contains some metadata about the package, including the contents of a 64 chart's `Chart.yaml` file. A valid chart repository must have an index file. The 65 index file contains information about each chart in the chart repository. The 66 `helm repo index` command will generate an index file based on a given local 67 directory that contains packaged charts. 68 69 This is an example of an index file: 70 71 ``` 72 apiVersion: v1 73 entries: 74 alpine: 75 - created: 2016-10-06T16:23:20.499814565-06:00 76 description: Deploy a basic Alpine Linux pod 77 digest: 99c76e403d752c84ead610644d4b1c2f2b453a74b921f422b9dcb8a7c8b559cd 78 home: https://k8s.io/helm 79 name: alpine 80 sources: 81 - https://github.com/kubernetes/helm 82 urls: 83 - https://technosophos.github.io/tscharts/alpine-0.2.0.tgz 84 version: 0.2.0 85 - created: 2016-10-06T16:23:20.499543808-06:00 86 description: Deploy a basic Alpine Linux pod 87 digest: 515c58e5f79d8b2913a10cb400ebb6fa9c77fe813287afbacf1a0b897cd78727 88 home: https://k8s.io/helm 89 name: alpine 90 sources: 91 - https://github.com/kubernetes/helm 92 urls: 93 - https://technosophos.github.io/tscharts/alpine-0.1.0.tgz 94 version: 0.1.0 95 nginx: 96 - created: 2016-10-06T16:23:20.499543808-06:00 97 description: Create a basic nginx HTTP server 98 digest: aaff4545f79d8b2913a10cb400ebb6fa9c77fe813287afbacf1a0b897cdffffff 99 home: https://k8s.io/helm 100 name: nginx 101 sources: 102 - https://github.com/kubernetes/charts 103 urls: 104 - https://technosophos.github.io/tscharts/nginx-1.1.0.tgz 105 version: 1.1.0 106 generated: 2016-10-06T16:23:20.499029981-06:00 107 ``` 108 109 A generated index and packages can be served from a basic webserver. You can test 110 things out locally with the `helm serve` command, which starts a local server. 111 112 ```console 113 $ helm serve --repo-path ./charts 114 Regenerating index. This may take a moment. 115 Now serving you on 127.0.0.1:8879 116 ``` 117 118 The above starts a local webserver, serving the charts it finds in `./charts`. The 119 serve command will automatically generate an `index.yaml` file for you during 120 startup. 121 122 ## Hosting Chart Repositories 123 124 This part shows several ways to serve a chart repository. 125 126 ### Google Cloud Storage 127 128 The first step is to **create your GCS bucket**. We'll call ours 129 `fantastic-charts`. 130 131 ![Create a GCS Bucket](images/create-a-bucket.png) 132 133 Next, make your bucket public by **editing the bucket permissions**. 134 135 ![Edit Permissions](images/edit-permissions.png) 136 137 Insert this line item to **make your bucket public**: 138 139 ![Make Bucket Public](images/make-bucket-public.png) 140 141 Congratulations, now you have an empty GCS bucket ready to serve charts! 142 143 You may upload your chart repository using the Google Cloud Storage command line 144 tool, or using the GCS web UI. This is the technique the official Kubernetes 145 Charts repository hosts its charts, so you may want to take a 146 [peek at that project](https://github.com/kubernetes/charts) if you get stuck. 147 148 **Note:** A public GCS bucket can be accessed via simple HTTPS at this address 149 `https://bucket-name.storage.googleapis.com/`. 150 151 ### JFrog Artifactory 152 153 You can also set up chart repositories using JFrog Artifactory. 154 Read more about chart repositories with JFrog Artifactory [here](https://www.jfrog.com/confluence/display/RTF/Helm+Chart+Repositories) 155 156 ### Github Pages example 157 158 In a similar way you can create charts repository using GitHub Pages. 159 160 GitHub allows you to serve static web pages in two different ways: 161 162 - By configuring a project to serve the contents of its `docs/` directory 163 - By configuring a project to serve a particular branch 164 165 We'll take the second approach, though the first is just as easy. 166 167 The first step will be to **create your gh-pages branch**. You can do that 168 locally as. 169 170 ```console 171 $ git checkout -b gh-pages 172 ``` 173 174 Or via web browser using **Branch** button on your Github repository: 175 176 ![Create Github Pages branch](images/create-a-gh-page-button.png) 177 178 Next, you'll want to make sure your **gh-pages branch** is set as Github Pages, 179 click on your repo **Settings** and scroll down to **Github pages** section and 180 set as per below: 181 182 ![Create Github Pages branch](images/set-a-gh-page.png) 183 184 By default **Source** usually gets set to **gh-pages branch**. If this is not set by default, then select it. 185 186 You can use a **custom domain** there if you wish so. 187 188 And check that **Enforce HTTPS** is ticked, so the **HTTPS** will be used when 189 charts are served. 190 191 In such setup you can use **master branch** to store your charts code, and 192 **gh-pages branch** as charts repository, e.g.: 193 `https://USERNAME.github.io/REPONAME`. The demonstration [TS Charts](https://github.com/technosophos/tscharts) 194 repository is accessible at `https://technosophos.github.io/tscharts/`. 195 196 ### Ordinary web servers 197 198 To configure an ordinary web server to serve Helm charts, you merely need to do 199 the following: 200 201 - Put your index and charts in a directory that the server can serve 202 - Make sure the `index.yaml` file can be accessed with no authentication requirement 203 - Make sure `yaml` files are served with the correct content type (`text/yaml` or 204 `text/x-yaml`) 205 206 For example, if you want to serve your charts out of `$WEBROOT/charts`, make sure 207 there is a `charts/` directory in your web root, and put the index file and 208 charts inside of that folder. 209 210 211 ## Managing Chart Repositories 212 213 Now that you have a chart repository, the last part of this guide explains how 214 to maintain charts in that repository. 215 216 217 ### Store charts in your chart repository 218 219 Now that you have a chart repository, let's upload a chart and an index file to 220 the repository. Charts in a chart repository must be packaged 221 (`helm package chart-name/`) and versioned correctly (following 222 [SemVer 2](https://semver.org/) guidelines). 223 224 These next steps compose an example workflow, but you are welcome to use 225 whatever workflow you fancy for storing and updating charts in your chart 226 repository. 227 228 Once you have a packaged chart ready, create a new directory, and move your 229 packaged chart to that directory. 230 231 ```console 232 $ helm package docs/examples/alpine/ 233 $ mkdir fantastic-charts 234 $ mv alpine-0.1.0.tgz fantastic-charts/ 235 $ helm repo index fantastic-charts --url https://fantastic-charts.storage.googleapis.com 236 ``` 237 238 The last command takes the path of the local directory that you just created and 239 the URL of your remote chart repository and composes an `index.yaml` file inside the 240 given directory path. 241 242 Now you can upload the chart and the index file to your chart repository using 243 a sync tool or manually. If you're using Google Cloud Storage, check out this 244 [example workflow](chart_repository_sync_example.md) using the gsutil client. For 245 GitHub, you can simply put the charts in the appropriate destination branch. 246 247 ### Add new charts to an existing repository 248 249 Each time you want to add a new chart to your repository, you must regenerate 250 the index. The `helm repo index` command will completely rebuild the `index.yaml` 251 file from scratch, including only the charts that it finds locally. 252 253 However, you can use the `--merge` flag to incrementally add new charts to an 254 existing `index.yaml` file (a great option when working with a remote repository 255 like GCS). Run `helm repo index --help` to learn more, 256 257 Make sure that you upload both the revised `index.yaml` file and the chart. And 258 if you generated a provenance file, upload that too. 259 260 ### Share your charts with others 261 262 When you're ready to share your charts, simply let someone know what the URL of 263 your repository is. 264 265 From there, they will add the repository to their helm client via the `helm 266 repo add [NAME] [URL]` command with any name they would like to use to 267 reference the repository. 268 269 ```console 270 $ helm repo add fantastic-charts https://fantastic-charts.storage.googleapis.com 271 $ helm repo list 272 fantastic-charts https://fantastic-charts.storage.googleapis.com 273 ``` 274 275 If the charts are backed by HTTP basic authentication, you can also supply the 276 username and password here: 277 278 ```console 279 $ helm repo add fantastic-charts https://fantastic-charts.storage.googleapis.com --username my-username --password my-password 280 $ helm repo list 281 fantastic-charts https://fantastic-charts.storage.googleapis.com 282 ``` 283 284 **Note:** A repository will not be added if it does not contain a valid 285 `index.yaml`. 286 287 After that, your users will be able to search through your charts. After you've updated 288 the repository, they can use the `helm repo update` command to get the latest 289 chart information. 290 291 *Under the hood, the `helm repo add` and `helm repo update` commands are 292 fetching the index.yaml file and storing them in the 293 `$HELM_HOME/repository/cache/` directory. This is where the `helm search` 294 function finds information about charts.*