From e0eb95be8625f4a0d0ffe35e887719b14c4821c0 Mon Sep 17 00:00:00 2001 From: Matt Butcher Date: Tue, 26 Apr 2016 15:49:15 -0600 Subject: [PATCH] docs(*): add arch, charts, and quickstart docs --- docs/architecture.md | 84 +++++++++++++++++++ docs/charts.md | 196 +++++++++++++++++++++++++++++++++++++++++++ docs/developers.md | 57 ++++++++++++- docs/quickstart.md | 75 +++++++++++++++++ 4 files changed, 409 insertions(+), 3 deletions(-) create mode 100644 docs/architecture.md create mode 100644 docs/charts.md create mode 100644 docs/quickstart.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 000000000..3cf6c186b --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,84 @@ +# The Kubernetes Helm Architecture + +This document describes the Helm architecture at a high level. + +## The Purpose of Helm + +Helm is a tool for managing Kubernetes packages called _charts_. Helm +can do the following: + +- Create new charts from scratch +- Package charts into chart archive (tgz) files +- Interact with chart repositories where charts are stored +- Install and uninstall charts into an existing Kubernetes cluster +- Manage the releases of charts that have been installed with Helm + +For Helm, there are three important concepts: + +1. The _chart_ is a bundle of information necessary to create an + instance of a Kubernetes application. +2. The _config_ contains configuration information that can be merged + into a packaged chart to create a releasable object. +3. A _release_ is a running instance of a _chart_, combined with a + specific _config_. + +Following the formula made famous by the 12 Factor App, _chart + config += release_. + +## Components + +Helm has two major components: + +**The Helm Client** is a command-line client for end users. The client +is responsible for the following domains: + +- Local chart development +- Managing repositories +- Interacting with the Tiller server + - Sending charts to be installed + - Asking for information about releases + - Requesting upgrading or uninstalling of existing releases + +**The Tiller Server** is an in-cluster server that interacts with the +Helm client, and interfaces with the Kubernetes API server. The server +is responsible for the following: + +- Listing for incomming requests from the Helm client +- Combining a chart and configuration to build a release +- Installing charts into Kubernetes, and then tracking the subsequent + release +- Upgrading and uninstalling charts by interacting with Kubernetes + +In a nutshell, the client is responsible for managing charts, and the +server is responsible for managing releases. + +## Implementation + +The Helm client is written in the Go programming language, and uses the +gRPC protocol suite to interact with the Tiller server. + +The Tiller server is also written in Go. It provides a gRPC server to +connect with the client, and it uses the Kubernetes client library to +communicate with Kubernetes. Currently, that library uses REST+JSON. + +The Tiller server stores information in ConfigMaps located inside of +Kubernetes. It does not need its own database. + +### Structure of the Code + +The individual programs are located in `cmd/`. Shared libraries are +stored in `pkg/`. The raw ProtoBuf files are stored in `_proto/hapi` +(where `hapi` stands for the Helm Application Programming Interface). +The Go files generated from the `proto` definitions are stored in +`pkg/proto`. + +Docker images are built by cross-compiling Linux binaries and then +building a Docker image from the files in `rootfs`. + +The `scripts/` directory contains a number of utility scripts, including +`local-cluster.sh`, which can start a full Kubernetes instance inside of +a Docker container. + +Go dependencies are managed with +[Glide](https://github.com/Masterminds/glide) and stored in the +`vendor/` directory. diff --git a/docs/charts.md b/docs/charts.md new file mode 100644 index 000000000..40f4b62f1 --- /dev/null +++ b/docs/charts.md @@ -0,0 +1,196 @@ +# Charts + +Helm uses a packaging format called _charts_. A chart is a collection of files +that collectively describe a set of Kubernetes resources. + +## The Chart File Structure + +A chart is organized as a collection of files inside of a directory. The +directory name is the name of the chart (without versioning information). Thus, +a chart describing Wordpress would be stored in the `wordpress/` directory. + +Inside of this directory, Helm will expect a structure that matches this: + +``` +wordpress/ + Chart.yaml # A YAML file containing information about the chart + LICENSE # A plain text file containing the license for the chart + README.md # A human-readable README file + values.toml # The default configuration values for this chart + charts/ # A directory containing any charts upon which this chart depends. + templates/ # A directory of templates that, when combined with values, + # will generate valid Kubernetes manifest files. +``` + +## The Chart.yaml File + +The Chart.yaml file is required for a chart. It contains the following fields: + +```yaml +name: The name of the chart (required) +version: A SemVer 2 version (required) +description: A single-sentence description of this project (optional) +keywords: + - A list of keywords about this project +home: The URL of this project's home page (optional) +sources: + - A list of URLs to source code for this project (optional) +maintainers: + - name: The maintainer's name + email: The maintainer's email +``` + +If you are familiar with the Chart.yaml file format for Helm Classic, you will +notice that fields specifying dependencies have been removed. That is because +the new Chart format expresses dependencies using the `charts/` directory. + +## Chart Dependencies + +In Helm, one chart may depend on any number of other charts. These +dependencies are expressed explicitly by copying the dependency charts +into the `charts/` directory. + +For example, if the Wordpress chart depends on the Apache chart, the +Apache chart (of the correct version) is supplied in the Wordpress +chart's `charts/` directory: + +``` +wordpress: + Chart.yaml + # ... + charts/ + apache/ + Chart.yaml + # ... + mysql/ + Chart.yaml + # ... +``` + +The example above shows how the Wordpress chart expresses its dependency +on Apache and MySQL by including those charts inside of its `charts/` +directory. + +## Templates and Values + +In Helm Charts, templates are written in the Go template language, with the +addition of 50 or so add-on template functions. + +All template files are stored in a chart's `templates/` folder. When +Helm renders the charts, it will pass every file in that directory +through the template engine. + +Values for the templates are supplied two ways: + - Chart developers may supply a file called `values.toml` inside of a + chart. This file can contain default values. + - Chart users may supply a TOML file that contains values. This can be + provided on the command line with `helm install`. + +When a user supplies custom values, these values will override the +values in the chart's `values.toml` file. + +### Template Files + +Template files follow the standard conventions for writing Go templates. +An example template file might look something like this: + +```yaml +apiVersion: v1 +kind: ReplicationController +metadata: + name: deis-database + namespace: deis + labels: + heritage: deis +spec: + replicas: 1 + selector: + app: deis-database + template: + metadata: + labels: + app: deis-database + spec: + serviceAccount: deis-database + containers: + - name: deis-database + image: {{.imageRegistry}}/postgres:{{.dockerTag}} + imagePullPolicy: {{.pullPolicy}} + ports: + - containerPort: 5432 + env: + - name: DATABASE_STORAGE + value: {{default "minio" .storage}} +``` + +The above example, based loosely on [https://github.com/deis/charts](the +chart for Deis), is a template for a Kubernetes replication controller. +It can use the following four template values: + +- `imageRegistry`: The source registry for the Docker image. +- `dockerTag`: The tag for the docker image. +- `pullPolicy`: The Kubernetes pull policy. +- `storage`: The storage backend, whose default is set to `"minio"` + +All of these values are defined by the template author. Helm does not +require or dictate parameters. + +### Values files + +Considering the template in the previous section, a `values.toml` file +that supplies the necessary values would look like this: + +```toml +imageRegistry = "quay.io/deis" +dockerTag = "latest" +pullPolicy = "alwaysPull" +storage = "s3" +``` + +When a chart includes dependency charts, values can be supplied to those +charts using TOML tables: + +```toml +imageRegistry = "quay.io/deis" +dockerTag = "latest" +pullPolicy = "alwaysPull" +storage = "s3" + +[router] +hostname = "example.com" +``` + +In the above example, the value of `hostname` will be passed to a chart +named `router` (if it exists) in the `charts/` directory. + +### References +- [Go templates](https://godoc.org/text/template) +- [Extra template functions](https://godoc.org/github.com/Masterminds/sprig) +- [The TOML format](https://github.com/toml-lang/toml) + +## Using Helm to Manage Charts + +The `helm` tool has several commands for working with charts. + +It can create a new chart for you: + +```console +$ helm create mychart +Created mychart/ +``` + +Once you have edited a chart, `helm` can package it into a chart archive +for you: + +```console +$ helm package mychart +Archived mychart-0.1.-.tgz +``` + +You can also use `helm` to help you find issues with your chart's +formatting or information: + +```console +$ helm lint mychart +No issues found +``` diff --git a/docs/developers.md b/docs/developers.md index 73edcfa52..ddea7e9ef 100644 --- a/docs/developers.md +++ b/docs/developers.md @@ -6,10 +6,33 @@ Helm and Tiller. ## Prerequisites - Go 1.6.0 or later +- Glide 0.10.2 or later - kubectl 1.2 or later - A Kubernetes cluster (optional) - The gRPC toolchain +## Building Helm/Tiller + +We use Make to build our programs. The simplest way to get started is: + +```console +$ make boostrap build +``` + +This will build both Helm and Tiller. + +To run all of the tests (without running the tests for `vendor/`), run +`make test`. + +To run Helm and Tiller locally, you can run `bin/helm` or `bin/tiller`. + +- Helm and Tiller are known to run on Mac OSX and most Linuxes, including + Alpine. +- Tiller must have access to a Kubernets cluster. It learns about the + cluster by examining the Kube config files that `kubectl` uese. + +## gRPC and Protobuf + Tiller uses gRPC. To get started with gRPC, you will need to... - Install `protoc` for compiling protobuf files. Releases are @@ -18,9 +41,37 @@ Tiller uses gRPC. To get started with gRPC, you will need to... Note that you need to be on protobuf 3.x (`protoc --version`) and use the latest Go plugin. -## The Helm API (HAPI) +### The Helm API (HAPI) -We use gRPC as an API layer. See `pkg/hapi` for the generated Go code, +We use gRPC as an API layer. See `pkg/proto/hapi` for the generated Go code, and `_proto` for the protocol buffer definitions. -To regenerate `hapi`, use `go generate pkg/hapi`. +To regenerate the Go files from the protobuf source, `cd _proto && +make`. + +## Docker Images + +To build Docker images, use `make docker-build` + +## Running a Local Cluster + +You can run tests locally using the `scripts/local-cluster.sh` script to +start Kubernetes inside of a Docker container. For OS X, you will need +to be running `docker-machine`. + +## Contribution Guidelines + +We welcome contributions. This project has set up some guidelines in +order to ensure that (a) code quality remains high, (b) the project +remains consistent, and (c) contributions follow the open source legal +requirements. Our intent is not to burden contributors, but to build +elegant and high-quality open source code so that our users will benefit. + +We follow the coding standards and guidelines outlined by the Deis +project: + +https://github.com/deis/workflow/blob/master/CONTRIBUTING.md +https://github.com/deis/workflow/blob/master/src/contributing/submitting-a-pull-request.md + +Adidtionally, contributors must have a CLA with CNCF/Google before we can +accept contributions. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 000000000..04b431f5b --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,75 @@ +# Quickstart Guide + +This guide covers how you can quickly get started using Helm. + +## Prerequisites + +- You must have Kubernetes installed, and have a local configured copy + of `kubectl`. + +## Install Helm + +Download a binary release of the Helm client from the official project +page. + +Alternately, you can clone the GitHub project and build your own +client from source. The quickest route to installing from source is to +run `make boostrap build`, and then use `bin/helm`. + +## Initialize Helm and Install Tiller + +Once you have Helm ready, you can initialize the local CLI and also +install Tiller into your Kubernetes cluster in one step: + +```console +$ helm init +``` + +## Install an Existing Chart + +To install an existing chart, you can run the `helm install` command: + +_TODO:_ Update this to the correct URL. + +```console +$ helm install https://helm.sh/charts/nginx-0.1.0.tgz +Released smiling-penguin +``` + +In the example above, the `nginx` chart was released, and the name of +our new release is `smiling-penguin` + +## Learn About The Release + +To find out about our release, run `helm status`: + +```console +$ helm status smiling-penguin +Status: DEPLOYED +``` + +## Uninstall a Release + +To remove a release, use the `helm remove` command: + +```console +$ helm remove smiling-penguin +Removed smiling-penguin +``` + +This will uninstall `smiling-penguin` from Kubernetes, but you will +still be able to request information about that release: + +```console +$ helm status smiling-penguin +Status: DELETED +``` + +## Reading the Help Text + +To learn more about the available Helm commands, use `helm help` or type +a command followed by the `-h` flag: + +```console +$ helm get -h +```