diff --git a/docs/workflow/developer-workflows.md b/docs/workflow/developer-workflows.md index 249243a21..3cc1eb642 100644 --- a/docs/workflow/developer-workflows.md +++ b/docs/workflow/developer-workflows.md @@ -1,44 +1,220 @@ -# Helm/DM Developer Workflows +# Helm/DM Developer Experience Workflows -This document explains how Helm/DM can be used under different developer workflows. When we talk about _developer workflow_, we are interested in the process that Helm Chart developers undertake, moving from initially creating a chart to officially releasing a chart. +The purpose of this document is to outline the various workflows used in +our target use cases. It is broken into three major sections: + +- A section on the anticipated workflow patterns for the `helm` command line tool +- A section on development workflow models +- A section providing sample workflow implementations for the workflow + models + +The document is designed to address user experience, not the +implementation of the tools. ## tl;dr: The Workflows Helm and DM expose tools for creating, managing, and deploying charts. This document outlines those tools, and then provides several possible -workflows. +high-level workflows. -We envision four workflows, each satisfying different organizational needs. +We envision four high-level workflows, each satisfying different organizational needs. - Helm Official: The workflow used for contributing to the official Helm charts repository. - Public Unofficial: A public workflow used by another org - Private: Non-public repository - Private Development: Charts without repositories -Each of these workflows can be accommodated by the existing Helm tools and assumptions. +## Helm Workflows and User Experience + +In this section 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. + +#### 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. + +#### 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 list-params 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. + +#### Generate the params for me: + +In this operation, helm generates a parameter values file for the user. + +``` +$ helm gen-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 + +#### Deploy with params: + +In this operation, the user deploys a chart with an associated values +file. + +``` +$ helm deploy helm:example.com/foo/bar values.yaml +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. + +#### 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. + +#### Edit and redeploy: + +Redeployment is taking an existing _instance_ and changing its template +values, and then re-deploying it. + +``` +$ edit values.yaml +$ helm redeploy taco-tuesday values.yaml +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. + +#### Uninstall: + +``` +$ helm uninstall taco-tuesday +Destroyed taco-tuesday +``` + +- The client sends the DELETE instance name command +- The API server destroys the resource + +### 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 get-values 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) + +#### Get fully generated manifest files + +``` +$ helm get-manifests 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. + +### 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. + + +### Additional Helm Commands -## Workflow Capabilities +The following commands are not anticipated to be part of the daily +workflow, but do have occasional uses. Because they are less common, +many of these are grouped into sections of subcommands. -- `helm init`: Initialize the Helm client and server. The client initializes itself, - and can optionally install the DM manifests on a k8s cluster. - `helm dm install|uninstall|status|target`: Get information about a cluster. This is a mix of client and server activities. -- `helm create`: Create a new chart from scratch. This is a client-side action. -- `helm deploy`: Deploy a chart. The client packages the chart. The - server creates a deployment, expands templates, and then deploys. - `helm repo add|rm|list`: Manage repositories. The client pushes requests to the manager, which manages repositories. -- `helm lint`: Test that a chart conforms to the spec. This is client - side. - `helm doctor`: Fix client communication problems. -- `helm get` or `helm deployment get`: Get details about a deployed - application. - `helm package`: Package a directory into a chart. Client side. - `helm release`: Push a package to the repository. Client sends directly to repository. -- `helm describe`: Describe a deployment. Processed on the manager. - `helm list`: List deployments. Processed on the manager -- `helm delete`: Remove a deployment. Processed on the manager. - `helm search`: Search for available charts matching a given pattern. This is processed on the manager. @@ -47,9 +223,9 @@ broad characteristics of the four workflows. The Development Cycle section covers how the developer cycle plays out for each of the four workflows. -## An Overview of Four Workflows +## An Overview of Four Team Workflows -This section provides an introduction to the four workflows outline +This section provides an introduction to the four workflows outlined above, calling out characteristics of each workflow that define it against other workflows.