dentaku/woodpecker-helm3
1
0
Fork 0
Code Pull requests Releases Activity
woodpecker-helm3/docs/parameter_reference.md

95 lines
6.5 KiB
Markdown
Raw Normal View History

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.""
2019-12-24 22:36:39 +00:00
# Parameter reference
## Global
| Param name | Type | Purpose |
|---------------------|-----------------|---------|
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
| mode | string | Indicates the operation to perform. Recommended, but not required. Valid options are `upgrade`, `uninstall`, `lint`, and `help`. |
Call `helm dependency update` when so instructed [#25] As with Lint, I have no idea whether the --namespace flag actually matters here. I don't think it will hurt, though!
2019-12-27 23:06:32 +00:00
| update_dependencies | boolean | Calls `helm dependency update` before running the main command.|
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
| add_repos | list\<string\> | Calls `helm repo add $repo` before running the main command. Each string should be formatted as `repo_name=https://repo.url/`. |
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.""
2019-12-24 22:36:39 +00:00
| 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
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
Linting is only triggered when the `mode` setting is "lint".
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.""
2019-12-24 22:36:39 +00:00
| Param name | Type | Required | Purpose |
|---------------|----------------|----------|---------|
| chart | string | yes | The chart to be linted. Must be a local path. |
| values | list\<string\> | | Chart values to use as the `--set` argument to `helm lint`. |
| string_values | list\<string\> | | Chart values to use as the `--set-string` argument to `helm lint`. |
| values_files | list\<string\> | | Values to use as `--values` arguments to `helm lint`. |
Pass --strict to `helm lint` when so instructed [#28]
2020-01-02 19:25:13 +00:00
| lint_strictly | boolean | | Pass `--strict` to `helm lint`, to turn warnings into errors. |
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.""
2019-12-24 22:36:39 +00:00
## Installation
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
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.
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.""
2019-12-24 22:36:39 +00:00
| 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. |
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
| 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. |
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.""
2019-12-24 22:36:39 +00:00
| chart_version | string | | Specific chart version to install. |
| dry_run | boolean | | Pass `--dry-run` to `helm upgrade`. |
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
| wait_for_upgrade | boolean | | Wait until kubernetes resources are in a ready state before marking the installation successful. |
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.""
2019-12-24 22:36:39 +00:00
| timeout | duration | | Timeout for any *individual* Kubernetes operation. The installation's full runtime may exceed this duration. |
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
| force_upgrade | boolean | | Pass `--force` to `helm upgrade`. |
Pass an atomic_upgrade setting to the Upgrade step [#64]
2020-01-07 20:21:55 +00:00
| atomic_upgrade | boolean | | Pass `--atomic` to `helm upgrade`. |
Pass CleanupOnFail to the Upgrade Step [#65] I don't love the mismatch between the helm.Config field (CleanupOnFail) and the setting name (cleanup_failed_upgrade). I do think the setting name should contain "upgrade" since it's specific to the upgrade command, but if I make the config field CleanupFailedUpgrade, it becomes the new longest field name, and gofmt creates a bunch of churn. Is that a good enough reason...?
2020-01-07 20:56:33 +00:00
| cleanup_failed_upgrade | boolean | | Pass `--cleanup-on-fail` to `helm upgrade`. |
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.""
2019-12-24 22:36:39 +00:00
| values | list\<string\> | | Chart values to use as the `--set` argument to `helm upgrade`. |
| string_values | list\<string\> | | Chart values to use as the `--set-string` argument to `helm upgrade`. |
| values_files | list\<string\> | | 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
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
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.
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.""
2019-12-24 22:36:39 +00:00
| Param name | Type | Required | Purpose |
|------------------------|----------|----------|---------|
| release | string | yes | The release name for helm to use. |
Default to the canonical setting names [#66] The goal with these changes was to give users a clearer, more readable interface, so we should present that interface up front and only document the aliases as a backward-compatibility option. I've renamed the envconfig tags to reflect the switch, but I left the actual field names the same. I think they're sufficiently meaningful inside the code, and leaving them unchanged avoids making a bunch of churn in the rest of the code.
2020-01-08 18:45:53 +00:00
| 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. |
Pass --keep-history when so instructed [#24]
2020-01-02 18:58:58 +00:00
| keep_history | boolean | | Pass `--keep-history` to `helm uninstall`, to retain the release history. |
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.""
2019-12-24 22:36:39 +00:00
| 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. |
Mention the chart param for uninstalls [#25]
2019-12-27 23:44:09 +00:00
| chart | string | | Required when the global `update_dependencies` parameter is true. No effect otherwise. |
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.""
2019-12-24 22:36:39 +00:00
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.
2019-12-26 17:41:10 +00:00
### Where to put settings
Docs for settings/environment conflict resolution [#45]
2020-01-02 17:23:02 +00:00
Any setting can go in either the `settings` or `environment` section. If a setting exists in _both_ sections, the version in `environment` will override the version in `settings`.
We recommend putting all drone-helm3 configuration in the `settings` block and limiting the `environment` block to variables that are used when building your charts.
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.
2019-12-26 17:41:10 +00:00
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.""
2019-12-24 22:36:39 +00:00
### 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)
Shim bare numbers into duration strings [#39] Helm2's --timeout took a number of seconds, rather than the ParseDuration-compatible string that helm3 uses. For backward- compatibility, update a bare number into a duration string.
2019-12-28 00:18:10 +00:00
* For backward-compatibility with drone-helm, a duration can also be an integer, in which case it will be interpreted to mean seconds.
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.""
2019-12-24 22:36:39 +00:00
* List\<string\>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" ]
```
Copy permalink