helm/docs/workflow/developer-workflows.md

Helm/DM Developer Experience Workflows

This document outlines the individual workflows that Helm is designed to solve.

In this document we examine several workflows that we feel are central to the experience of deploying, managing, and building applications using Helm. Each workflow is followed by a basic model of where the processing of commands occurs.

User Workflow

The user workflow is the common case. This answers stories for the "tire kicker" and "standard user" personas.

Installation

Currently, the client can be used with no installation. However, installing the server side component is done like this:

$ helm dm install

• Client uses existing kubectl configuration to install built-in manifests.

General pattern:

helm dm install

Searching

$ helm search bar
helm:example.com/foo/bar - A basic chart
helm:example.com/foo/barracuda - A fishy chart
helm:example.com/foo/barbecue - A smoky chart

• Client submits the query to the manager
• Server searches the available chart repos

General pattern:

helm search PATTERN

Simple deployment:

$ helm deploy helm:example.com/foo/bar
Created wonky-panda

• The client sends the server a request to deploy helm:example.com/foo/bar.
• The server assigns a random name wonky-panda, fetches the chart from object storage, and goes about the deployment process.

General patterns:

helm deploy [-f CONFIG] [-n NAME] [CHART]

Find out about params:

In this operation, helm reads a chart and returns the list of parameters that can be supplied in a template:

$ helm chart show helm:example.com/foo/bar
Params:
- bgcolor: The background color for the home page (hex code or HTML colors)
- title: The title of the app

• The client sends the request to the API server
• The API server fetches the chart, analyzes it, and returns the list of parameters.

General pattern:

helm chart show CHART

Generate the params for me:

In this operation, helm generates a parameter values file for the user.

$ helm chart params helm:example.com/foo/bar
Created: values.yaml
$ edit values.yaml

• The client sends the request to the server
• The server returns a stub file
• The client writes the file to disk

General pattern:

helm chart params CHART [CHART...]

Deploy with params:

In this operation, the user deploys a chart with an associated values file.

$ helm deploy -f values.yaml helm:example.com/foo/bar 
Created taco-tuesday

• The client sends a request with the name of the chart and the values file.
• The API server generates a name (taco-tuesday)
• The API server fetches the request chart, sends the chart and values through the template resolution phase, and deploys the results.

If we allow the user to pass in a name (overriding the generated name), then the server must first guarantee that this name is unique.

Alternately, just the values file may be specified, since it contains a reference to the base chart.

$ helm deploy -f values.yaml
Created taco-wednesday

Get the info about named deployment.

A deployment, as we have seen, is a named instance of a chart. Operations that operate on these instances use the name to refer to the instance.

$ helm status taco-tuesday
OK
Located at: 10.10.10.77:8080

• The client sends the API server a request for the status of taco-tuesday.
• The API server looks up pertinent data and returns it.
• The client displays the data.

General pattern:

helm status NAME

Edit and redeploy:

Redeployment is taking an existing instance and changing its template values, and then re-deploying it.

$ edit values.yaml
$ helm redeploy -f values.yaml taco-tuesday
Redeployed taco-tuesday

• The client sends the instance name and the new values to the server
• The server coalesces the values into the existing instance and then restarts.

General pattern:

helm redeploy [-f CONFIG] NAME

Delete:

$ helm delete taco-tuesday
Destroyed taco-tuesday

• The client sends the DELETE instance name command
• The API server destroys the resource

General pattern:

helm uninstall NAME [NAME...]

Power User Features

Users familiar with the system may desire additional tools.

Name a deploy

$ helm deploy -name skinny-pigeon example.com/foo/bar

This follows the deployment process above. The server must ensure that the name is unique.

Get values for an app:

$ helm deployment params taco-tuesday
Stored in values.yaml
$ helm redeploy taco-tuesday values.yaml

• The client sends the instance name to the values endpoint
• The server returns the values file used to generate the instance.
• The client writes this to a file (or, perhaps, to STDOUT)

General pattern:

helm deployment params NAME [NAME...]

When more than one name is specified, the resulting file will contain configs for all names.

Get fully generated manifest files

