diff --git a/docs/parameter_reference.md b/docs/parameter_reference.md index 7b14db5..1379ba5 100644 --- a/docs/parameter_reference.md +++ b/docs/parameter_reference.md @@ -1,13 +1,13 @@ # Parameter reference ## Global -| Param name | Type | Purpose | -|---------------------|-----------------|---------| -| mode | 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.| -| add_repos | list\ | Calls `helm repo add $repo` before running the main command. Each string should be formatted as `repo_name=https://repo.url/`. | -| namespace | string | Kubernetes namespace to use for this operation. | -| 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. | +| Param name | Type | Alias | Purpose | +|---------------------|-----------------|--------------|---------| +| mode | string | helm_command | 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.| +| add_repos | list\ | helm_repos | Calls `helm repo add $repo` before running the main command. Each string should be formatted as `repo_name=https://repo.url/`. | +| namespace | string | | Kubernetes namespace to use for this operation. | +| 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 @@ -25,43 +25,43 @@ Linting is only triggered when the `mode` setting is "lint". Installations are triggered when the `mode` 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. | -| kube_api_server | string | yes | API endpoint for the Kubernetes cluster. | -| kube_token | string | yes | Token for authenticating to Kubernetes. | -| kube_service_account | string | | Service account for authenticating to Kubernetes. Default is `helm`. | -| kube_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_for_upgrade | 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_upgrade | boolean | | Pass `--force` to `helm upgrade`. | -| atomic_upgrade | boolean | | Pass `--atomic` to `helm upgrade`. | -| cleanup_failed_upgrade | boolean | | Pass `--cleanup-on-fail` 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. | +| Param name | Type | Required | Alias | Purpose | +|------------------------|----------------|----------|------------------------|---------| +| chart | string | yes | | The chart to use for this installation. | +| release | string | yes | | The release name for helm to use. | +| kube_api_server | string | yes | api_server | API endpoint for the Kubernetes cluster. | +| kube_token | string | yes | kubernetes_token | Token for authenticating to Kubernetes. | +| kube_service_account | string | | service_account | Service account for authenticating to Kubernetes. Default is `helm`. | +| kube_certificate | string | | kubernetes_certificate | 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_for_upgrade | boolean | | wait | 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_upgrade | boolean | | force | Pass `--force` to `helm upgrade`. | +| atomic_upgrade | boolean | | | Pass `--atomic` to `helm upgrade`. | +| cleanup_failed_upgrade | boolean | | | Pass `--cleanup-on-fail` 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 `mode` 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. | -| kube_api_server | string | yes | API endpoint for the Kubernetes cluster. | -| kube_token | string | yes | Token for authenticating to Kubernetes. | -| kube_service_account | string | | Service account for authenticating to Kubernetes. Default is `helm`. | -| kube_certificate | string | | Base64 encoded TLS certificate used by the Kubernetes cluster's certificate authority. | -| keep_history | boolean | | Pass `--keep-history` to `helm uninstall`, to retain the release history. | -| 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. | -| chart | string | | Required when the global `update_dependencies` parameter is true. No effect otherwise. | +| Param name | Type | Required | Alias | Purpose | +|------------------------|----------|----------|------------------------|---------| +| release | string | yes | | The release name for helm to use. | +| kube_api_server | string | yes | api_server | API endpoint for the Kubernetes cluster. | +| kube_token | string | yes | kubernetes_token | Token for authenticating to Kubernetes. | +| kube_service_account | string | | service_account | Service account for authenticating to Kubernetes. Default is `helm`. | +| kube_certificate | string | | kubernetes_certificate | Base64 encoded TLS certificate used by the Kubernetes cluster's certificate authority. | +| keep_history | boolean | | | Pass `--keep-history` to `helm uninstall`, to retain the release history. | +| 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. | +| chart | string | | | Required when the global `update_dependencies` parameter is true. No effect otherwise. | ### Where to put settings @@ -92,3 +92,18 @@ Note that **list members must not contain commas**. Both of the following are eq values_files: [ "./over_9,000.yml" ] values_files: [ "./over_9", "000.yml" ] ``` + +### Backward-compatibility aliases + +Some settings have alternate names, for backward-compatibility with drone-helm. We recommend using the canonical name unless you require the backward-compatible form. + +| Canonical name | Alias | +|----------------------|-------| +| mode | helm_command | +| add_repos | helm_repos | +| kube_api_server | api_server | +| kube_service_account | service_account | +| kube_token | kubernetes_token | +| kube_certificate | kubernetes_certificate | +| wait_for_upgrade | wait | +| force_upgrade | force |