mirror of https://github.com/helm/helm
Merge pull request #62 from technosophos/docs/architecture
docs(*): add arch, charts, and quickstart docspull/613/head
Matt Butcher
9 years ago
commit
325d6b445f
@ -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.
|
||||
@ -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
|
||||
```
|
||||
@ -0,0 +1,4 @@
|
||||
# Helm Examples
|
||||
|
||||
This directory contains example charts to help you get started with
|
||||
chart development.
|
||||
@ -0,0 +1,4 @@
|
||||
name: alpine
|
||||
description: Deploy a basic Alpine Linux pod
|
||||
version: 0.1.0
|
||||
home: "https://github.com/deis/tiller"
|
||||
@ -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`.
|
||||
@ -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"]
|
||||
@ -0,0 +1,2 @@
|
||||
# The pod name
|
||||
name = "my-alpine"
|
||||
@ -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
|
||||
```
|
||||
Loading…
Reference in new issue