Merge branch 'master' into config-fixup

This commit is contained in:
Joachim Hill-Grannec 2019-12-26 11:36:55 -08:00 committed by GitHub
commit 253a4465f8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 204 additions and 12 deletions

View file

@ -1,3 +1,71 @@
# Drone plugin for Helm 3 # 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
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
```yaml
steps:
- name: lint
image: pelotech/drone-helm3
settings:
helm_command: lint
chart: ./
```
### Installation
```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
```
### Uninstallation
```yaml
steps:
- name: uninstall
image: pelotech/drone-helm3
settings:
helm_command: uninstall
release: my-project
environment:
API_SERVER: https://my.kubernetes.installation/clusters/a-1234
KUBERNETES_TOKEN:
from_secret: kubernetes_token
```
## Upgrading from drone-helm
drone-helm3 is largely backwards-compatible with drone-helm. There are some known differences:
* `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`
Since helm 3 does not require Tiller, we also recommend switching to a service account with less-expansive permissions.

129
docs/parameter_reference.md Normal file
View file

@ -0,0 +1,129 @@
# Parameter reference
## 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. |
### 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"`.
* 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
```

View file

@ -69,6 +69,7 @@ func determineSteps(cfg Config) *func(Config) []Step {
return &help return &help
default: default:
switch cfg.DroneEvent { 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": case "push", "tag", "deployment", "pull_request", "promote", "rollback":
return &upgrade return &upgrade
case "delete": case "delete":

View file

@ -51,9 +51,6 @@ func (i *InitKube) Prepare(cfg Config) error {
if i.Token == "" { if i.Token == "" {
return errors.New("token is needed to deploy") return errors.New("token is needed to deploy")
} }
if i.Certificate == "" && !i.SkipTLSVerify {
return errors.New("certificate is needed to deploy")
}
if i.ServiceAccount == "" { if i.ServiceAccount == "" {
i.ServiceAccount = "helm" i.ServiceAccount = "helm"

View file

@ -132,13 +132,6 @@ func (suite *InitKubeTestSuite) TestPrepareRequiredConfig() {
init.APIServer = "Sysadmin" init.APIServer = "Sysadmin"
init.Token = "" init.Token = ""
suite.Error(init.Prepare(cfg), "Token should be required.") 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() { func (suite *InitKubeTestSuite) TestPrepareDefaultsServiceAccount() {

View file

@ -16,6 +16,8 @@ func (l *Lint) Execute(_ Config) error {
} }
// Prepare gets the Lint ready to execute. // 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 { func (l *Lint) Prepare(cfg Config) error {
if l.Chart == "" { if l.Chart == "" {
return fmt.Errorf("chart is required") return fmt.Errorf("chart is required")

View file

@ -25,6 +25,8 @@ func (u *Upgrade) Execute(_ Config) error {
} }
// Prepare gets the Upgrade ready to execute. // 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 { func (u *Upgrade) Prepare(cfg Config) error {
if u.Chart == "" { if u.Chart == "" {
return fmt.Errorf("chart is required") return fmt.Errorf("chart is required")

View file

@ -3,7 +3,7 @@ clusters:
- cluster: - cluster:
{{- if eq .SkipTLSVerify true }} {{- if eq .SkipTLSVerify true }}
insecure-skip-tls-verify: true insecure-skip-tls-verify: true
{{- else }} {{- else if .Certificate }}
certificate-authority-data: {{ .Certificate }} certificate-authority-data: {{ .Certificate }}
{{- end}} {{- end}}
server: {{ .APIServer }} server: {{ .APIServer }}