$ helm deployment manifest taco-tuesday
Created manifest.yaml

• The client sends the instance name to the manifests endpoint
• The server returns the manifests, as generated during the deploy/redeploy cycle done prior.

General pattern:

helm deployment manifest NAME [NAME...]

Auto-detecting helm problems

$ helm doctor

• The client performs local diagnostics and diagnostics of Kubernetes and the DM server.

General pattern:

helm doctor

Listing all installed charts

$ helm chart list
helm:example.com/foo/bar#1.1.1 
helm:example.com/foo/bar#1.1.2
helm:example.com/foo/barbecue#0.1.0

• The client sends the server a request for all charts installed
• The server computes and responds

General pattern:

helm chart list

Get instances of a chart

NB: We might rename this helm chart instances, as that is less vague.

$ helm chart get helm:example.com/foo/bar 
taco-tuesday
taco-wednesday

• The client sends a request to the API server.
• The server responds with a list of deployment instance names.

This retrieves a shallow list, and does not inspect instances for ancestor charts.

General pattern:

helm chart get CHART

Listing deployments

$ helm deployment list
skinny-pigeon
taco-tuesday
taco-wednesday

• The client requests a list from the server
• The server returns the list

General pattern:

helm deployment list

Getting details of a deployment

NB: Might not need this.

$ helm deployment show skinny-pigeon
DETAILS

Developer Workflow

This section covers the experience of the chart developer.

In this case, when the client detects that it is working with a local chart, it bundles the chart, and sends the entire chart, not just the values.

$ helm create mychart
Created mychart/Chart.yaml
$ helm lint mychart
OK
$ helm deploy .
Uploading ./mychart as localchart/mychart-0.0.1.tgz
Created skinny-pigeon
$ helm status skinny-pigeon
OK
$ edit something
$ helm redeploy skinny-pigeon
Redeployed skinny-pigeon

• helm create and helm lint are client side operations
• helm deploy, helm status, and helm redeploy are explained above.

General pattern for create:

helm create [--from NAME] CHARTNAME

Where NAME will result in fetching the generated values from the cluster.

General pattern for lint:

helm lint PATH

Packaging and Releasing packages

Package a chart:

$ helm package .
Created foo-1.1.2.tgz

Releasing a chart:

$ helm release -u https://example.com/bucket ./foo-1.1.2.tgz
Uploaded to https://example.com/bucket/foo-1.1.2.tgz

General pattern:

helm package PATH
helm release [-u destination] PATH|FILE

Helm Cluster Management Commands

Install

$ helm dm install

• Client installs using the current kubectl configuration

General pattern:

helm dm install

Uninstall

$ helm dm uninstall

• The client interacts with the Kubernetes API server

General pattern:

helm dm uninstall

Check which cluster is the current target for helm

$ helm dm target
API Endpoint: https://10.21.21.21/

• The client interacts with the local Kubernetes config and the Kubernetes API server

General pattern:

helm search PATTERN

View status of DM service

$ helm dm status
OK

• The client interacts with the Kubernetes API server

General pattern:

helm dm status

Repository Configuration

Listing repositories

$ helm repo list

• The client request info from the server
• The server provides information about which repositories it is aware of

General pattern:

helm repo list

Adding credentials

$ helm credential add aff34... 89897a...
Created token-foo

• The client sends a request to the server
• The server creates a new token and returns a name

General pattern:

helm credential add TOKEN SECRET

Adding a repository with credentials

$ helm repo add -c token-foo https://example.com/charts

The URL is of the form PROTO://HOST[:PORT]/BUCKET.

General pattern:

helm repo add [-c TOKEN_NAME] REPO_URL

Removing repositories

$ helm repo rm https://example.com/charts

• The client sends a request to the server
• The server removes the repo from the known list

General pattern:

helm repo rm REPO_URL

Listing Credentials

$ helm credential list
token-foo: TOKEN

• The client requests a list of tokens
• The server returns the name and the token, but not the secret

General pattern:

helm credential list [PATTERN]

Removing credentials

$ helm credential rm token-foo

• The client sends a request to the server
• The server deletes the credential

General pattern:

helm credential rm CREDENTIAL_NAME