From d3e4e9f4b14de2a030d0586e9511a30968adcc4f Mon Sep 17 00:00:00 2001 From: Matt Butcher Date: Wed, 20 Jul 2016 07:30:10 -0600 Subject: [PATCH] docs(README): update README with basic information The README reflected an earlier stage of project development. This update gives more useful "Why Helm?" documentation at the top, and updates several of the instructions to be more reflective of current status. --- README.md | 108 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 73 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index a16bf2706..7d1291f94 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,79 @@ Helm is a tool for managing Kubernetes charts. Charts are packages of pre-configured Kubernetes resources. -Features: +Use Helm to... + +- Find and use popular software packaged as Kubernetes charts +- Share your own applications as Kubernetes charts +- Create reproducible builds of your Kubernetes applications +- Intelligently manage your Kubernetes manifest files +- Manage releases of Helm packages + +## Helm in a Handbasket + +Helm is a tool that streamlines installing and managing Kubernetes applications. +Think of it like apt/yum/homebrew for Kubernetes. + +- Helm has two parts: a client (`helm`) and a server (`tiller`) +- Tiller runs inside of your Kubernetes cluster, and manages releases (installations) + of your charts. +- Helm runs on your laptop, CI/CD, or wherever you want it to run. +- Charts are Helm packages that contain at least two things: + - A description of the package (`Chart.yaml`) + - One or more templates, which contain Kubernetes manifest files +- Charts can be stored on disk, or fetched from remote chart repositories + (like Debian or RedHat packages) + +Using Helm is as easy as this: + +```console +$ helm init # Initialize Helm as well as the Tiller server +$ helm install docs/examples/alpine # Install the example Alpine chart +happy-panda # <-- That's the name of your release +$ helm list # List all releases +happy-panda +quiet-kitten +``` + +## Install + +Helm is in its early stages of development. At this time there are no binary +releases. + +To install Helm from source, follow this process: + +Make sure you have the prerequisites: +- Go 1.6 +- A running Kubernetes cluster +- `kubectl` properly configured to talk to your cluster +- [Glide](https://glide.sh/) 0.10 or greater with both git and mercurial installed. + +1. [Properly set your $GOPATH](https://golang.org/doc/code.html) +2. Clone (or otherwise download) this repository into $GOPATH/src/k8s.io/helm +3. Run `make bootstrap build` + +You will now have two binaries built: + +- `bin/helm` is the client +- `bin/tiller` is the server + +From here, you can run `bin/helm` and use it to install a recent snapshot of +Tiller. Helm will use your `kubectl` config to learn about your cluster. + +For development on Tiller, you can locally run Tiller, or you build a Docker +image (`make docker-build`) and then deploy it (`helm init -i IMAGE_NAME`). + +The [documentation](docs) folder contains more information about the +architecture and usage of Helm/Tiller. + +## The History of the Project + +Kubernetes Helm is the merged result of [Helm +Classic](https://github.com/helm/helm) and the Kubernetes port of GCS Deployment +Manager. The project was jointly started by Google and Deis, though it +is now part of the CNCF. + +Differences from Helm Classic: - Helm now has both a client (`helm`) and a server (`tiller`). The server runs inside of Kubernetes, and manages your resources. @@ -28,37 +100,3 @@ Features: - The Helm workspace is gone. You can now work anywhere on your filesystem that you want to work. -## Install - -Helm is in its early stages of development. At this time there are no -releases. - -To install Helm from source, follow this process: - -Make sure you have the prerequisites: -- Go 1.6 -- A running Kubernetes cluster -- `kubectl` properly configured to talk to your cluster -- [Glide](https://glide.sh/) 0.10 or greater with both git and mercurial installed. - -1. [Properly set your $GOPATH](https://golang.org/doc/code.html) -2. Clone (or otherwise download) this repository into $GOPATH/src/k8s.io/helm -3. Run `make bootstrap build` - -You will now have two binaries built: - -- `bin/helm` is the client -- `bin/tiller` is the server - -You can locally run Tiller, or you build a Docker image (`make -docker-build`) and then deploy it (`helm init -i IMAGE_NAME`). - -The [documentation](docs) folder contains more information about the -architecture and usage of Helm/Tiller. - -## The History of the Project - -Kubernetes Helm is the merged result of [Helm -Classic](https://github.com/helm/helm) and the Kubernetes port of GCS Deployment -Manager. The project was jointly started by Google and Deis, though it -is now part of the CNCF.