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.""
This commit is contained in:
Erin Call
parent
59a591eda5
commit
ef66bc0f92
|
|
@ -10,7 +10,7 @@ The plugin is inpsired by [drone-helm](https://github.com/ipedrazas/drone-helm),
|
||||||
|
|
||||||
## Example configuration
|
## 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
|
### Linting
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
|
||||||
133
docs/parameter_reference.md
Normal file
133
docs/parameter_reference.md
Normal file
|
|
@ -0,0 +1,133 @@
|
||||||
|
# Parameter reference
|
||||||
|
|
||||||
|
## Something here about how to specify non-string types
|
||||||
|
|
||||||
|
* boolean
|
||||||
|
* list\<string\>
|
||||||
|
* 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\<string\> | 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\<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`. |
|
||||||
|
|
||||||
|
## 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\<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
|
||||||
|
|
||||||
|
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\<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" ]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
||||||
|
```
|
||||||
|
|
@ -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
|
|
||||||
Loading…
Reference in a new issue