From ef66bc0f9210f458d3757d4fb22db0e7e5364b82 Mon Sep 17 00:00:00 2001 From: Erin Call Date: Tue, 24 Dec 2019 14:36:39 -0800 Subject: [PATCH] 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