From 5e2f2f3dc60a1788387815f0825fba9af55ee944 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Thu, 19 Dec 2019 14:53:53 -0800 Subject: [PATCH 01/17] First draft of a useful README [#8] --- README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 04f55a3..aba89c8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,71 @@ # Drone plugin for Helm 3 -Dissatisfied with this empty README? Consider grabbing [the "put stuff in the README" issue](https://github.com/pelotech/drone-helm3/issues/8)! +This plugin provides an interface between [Drone](https://drone.io/) and [Helm 3](https://github.com/kubernetes/helm): + +* Lint your charts +* Deploy your service +* Delete your service + +The plugin is inpsired by [drone-helm](https://github.com/ipedrazas/drone-helm), which fills the same role for Helm 2. It provides a comparable feature-set and the configuration settings are backwards-compatible. + +## Example configuration + +These examples give a minimal and sufficient configuration for each use-case. For a full description of each case, see [docs/lint_example.yml](docs/lint_example.yml), [docs/upgrade_example.yml](docs/upgrade_example.yml), and [docs/delete_example.yml](docs/delete_example.yml). + +### Linting + +```yaml +steps: + - name: lint + image: pelotech/drone-helm3 + settings: + helm_command: lint + chart: ./ +``` + +### Deployment + +```yaml +steps: + - name: deploy + image: pelotech/drone-helm3 + settings: + helm_command: upgrade + chart: ./ + release: my-project + environment: + API_SERVER: https://my.kubernetes.installation/clusters/a-1234 + KUBERNETES_TOKEN: + from_secret: kubernetes_token +``` + +### Deletion + +```yaml +steps: + - name: delete + image: pelotech/drone-helm3 + settings: + helm_command: delete + release: my-project + environment: + API_SERVER: https://my.kubernetes.installation/clusters/a-1234 + KUBERNETES_TOKEN: + from_secret: kubernetes_token +``` + +## Upgrading from drone-helm + +The setting names for drone-helm3 are backwards-compatible with those for drone-helm, so the only mandatory step is to update the `image` clause so that drone uses the new plugin. + +There are several settings that no longer have any effect: + +* `purge` -- this is the default behavior in Helm 3 +* `recreate_pods` +* `tiller_ns` +* `upgrade` +* `canary_image` +* `client_only` +* `stable_repo_url` + +If your `.drone.yml` contains those settings, we recommend removing them. From 485eb4375c0b200af62ab0a7709134191f4f976e Mon Sep 17 00:00:00 2001 From: Erin Call Date: Thu, 19 Dec 2019 15:23:13 -0800 Subject: [PATCH 02/17] Rename "delete" to "uninstall" [#8] Helm 3 renamed the command, and I didn't realize it until just now. See also 161960e, where it was renamed in the code. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index aba89c8..0ff3b73 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The plugin is inpsired by [drone-helm](https://github.com/ipedrazas/drone-helm), ## Example configuration -These examples give a minimal and sufficient configuration for each use-case. For a full description of each case, see [docs/lint_example.yml](docs/lint_example.yml), [docs/upgrade_example.yml](docs/upgrade_example.yml), and [docs/delete_example.yml](docs/delete_example.yml). +These examples give a minimal and sufficient configuration for each use-case. For a full description of each case, see [docs/lint_example.yml](docs/lint_example.yml), [docs/upgrade_example.yml](docs/upgrade_example.yml), and [docs/uninstall_example.yml](docs/uninstall_example.yml). ### Linting @@ -43,10 +43,10 @@ steps: ```yaml steps: - - name: delete + - name: uninstall image: pelotech/drone-helm3 settings: - helm_command: delete + helm_command: uninstall release: my-project environment: API_SERVER: https://my.kubernetes.installation/clusters/a-1234 From 285af8a317e984320f24a6e88ebb5aac00e525a0 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Thu, 19 Dec 2019 16:37:04 -0800 Subject: [PATCH 03/17] Rough draft of an example lint stanza [#8] --- docs/lint_example.yml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/lint_example.yml diff --git a/docs/lint_example.yml b/docs/lint_example.yml new file mode 100644 index 0000000..677726b --- /dev/null +++ b/docs/lint_example.yml @@ -0,0 +1,36 @@ +--- +kind: pipeline +type: docker +name: default + +steps: + - name: lint + image: pelotech/drone-helm3 + settings: + # Helm_command must be set to "lint" in order to lint :) + helm_command: lint + + # Mandatory; must be a path to a chart directory. + chart: ./charts/bloge + + # Produce debug output from drone-helm itself and send --debug to all helm commands. + debug: true + + # The string given here will be passed verbatim to --set. + values: some=local,helm=values + + # The string given here will be passed verbatim to --set-string. + string_values: "notAnInt=5" + + # Each file will be passed to --values. Filenames must not contain commas. + values_files: "values/underrides.yml,values/overrides.yml" + + # Call `helm dependency update` before linting. + update_dependencies: true + + # Call `helm repo add` for each repo before linting. Repo names and urls must not contain commas. + repos: "eDeath=https://github.com/bug/e-death,idMaker=https://github.com/nmarks/id-maker" + + # Give the --namespace flag to all helm commands. + # TODO: I don't think this setting has any effect on linting; should it be documented? + namespace: my_kube_subset From 420014f9e5a89653eb69200dfe96e8fa935b5fb0 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Fri, 20 Dec 2019 09:41:36 -0800 Subject: [PATCH 04/17] Rename the setting description files to _settings [#8] --- README.md | 2 +- docs/{lint_example.yml => lint_settings.yml} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{lint_example.yml => lint_settings.yml} (100%) diff --git a/README.md b/README.md index 0ff3b73..c0505fb 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The plugin is inpsired by [drone-helm](https://github.com/ipedrazas/drone-helm), ## Example configuration -These examples give a minimal and sufficient configuration for each use-case. For a full description of each case, see [docs/lint_example.yml](docs/lint_example.yml), [docs/upgrade_example.yml](docs/upgrade_example.yml), and [docs/uninstall_example.yml](docs/uninstall_example.yml). +The examples below give a minimal and sufficient configuration for each use-case. For a full description of each command's settings, see [docs/lint_settings.yml](docs/lint_settings.yml), [docs/upgrade_settings.yml](docs/upgrade_settings.yml), and [docs/uninstall_settings.yml](docs/uninstall_settings.yml). ### Linting diff --git a/docs/lint_example.yml b/docs/lint_settings.yml similarity index 100% rename from docs/lint_example.yml rename to docs/lint_settings.yml From aed59c251e708665dfcabd884897cd1774be0bb6 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Fri, 20 Dec 2019 09:56:51 -0800 Subject: [PATCH 05/17] Namespace is relevant in helm lint [#8] ...Or at least, the namespace is passed around in helm's linting code. I haven't proven that there's a case where omitting the namespace can cause a linting problem, but I've seen enough to go ahead and document the setting. --- docs/lint_settings.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/lint_settings.yml b/docs/lint_settings.yml index 677726b..c47b30a 100644 --- a/docs/lint_settings.yml +++ b/docs/lint_settings.yml @@ -32,5 +32,4 @@ steps: repos: "eDeath=https://github.com/bug/e-death,idMaker=https://github.com/nmarks/id-maker" # Give the --namespace flag to all helm commands. - # TODO: I don't think this setting has any effect on linting; should it be documented? namespace: my_kube_subset From 197a377a8215c1ccd2c94d3e4c47c83feb7587af Mon Sep 17 00:00:00 2001 From: Erin Call Date: Fri, 20 Dec 2019 10:05:50 -0800 Subject: [PATCH 06/17] Prod maintainers to keep the docs and code in sync [#8] Offhand I don't see a way to ensure it programmatically, but I feel like I should at least make an attempt. --- internal/run/lint.go | 2 ++ 1 file changed, 2 insertions(+) diff --git a/internal/run/lint.go b/internal/run/lint.go index e2843ca..1993b49 100644 --- a/internal/run/lint.go +++ b/internal/run/lint.go @@ -16,6 +16,8 @@ func (l *Lint) Execute(_ Config) error { } // Prepare gets the Lint ready to execute. +// Note: mandatory settings are documented in README.md, and the full list of settings is in docs/lint_settings.yml. +// Any additions or deletions here should be reflected there. func (l *Lint) Prepare(cfg Config) error { if l.Chart == "" { return fmt.Errorf("chart is required") From cab3a8ae95d7e9752d9daa870d4df99e96b85862 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Fri, 20 Dec 2019 10:37:32 -0800 Subject: [PATCH 07/17] Advise that some settings aren't yet functional [#8] --- docs/lint_settings.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/lint_settings.yml b/docs/lint_settings.yml index c47b30a..b309b6e 100644 --- a/docs/lint_settings.yml +++ b/docs/lint_settings.yml @@ -26,9 +26,11 @@ steps: values_files: "values/underrides.yml,values/overrides.yml" # Call `helm dependency update` before linting. + # Note: this setting is on the v1.0 roadmap, but not yet implemented. update_dependencies: true # Call `helm repo add` for each repo before linting. 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. From dc4ecb6b91a5322003b1ff554919362793c9c4db Mon Sep 17 00:00:00 2001 From: Erin Call Date: Fri, 20 Dec 2019 16:09:57 -0800 Subject: [PATCH 08/17] Allow an empty Certificate setting [#29] I just plain misunderstood how kubernetes CAs worked! --- internal/run/initkube.go | 3 --- internal/run/initkube_test.go | 7 ------- 2 files changed, 10 deletions(-) diff --git a/internal/run/initkube.go b/internal/run/initkube.go index 4af29af..a341dca 100644 --- a/internal/run/initkube.go +++ b/internal/run/initkube.go @@ -50,9 +50,6 @@ func (i *InitKube) Prepare(cfg Config) error { if i.Token == "" { return errors.New("token is needed to deploy") } - if i.Certificate == "" && !i.SkipTLSVerify { - return errors.New("certificate is needed to deploy") - } if i.ServiceAccount == "" { i.ServiceAccount = "helm" diff --git a/internal/run/initkube_test.go b/internal/run/initkube_test.go index fb32b15..09dc4df 100644 --- a/internal/run/initkube_test.go +++ b/internal/run/initkube_test.go @@ -134,13 +134,6 @@ func (suite *InitKubeTestSuite) TestPrepareRequiredConfig() { init.APIServer = "Sysadmin" init.Token = "" suite.Error(init.Prepare(cfg), "Token should be required.") - - init.Token = "Aspire virtual currency" - init.Certificate = "" - suite.Error(init.Prepare(cfg), "Certificate should be required.") - - init.SkipTLSVerify = true - suite.NoError(init.Prepare(cfg), "Certificate should not be required if SkipTLSVerify is true") } func (suite *InitKubeTestSuite) TestPrepareDefaultsServiceAccount() { From 044caebafd48ea6c8ad44c232f69e7d7fa0ecf17 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Fri, 20 Dec 2019 16:14:17 -0800 Subject: [PATCH 09/17] Omit empty CA data from the kubeconfig [#29] --- kubeconfig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kubeconfig b/kubeconfig index c7b2025..92ec2c7 100644 --- a/kubeconfig +++ b/kubeconfig @@ -3,7 +3,7 @@ clusters: - cluster: {{- if eq .SkipTLSVerify true }} insecure-skip-tls-verify: true -{{- else }} +{{- else if .Certificate }} certificate-authority-data: {{ .Certificate }} {{- end}} server: {{ .APIServer }} From 3eb90651d1f3f6b3b31f0b95fc343239cdaf16a0 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Fri, 20 Dec 2019 16:07:05 -0800 Subject: [PATCH 10/17] Rough-draft upgrade settings documentation [#8] --- docs/upgrade_settings.yml | 87 +++++++++++++++++++++++++++++++++++++++ internal/helm/plan.go | 1 + internal/run/upgrade.go | 2 + 3 files changed, 90 insertions(+) create mode 100644 docs/upgrade_settings.yml diff --git a/docs/upgrade_settings.yml b/docs/upgrade_settings.yml new file mode 100644 index 0000000..5531509 --- /dev/null +++ b/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 diff --git a/internal/helm/plan.go b/internal/helm/plan.go index 1d4ced9..ffa3e52 100644 --- a/internal/helm/plan.go +++ b/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": diff --git a/internal/run/upgrade.go b/internal/run/upgrade.go index cff2c70..9f57e05 100644 --- a/internal/run/upgrade.go +++ b/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") From 3d1c849e75fbcb738c085203b4423bb554809bd6 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Mon, 23 Dec 2019 09:49:29 -0800 Subject: [PATCH 11/17] Don't document the kube_config setting [#8] See #30--there's no known use-case and no drone-helm users are using the setting, so it's on the chopping block. --- docs/upgrade_settings.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/upgrade_settings.yml b/docs/upgrade_settings.yml index 5531509..90cd49c 100644 --- a/docs/upgrade_settings.yml +++ b/docs/upgrade_settings.yml @@ -62,9 +62,6 @@ steps: # 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 From 59a591eda512deedf1165ffc863a81d76f8af28a Mon Sep 17 00:00:00 2001 From: Erin Call Date: Mon, 23 Dec 2019 09:57:05 -0800 Subject: [PATCH 12/17] Recommend removing tiller when upgrading [#8] --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c0505fb..3456f7d 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,11 @@ steps: The setting names for drone-helm3 are backwards-compatible with those for drone-helm, so the only mandatory step is to update the `image` clause so that drone uses the new plugin. -There are several settings that no longer have any effect: +There are some recommended changes, though: + +* If your `service_account` is currently `tiller`, change it to a service account with more restricted permissions. + * If possible, remove the tiller account entirely, since its superuser status presents a security risk. +* Remove outdated settings that have no effect in drone-helm3: * `purge` -- this is the default behavior in Helm 3 * `recreate_pods` @@ -67,5 +71,3 @@ There are several settings that no longer have any effect: * `canary_image` * `client_only` * `stable_repo_url` - -If your `.drone.yml` contains those settings, we recommend removing them. From ef66bc0f9210f458d3757d4fb22db0e7e5364b82 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Tue, 24 Dec 2019 14:36:39 -0800 Subject: [PATCH 13/17] Document parameters in a single markdown file [#8] I was unhappy with the comments-in-yaml approach; it required duplicating a lot of information and it was hard to find a balance between "usefully thorough" and "readably concise."" --- README.md | 2 +- docs/lint_settings.yml | 37 ---------- docs/parameter_reference.md | 133 ++++++++++++++++++++++++++++++++++++ docs/upgrade_settings.yml | 84 ----------------------- 4 files changed, 134 insertions(+), 122 deletions(-) delete mode 100644 docs/lint_settings.yml create mode 100644 docs/parameter_reference.md delete mode 100644 docs/upgrade_settings.yml diff --git a/README.md b/README.md index 3456f7d..b21ac90 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The plugin is inpsired by [drone-helm](https://github.com/ipedrazas/drone-helm), ## Example configuration -The examples below give a minimal and sufficient configuration for each use-case. For a full description of each command's settings, see [docs/lint_settings.yml](docs/lint_settings.yml), [docs/upgrade_settings.yml](docs/upgrade_settings.yml), and [docs/uninstall_settings.yml](docs/uninstall_settings.yml). +The examples below give a minimal and sufficient configuration for each use-case. For a full description of each command's settings, see [docs/parameter_reference.md](docs/parameter_reference.md). ### Linting diff --git a/docs/lint_settings.yml b/docs/lint_settings.yml deleted file mode 100644 index b309b6e..0000000 --- a/docs/lint_settings.yml +++ /dev/null @@ -1,37 +0,0 @@ ---- -kind: pipeline -type: docker -name: default - -steps: - - name: lint - image: pelotech/drone-helm3 - settings: - # Helm_command must be set to "lint" in order to lint :) - helm_command: lint - - # Mandatory; must be a path to a chart directory. - chart: ./charts/bloge - - # Produce debug output from drone-helm itself and send --debug to all helm commands. - debug: true - - # The string given here will be passed verbatim to --set. - values: some=local,helm=values - - # The string given here will be passed verbatim to --set-string. - string_values: "notAnInt=5" - - # Each file will be passed to --values. Filenames must not contain commas. - values_files: "values/underrides.yml,values/overrides.yml" - - # Call `helm dependency update` before linting. - # Note: this setting is on the v1.0 roadmap, but not yet implemented. - update_dependencies: true - - # Call `helm repo add` for each repo before linting. 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 diff --git a/docs/parameter_reference.md b/docs/parameter_reference.md new file mode 100644 index 0000000..288bd53 --- /dev/null +++ b/docs/parameter_reference.md @@ -0,0 +1,133 @@ +# Parameter reference + +## Something here about how to specify non-string types + +* boolean +* list\ +* duration + +## Mention that everything can be settings or environment + +## Global +| Param name | Type | Purpose | +|---------------------|-----------------|---------| +| helm_command | string | Indicates the operation to perform. Recommended, but not required. Valid options are `upgrade`, `uninstall`, `lint`, and `help`. | +| update_dependencies | boolean | Calls `helm dependency update` before running the main command. **Not currently implemented**; see [#25](https://github.com/pelotech/drone-helm3/issues/25).| +| helm_repos | list\ | Calls `helm repo add $repo` before running the main command. Each string should be formatted as `repo_name=https://repo.url/`. **Not currently implemented**; see [#26](https://github.com/pelotech/drone-helm3/issues/26). | +| namespace | string | Kubernetes namespace to use for this operation. | +| prefix | string | Expect environment variables to be prefixed with the given string. For more details, see "Using the prefix setting" below. **Not currently implemented**; see [#19](https://github.com/pelotech/drone-helm3/issues/19). | +| debug | boolean | Generate debug output within drone-helm3 and pass `--debug` to all helm commands. Use with care, since the debug output may include secrets. | + +## Linting + +Linting is only triggered when the `helm_command` setting is "lint". + +| Param name | Type | Required | Purpose | +|---------------|----------------|----------|---------| +| chart | string | yes | The chart to be linted. Must be a local path. | +| values | list\ | | Chart values to use as the `--set` argument to `helm lint`. | +| string_values | list\ | | Chart values to use as the `--set-string` argument to `helm lint`. | +| values_files | list\ | | Values to use as `--values` arguments to `helm lint`. | + +## Installation + +Installations are triggered when the `helm_command` setting is "upgrade." They can also be triggered when the build was triggered by a `push`, `tag`, `deployment`, `pull_request`, `promote`, or `rollback` Drone event. + +| Param name | Type | Required | Purpose | +|------------------------|----------------|----------|---------| +| chart | string | yes | The chart to use for this installation. | +| release | string | yes | The release name for helm to use. | +| api_server | string | yes | API endpoint for the Kubernetes cluster. | +| kubernetes_token | string | yes | Token for authenticating to Kubernetes. | +| service_account | string | | Service account for authenticating to Kubernetes. Default is `helm`. | +| kubernetes_certificate | string | | Base64 encoded TLS certificate used by the Kubernetes cluster's certificate authority. | +| chart_version | string | | Specific chart version to install. | +| dry_run | boolean | | Pass `--dry-run` to `helm upgrade`. | +| wait | boolean | | Wait until kubernetes resources are in a ready state before marking the installation successful. | +| timeout | duration | | Timeout for any *individual* Kubernetes operation. The installation's full runtime may exceed this duration. | +| force | boolean | | Pass `--force` to `helm upgrade`. | +| values | list\ | | Chart values to use as the `--set` argument to `helm upgrade`. | +| string_values | list\ | | Chart values to use as the `--set-string` argument to `helm upgrade`. | +| values_files | list\ | | Values to use as `--values` arguments to `helm upgrade`. | +| reuse_values | boolean | | Reuse the values from a previous release. | +| skip_tls_verify | boolean | | Connect to the Kubernetes cluster without checking for a valid TLS certificate. Not recommended in production. | + +## Uninstallation + +Uninstallations are triggered when the `helm_command` setting is "uninstall" or "delete." They can also be triggered when the build was triggered by a `delete` Drone event. + +| Param name | Type | Required | Purpose | +|------------------------|----------|----------|---------| +| release | string | yes | The release name for helm to use. | +| api_server | string | yes | API endpoint for the Kubernetes cluster. | +| kubernetes_token | string | yes | Token for authenticating to Kubernetes. | +| service_account | string | | Service account for authenticating to Kubernetes. Default is `helm`. | +| kubernetes_certificate | string | | Base64 encoded TLS certificate used by the Kubernetes cluster's certificate authority. | +| dry_run | boolean | | Pass `--dry-run` to `helm uninstall`. | +| timeout | duration | | Timeout for any *individual* Kubernetes operation. The uninstallation's full runtime may exceed this duration. | +| skip_tls_verify | boolean | | Connect to the Kubernetes cluster without checking for a valid TLS certificate. Not recommended in production. | + +### Formatting non-string values + +* Booleans can be yaml's `true` and `false` literals or the strings `"true"` and `"false"`. +* Durations are strings formatted with the syntax accepted by [golang's ParseDuration function](https://golang.org/pkg/time/#ParseDuration) (e.g. 5m30s) +* List\s can be a yaml sequence or a comma-separated string. + +All of the following are equivalent: + +```yaml +values: "foo=1,bar=2" +values: ["foo=1", "bar=2"] +values: + - foo=1 + - bar=2 +``` + +Note that **list members must not contain commas**. Both of the following are equivalent: + +```yaml +values_files: [ "./over_9,000.yml" ] +values_files: [ "./over_9", "000.yml" ] +``` + +### Using the `prefix` setting + +Because the prefix setting is meta-configuration, it has some inherent edge-cases. Here is what it does in the cases we've thought of: + +Unlike the other settings, it must be declared in the `settings` block, not `environment`. + +```yaml +settings: + prefix: helm # drone-helm3 will look for environment variables called HELM_VARNAME +environment: + prefix: armet # no effect +``` + +It does not apply to configuration in the `settings` block, only in `environment`. + +```yaml +settings: + prefix: helm + helm_timeout: 5m # no effect +environment: + helm_timeout: 2m # timeout will be 2 minutes +``` + +If the environment contains a variable in non-prefixed form, it will still be applied. + +```yaml +settings: + prefix: helm +environment: + timeout: 2m # timeout will be 2 minutes +``` + +If the environment contains both the prefixed and non-prefixed forms, drone-helm3 will use the prefixed form. + +```yaml +settings: + prefix: helm +environment: + timeout: 5m # overridden + helm_timeout: 2m # timeout will be 2 minutes +``` diff --git a/docs/upgrade_settings.yml b/docs/upgrade_settings.yml deleted file mode 100644 index 90cd49c..0000000 --- a/docs/upgrade_settings.yml +++ /dev/null @@ -1,84 +0,0 @@ ---- -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 - - # 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 From ff8e988122beb8b5c66aca163d2ad806307ce951 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Tue, 24 Dec 2019 15:22:25 -0800 Subject: [PATCH 14/17] Use "installation" rather than "deployment" [#8] "deploy" matches my mental model of what helm does, but "install" matches helm's own terminology more closely. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b21ac90..023232a 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ steps: chart: ./ ``` -### Deployment +### Installation ```yaml steps: @@ -39,7 +39,7 @@ steps: from_secret: kubernetes_token ``` -### Deletion +### Uninstallation ```yaml steps: From d4506608d79d78ed4164c6953e167df23ca8395c Mon Sep 17 00:00:00 2001 From: Erin Call Date: Tue, 24 Dec 2019 15:25:44 -0800 Subject: [PATCH 15/17] Note a backwards-incompatibility in the README [#8] This probably isn't going to bite anyone, but it's technically possible, and it doesn't hurt to mention it. --- README.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 023232a..592baee 100644 --- a/README.md +++ b/README.md @@ -56,18 +56,16 @@ steps: ## Upgrading from drone-helm -The setting names for drone-helm3 are backwards-compatible with those for drone-helm, so the only mandatory step is to update the `image` clause so that drone uses the new plugin. +drone-helm3 is largely backwards-compatible with drone-helm. There are some known differences: -There are some recommended changes, though: +* `prefix` must be supplied via the `settings` block, not `environment`. +* Several settings no longer have any effect: + * `purge` -- this is the default behavior in Helm 3 + * `recreate_pods` + * `tiller_ns` + * `upgrade` + * `canary_image` + * `client_only` + * `stable_repo_url` -* If your `service_account` is currently `tiller`, change it to a service account with more restricted permissions. - * If possible, remove the tiller account entirely, since its superuser status presents a security risk. -* Remove outdated settings that have no effect in drone-helm3: - -* `purge` -- this is the default behavior in Helm 3 -* `recreate_pods` -* `tiller_ns` -* `upgrade` -* `canary_image` -* `client_only` -* `stable_repo_url` +Since helm 3 does not require Tiller, we also recommend switching to a service account with less-expansive permissions. From dc05855aa5c79fd530b1c064210ee9fc6b14fcb0 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Thu, 26 Dec 2019 09:41:10 -0800 Subject: [PATCH 16/17] Mention the `settings`/`environment` equivalency [#8] It seems like this needs more information, like why you'd want to put something in one stanza or the other, but I don't really know enough about drone to give useful advice. --- docs/parameter_reference.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/parameter_reference.md b/docs/parameter_reference.md index 288bd53..ba492ed 100644 --- a/docs/parameter_reference.md +++ b/docs/parameter_reference.md @@ -1,13 +1,5 @@ # Parameter reference -## Something here about how to specify non-string types - -* boolean -* list\ -* duration - -## Mention that everything can be settings or environment - ## Global | Param name | Type | Purpose | |---------------------|-----------------|---------| @@ -67,6 +59,10 @@ Uninstallations are triggered when the `helm_command` setting is "uninstall" or | timeout | duration | | Timeout for any *individual* Kubernetes operation. The uninstallation's full runtime may exceed this duration. | | skip_tls_verify | boolean | | Connect to the Kubernetes cluster without checking for a valid TLS certificate. Not recommended in production. | +### Where to put settings + +Any setting (with the exception of `prefix`; [see below](#user-content-using-the-prefix-setting)), can go in either the `settings` or `environment` section. + ### Formatting non-string values * Booleans can be yaml's `true` and `false` literals or the strings `"true"` and `"false"`. From 568f613401cc67c91b62679b843eaa2fb74184a0 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Thu, 26 Dec 2019 09:44:46 -0800 Subject: [PATCH 17/17] Associate lines of text with their yaml blocks [#8] As I skimmed through that section I noticed it wasn't immediately clear whether a line of text was referring to the example above it or the one below it. --- docs/parameter_reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/parameter_reference.md b/docs/parameter_reference.md index ba492ed..07d8107 100644 --- a/docs/parameter_reference.md +++ b/docs/parameter_reference.md @@ -90,7 +90,7 @@ values_files: [ "./over_9", "000.yml" ] Because the prefix setting is meta-configuration, it has some inherent edge-cases. Here is what it does in the cases we've thought of: -Unlike the other settings, it must be declared in the `settings` block, not `environment`. +Unlike the other settings, it must be declared in the `settings` block, not `environment`: ```yaml settings: @@ -99,7 +99,7 @@ environment: prefix: armet # no effect ``` -It does not apply to configuration in the `settings` block, only in `environment`. +It does not apply to configuration in the `settings` block, only in `environment`: ```yaml settings: @@ -109,7 +109,7 @@ environment: helm_timeout: 2m # timeout will be 2 minutes ``` -If the environment contains a variable in non-prefixed form, it will still be applied. +If the environment contains a variable in non-prefixed form, it will still be applied: ```yaml settings: @@ -118,7 +118,7 @@ environment: timeout: 2m # timeout will be 2 minutes ``` -If the environment contains both the prefixed and non-prefixed forms, drone-helm3 will use the prefixed form. +If the environment contains both the prefixed and non-prefixed forms, drone-helm3 will use the prefixed form: ```yaml settings: