Merge pull request #62 from technosophos/docs/architecture

docs(*): add arch, charts, and quickstart docs

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.

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 (optional)
+home: The URL of this project's home page (optional)
+sources:
+  - A list of URLs to source code for this project (optional)
+maintainers: # (optional)
+  - name: The maintainer's name (required for each maintainer)
+    email: The maintainer's email (optional for each maintainer)
+```
+
+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
+```

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.

docs/examples/README.md

@@ -0,0 +1,4 @@
+# Helm Examples
+
+This directory contains example charts to help you get started with
+chart development.

docs/examples/alpine/Chart.yaml

@@ -0,0 +1,4 @@
+name: alpine
+description: Deploy a basic Alpine Linux pod
+version: 0.1.0
+home: "https://github.com/deis/tiller"

docs/examples/alpine/README.md

@@ -0,0 +1,9 @@
+This example was generated using the command `helm create alpine`.
+
+The `templates/` directory contains a very simple pod resource with a
+couple of parameters.
+
+The `values.toml` file contains the default values for the
+`alpine-pod.yaml` template.
+
+You can install this example using `helm install docs/examples/alpine`.

docs/examples/alpine/templates/alpine-pod.yaml

@@ -0,0 +1,12 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: {{default "alpine" .name}}
+  labels:
+    heritage: helm
+spec:
+  restartPolicy: {{default "Never" .restart_policy}}
+  containers:
+  - name: waiter
+    image: "alpine:3.3"
+    command: ["/bin/sleep","9000"]

docs/examples/alpine/values.toml

@@ -0,0 +1,2 @@
+# The pod name
+name = "my-alpine"

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
+```