Rough-draft upgrade settings documentation [#8]

docs/upgrade_settings.yml

@@ -0,0 +1,87 @@
+---
+kind: pipeline
+type: docker
+name: default
+
+steps:
+  - name: deploy
+    image: pelotech/drone-helm3
+    settings:
+      # Setting helm_command to "upgrade" is recommended, but not mandatory. If no command is given, the plugin
+      # infers "upgrade" when triggered by a push, tag, deployment, pull_request, promote, or rollback event.
+      helm_command: upgrade
+
+      # Mandatory.
+      # The chart to use for this release.
+      chart: ./charts/bloge
+
+      # Mandatory.
+      # Release name for Helm to use.
+      release: bloge
+
+      # Mandatory.
+      # API endpoint for the Kubernetes cluster.
+      api_server: https://k8s.mycompany.example.com/clusters/c-tr1sb
+
+      # Mandatory.
+      # Token to use when connecting to kubernetes.
+      kubernetes_token:
+        from_secret: deploybot_token
+
+      # Base-64 encoded TLS certificate used by the Kubernetes cluster's certificate authority.
+      kubernetes_certificate: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t....
+
+      # Specific chart version to deploy.
+      chart_version: 1.2.3
+
+      # Simulate an upgrade without deploying it.
+      dry_run: true
+
+      # Wait until kubernetes resources are in a ready state before marking the release successful.
+      wait: true
+
+      # Timeout for any *individual* Kubernetes operation. The plugin's full runtime may exceed this duration.
+      timeout: 1m23s
+
+      # Force resource updates (helm upgrade --force).
+      force: true
+
+      # Values to set for this helm release. Keys and values must not contain commas.
+      values:
+        - image.tag=latest
+        - image.annotations.deployedDate="${DRONE_BUILD_CREATED}"
+
+      # String values to set for this helm release. Keys and values must not contain commas.
+      string_values: "notAnInt=5"
+
+      # Values files to use in this helm release. Filenames must not contain commas.
+      values_files:
+        - ./values/underrides.yml
+        - ./values/overrides.yml
+
+      # Reuse the values from a previous release.
+      reuse_values: true
+
+      # Put the kubernetes config file used for the deploy in an alternate location.
+      kube_config: /root/.spherernetes/config
+
+      # Produce debug output from drone-helm itself and send --debug to all helm commands.
+      debug: true
+
+      # Call `helm dependency update` before upgrading.
+      # Note: this setting is on the v1.0 roadmap, but not yet implemented.
+      update_dependencies: true
+
+      # Call `helm repo add` for each repo before upgrading. Repo names and urls must not contain commas.
+      # Note: this setting is on the v1.0 roadmap, but not yet implemented.
+      repos: "eDeath=https://github.com/bug/e-death,idMaker=https://github.com/nmarks/id-maker"
+
+      # Give the --namespace flag to all helm commands.
+      namespace: my_kube_subset
+
+      # Connect insecurely to the kubernetes server. Using this setting in production is inadvisable.
+      skip_tls_verify: true
+
+      # Service account to use when connecting to kubernetes. Defaults to "helm."
+      service_account: deploybot
+        from_secret: kubernetes_service_account

internal/helm/plan.go

@@ -67,6 +67,7 @@ func determineSteps(cfg Config) *func(Config) []Step {
 		return &help
 	default:
 		switch cfg.DroneEvent {
+		// Note: These events are documented in docs/upgrade_settings.yml. Any changes here should be reflected there.
 		case "push", "tag", "deployment", "pull_request", "promote", "rollback":
 			return &upgrade
 		case "delete":

internal/run/upgrade.go

@@ -25,6 +25,8 @@ func (u *Upgrade) Execute(_ Config) error {
 }
 
 // Prepare gets the Upgrade ready to execute.
+// Note: mandatory settings are documented in README.md, and the full list of settings is in docs/upgrade_settings.yml.
+// Any additions or deletions here should be reflected there.
 func (u *Upgrade) Prepare(cfg Config) error {
 	if u.Chart == "" {
 		return fmt.Errorf("chart is required")