public_git
/
helmfile
mirror of https://github.com/helmfile/helmfile.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve capitalization and formats of README.md. (#1545)

This commit is contained in:
Wi1dcard 2020-10-19 07:47:19 +08:00 committed by GitHub
parent 1aca099457
commit 4d868794fd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 55 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.editorconfig Normal file
View File

@ -0,0 +1,5 @@
root = true
[*.md]
insert_final_newline = true
trim_trailing_whitespace = true

22
PATHS.md
View File

@ -1,25 +1,27 @@
# Paths Overivew # Paths Overivew
Using manifest files in conjunction with command line argument can be a bit confusing.
A few rules to clear up this ambiguity: Using manifest files in conjunction with command line argument can be a bit confusing.
A few rules to clear up this ambiguity:
- Absolute paths are always resolved as absolute paths - Absolute paths are always resolved as absolute paths
- Relative paths referenced *in* the helmfile manifest itself are relative to that manifest - Relative paths referenced *in* the helmfile manifest itself are relative to that manifest
- Relative paths referenced on the command line are relative to the current working directory the user is in - Relative paths referenced on the command line are relative to the current working directory the user is in
### Examples ### Examples
There are several examples that we can go through in the `/examples` folder which demonstrate this.
There are several examples that we can go through in the [`/examples`](examples) folder which demonstrate this.
**Local Execution** **Local Execution**
This is an example of a Helmfile manifest referencing a local value directly. This is an example of a Helmfile manifest referencing a local value directly.
Indirect: Indirect:
``` ```
helmfile -f examples/deployments/local/charts.yaml sync helmfile -f examples/deployments/local/charts.yaml sync
``` ```
Direct: Direct:
``` ```
cd examples/deployments/local/ cd examples/deployments/local/
helmfile sync helmfile sync
@ -27,14 +29,14 @@ helmfile sync
**Relative Paths in Helmfile** **Relative Paths in Helmfile**
This is an example of a Helmfile manifest using relative paths for values. This is an example of a Helmfile manifest using relative paths for values.
Indirect: Indirect:
``` ```
helmfile -f examples/deployments/dev/charts.yaml sync helmfile -f examples/deployments/dev/charts.yaml sync
``` ```
Direct: Direct:
``` ```
cd examples/deployments/dev/ cd examples/deployments/dev/
helmfile sync helmfile sync
@ -42,7 +44,7 @@ helmfile sync
**Relative Paths in Helmfile w/ --values overrides** **Relative Paths in Helmfile w/ --values overrides**
This is an example of a Helmfile manifest using relative paths for values including an additional `--values` from the command line. This is an example of a Helmfile manifest using relative paths for values including an additional `--values` from the command line.
NOTE: The `--values` is resolved relative to the CWD of the terminal *not* the Helmfile manifest. You can see this with the `replicas` being adjusted to 3 now for the deployment. NOTE: The `--values` is resolved relative to the CWD of the terminal *not* the Helmfile manifest. You can see this with the `replicas` being adjusted to 3 now for the deployment.
@ -51,7 +53,7 @@ Indirect:
helmfile -f examples/deployments/dev/charts.yaml sync --values values/replica-values.yaml helmfile -f examples/deployments/dev/charts.yaml sync --values values/replica-values.yaml
``` ```
Direct: Direct:
``` ```
cd examples/deployments/dev/ cd examples/deployments/dev/
helmfile sync --values ../../values/replica-values.yaml helmfile sync --values ../../values/replica-values.yaml

72
README.md
View File

@ -351,7 +351,7 @@ releases:
If you wish to treat your enviroment variables as strings always, even if they are boolean or numeric values you can use `{{ env "ENV_NAME" | quote }}` or `"{{ env "ENV_NAME" }}"`. These approaches also work with `requiredEnv`. If you wish to treat your enviroment variables as strings always, even if they are boolean or numeric values you can use `{{ env "ENV_NAME" | quote }}` or `"{{ env "ENV_NAME" }}"`. These approaches also work with `requiredEnv`.
## installation ## Installation
- download one of [releases](https://github.com/roboll/helmfile/releases) or - download one of [releases](https://github.com/roboll/helmfile/releases) or
- run as a [container](https://quay.io/roboll/helmfile) or - run as a [container](https://quay.io/roboll/helmfile) or
@ -359,7 +359,7 @@ If you wish to treat your enviroment variables as strings always, even if they a
- Windows (using [scoop](https://scoop.sh/)): `scoop install helmfile` - Windows (using [scoop](https://scoop.sh/)): `scoop install helmfile`
- macOS (using [homebrew](https://brew.sh/)): `brew install helmfile` - macOS (using [homebrew](https://brew.sh/)): `brew install helmfile`
## getting started ## Getting Started
Let's start with a simple `helmfile` and gradually improve it to fit your use-case! Let's start with a simple `helmfile` and gradually improve it to fit your use-case!
@ -389,7 +389,7 @@ Iterate on the `helmfile.yaml` by referencing:
- [CLI reference](#cli-reference). - [CLI reference](#cli-reference).
- [Helmfile Best Practices Guide](https://github.com/roboll/helmfile/blob/master/docs/writing-helmfile.md) - [Helmfile Best Practices Guide](https://github.com/roboll/helmfile/blob/master/docs/writing-helmfile.md)
## cli reference ## CLI Reference
``` ```
NAME: NAME:
@ -496,7 +496,6 @@ The `helmfile delete` sub-command deletes all the releases defined in the manife
Note that `delete` doesn't purge releases. So `helmfile delete && helmfile sync` results in sync failed due to that releases names are not deleted but preserved for future references. If you really want to remove releases for reuse, add `--purge` flag to run it like `helmfile delete --purge`. Note that `delete` doesn't purge releases. So `helmfile delete && helmfile sync` results in sync failed due to that releases names are not deleted but preserved for future references. If you really want to remove releases for reuse, add `--purge` flag to run it like `helmfile delete --purge`.
### secrets ### secrets
The `secrets` parameter in a `helmfile.yaml` causes the [helm-secrets](https://github.com/futuresimple/helm-secrets) plugin to be executed to decrypt the file. The `secrets` parameter in a `helmfile.yaml` causes the [helm-secrets](https://github.com/futuresimple/helm-secrets) plugin to be executed to decrypt the file.
@ -516,6 +515,7 @@ Use `--cleanup` to delete pods upon completion.
The `helmfile lint` sub-command runs a `helm lint` across all of the charts/releases defined in the manifest. Non local charts will be fetched into a temporary folder which will be deleted once the task is completed. The `helmfile lint` sub-command runs a `helm lint` across all of the charts/releases defined in the manifest. Non local charts will be fetched into a temporary folder which will be deleted once the task is completed.
## Paths Overview ## Paths Overview
Using manifest files in conjunction with command line argument can be a bit confusing. Using manifest files in conjunction with command line argument can be a bit confusing.
A few rules to clear up this ambiguity: A few rules to clear up this ambiguity:
@ -524,9 +524,10 @@ A few rules to clear up this ambiguity:
- Relative paths referenced *in* the Helmfile manifest itself are relative to that manifest - Relative paths referenced *in* the Helmfile manifest itself are relative to that manifest
- Relative paths referenced on the command line are relative to the current working directory the user is in - Relative paths referenced on the command line are relative to the current working directory the user is in
For additional context, take a look at [paths examples](PATHS.md) For additional context, take a look at [paths examples](PATHS.md).
## Labels Overview ## Labels Overview
A selector can be used to only target a subset of releases when running Helmfile. This is useful for large helmfiles with releases that are logically grouped together. A selector can be used to only target a subset of releases when running Helmfile. This is useful for large helmfiles with releases that are logically grouped together.
Labels are simple key value pairs that are an optional field of the release spec. When selecting by label, the search can be inverted. `tier!=backend` would match all releases that do NOT have the `tier: backend` label. `tier=fronted` would only match releases with the `tier: frontend` label. Labels are simple key value pairs that are an optional field of the release spec. When selecting by label, the search can be inverted. `tier!=backend` would match all releases that do NOT have the `tier: backend` label. `tier=fronted` would only match releases with the `tier: frontend` label.
@ -535,7 +536,7 @@ Multiple labels can be specified using `,` as a separator. A release must match
The `selector` parameter can be specified multiple times. Each parameter is resolved independently so a release that matches any parameter will be used. The `selector` parameter can be specified multiple times. Each parameter is resolved independently so a release that matches any parameter will be used.
`--selector tier=frontend --selector tier=backend` will select all the charts `--selector tier=frontend --selector tier=backend` will select all the charts.
In addition to user supplied labels, the name, the namespace, and the chart are available to be used as selectors. The chart will just be the chart name excluding the repository (Example `stable/filebeat` would be selected using `--selector chart=filebeat`). In addition to user supplied labels, the name, the namespace, and the chart are available to be used as selectors. The chart will just be the chart name excluding the repository (Example `stable/filebeat` would be selected using `--selector chart=filebeat`).
@ -544,7 +545,7 @@ For instance, you install a number of charts on every customer but need to provi
templates/common.yaml: templates/common.yaml:
``` ```yaml
templates: templates:
nginx: &nginx nginx: &nginx
name: nginx name: nginx
@ -563,7 +564,7 @@ templates:
helmfile.yaml: helmfile.yaml:
``` ```yaml
{{ readFile "templates/common.yaml" }} {{ readFile "templates/common.yaml" }}
commonLabels: commonLabels:
@ -984,14 +985,14 @@ that is accessible by running a command:
A usual usage of `exec` would look like this: A usual usage of `exec` would look like this:
``` ```yaml
mysetting: | mysetting: |
{{ exec "./mycmd" (list "arg1" "arg2" "--flag1") | indent 2 }} {{ exec "./mycmd" (list "arg1" "arg2" "--flag1") | indent 2 }}
``` ```
Or even with a pipeline: Or even with a pipeline:
``` ```yaml
mysetting: | mysetting: |
{{ yourinput | exec "./mycmd-consume-stdin" (list "arg1" "arg2") | indent 2 }} {{ yourinput | exec "./mycmd-consume-stdin" (list "arg1" "arg2") | indent 2 }}
``` ```
@ -1037,7 +1038,7 @@ This is the counterpart to `prepare`, as any release on which `prepare` has been
The following is an example hook that just prints the contextual information provided to hook: The following is an example hook that just prints the contextual information provided to hook:
``` ```yaml
releases: releases:
- name: myapp - name: myapp
chart: mychart chart: mychart
@ -1072,10 +1073,11 @@ For templating, imagine that you created a hook that generates a helm chart on-t
It will allow you to write your helm releases with any language you like, while still leveraging goodies provided by helm. It will allow you to write your helm releases with any language you like, while still leveraging goodies provided by helm.
### Global Hooks ### Global Hooks
In contrast to the per release hooks mentioned above these are run only once at the very beginning and end of the execution of a helmfile command and only the `prepare` and `cleanup` hooks are available respectively. In contrast to the per release hooks mentioned above these are run only once at the very beginning and end of the execution of a helmfile command and only the `prepare` and `cleanup` hooks are available respectively.
They use the same syntax as per release hooks, but at the top level of your helmfile: They use the same syntax as per release hooks, but at the top level of your helmfile:
``` yaml ```yaml
hooks: hooks:
- events: ["prepare", "cleanup"] - events: ["prepare", "cleanup"]
showlogs: true showlogs: true
@ -1146,9 +1148,9 @@ We also have dedicated documentation on the following topics which might interes
Or join our friendly slack community in the [`#helmfile`](https://slack.sweetops.com) channel to ask questions and get help. Check out our [slack archive](https://archive.sweetops.com/helmfile/) for good examples of how others are using it. Or join our friendly slack community in the [`#helmfile`](https://slack.sweetops.com) channel to ask questions and get help. Check out our [slack archive](https://archive.sweetops.com/helmfile/) for good examples of how others are using it.
## Using env files ## Using .env files
Helmfile itself doesn't have an ability to load env files. But you can write some bash script to achieve the goal: Helmfile itself doesn't have an ability to load .env files. But you can write some bash script to achieve the goal:
```console ```console
set -a; . .env; set +a; helmfile sync set -a; . .env; set +a; helmfile sync
@ -1156,7 +1158,7 @@ set -a; . .env; set +a; helmfile sync
Please see #203 for more context. Please see #203 for more context.
## Running helmfile interactively ## Running Helmfile interactively
`helmfile --interactive [apply|destroy]` requests confirmation from you before actually modifying your cluster. `helmfile --interactive [apply|destroy]` requests confirmation from you before actually modifying your cluster.
@ -1170,29 +1172,14 @@ Once you download all required charts into your machine, you can run `helmfile c
It basically run only `helm upgrade --install` with your already-downloaded charts, hence no Internet connection is required. It basically run only `helm upgrade --install` with your already-downloaded charts, hence no Internet connection is required.
See #155 for more information on this topic. See #155 for more information on this topic.
## Experimental features ## Experimental Features
Some experimental features may be available for testing in perspective of being (or not) included in a future release. Some experimental features may be available for testing in perspective of being (or not) included in a future release.
Those features are set using the environment variable `HELMFILE_EXPERIMENTAL`. Here is the current experimental feature : Those features are set using the environment variable `HELMFILE_EXPERIMENTAL`. Here is the current experimental feature :
* `explicit-selector-inheritance` : remove today implicit cli selectors inheritance for composed helmfiles, see [composition selector](#selectors) * `explicit-selector-inheritance` : remove today implicit cli selectors inheritance for composed helmfiles, see [composition selector](#selectors)
If you want to enable all experimental features set the env var to `HELMFILE_EXPERIMENTAL=true` If you want to enable all experimental features set the env var to `HELMFILE_EXPERIMENTAL=true`
## Azure ACR integration
Azure offers helm repository [support for Azure Container Registry](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-helm-repos) as a preview feature.
To use this you must first `az login` and then `az acr helm repo add -n <MyRegistry>`. This will extract a token for the given ACR and configure `helm` to use it, e.g. `helm repo update` should work straight away.
To use `helmfile` with ACR, on the other hand, you must either include a username/password in the repository definition for the ACR in your `helmfile.yaml` or use the `--skip-deps` switch, e.g. `helmfile template --skip-deps`.
An ACR repository definition in `helmfile.yaml` looks like this:
```
repositories:
- name: <MyRegistry>
url: https://<MyRegistry>.azurecr.io/helm/v1/repo
```
## Examples ## Examples
For more examples, see the [examples/README.md](https://github.com/roboll/helmfile/blob/master/examples/README.md) or the [`helmfile`](https://github.com/cloudposse/helmfiles/tree/master/releases) distribution by [Cloud Posse](https://github.com/cloudposse/). For more examples, see the [examples/README.md](https://github.com/roboll/helmfile/blob/master/examples/README.md) or the [`helmfile`](https://github.com/cloudposse/helmfiles/tree/master/releases) distribution by [Cloud Posse](https://github.com/cloudposse/).
@ -1202,6 +1189,7 @@ For more examples, see the [examples/README.md](https://github.com/roboll/helmfi
- [renovate](https://github.com/renovatebot/renovate) automates chart version updates. See [this PR for more information](https://github.com/renovatebot/renovate/pull/5257). - [renovate](https://github.com/renovatebot/renovate) automates chart version updates. See [this PR for more information](https://github.com/renovatebot/renovate/pull/5257).
- For updating container image tags and git tags embedded within helmfile.yaml and values, you can use [renovate's regexManager](https://docs.renovatebot.com/modules/manager/regex/). Please see [this comment in the renovate repository](https://github.com/renovatebot/renovate/issues/6130#issuecomment-624061289) for more information. - For updating container image tags and git tags embedded within helmfile.yaml and values, you can use [renovate's regexManager](https://docs.renovatebot.com/modules/manager/regex/). Please see [this comment in the renovate repository](https://github.com/renovatebot/renovate/issues/6130#issuecomment-624061289) for more information.
- [ArgoCD Integration](#argocd-integration) - [ArgoCD Integration](#argocd-integration)
- [Azure ACR Integration](#azure-acr-integration)
### ArgoCD Integration ### ArgoCD Integration
@ -1235,7 +1223,7 @@ git push origin $BRANCH
> Note that `$(pwd)` is necessary when `hemlfile.yaml` has one or more sub-helmfiles in nested directories, > Note that `$(pwd)` is necessary when `hemlfile.yaml` has one or more sub-helmfiles in nested directories,
> because setting a relative file path in `--output-dir` or `--output-dir-template` results in each sub-helmfile render > because setting a relative file path in `--output-dir` or `--output-dir-template` results in each sub-helmfile render
> to the directory relative to the specified path. > to the directory relative to the specified path.
so that they can be deployed by Argo CD as usual. so that they can be deployed by Argo CD as usual.
@ -1252,7 +1240,23 @@ Recommendations:
- If you don't directly push it to the main Git branch and instead go through a pull-request, do lint rendered manifests on your CI, so that you can catch easy mistakes earlier/before ArgoCD finally deploys it - If you don't directly push it to the main Git branch and instead go through a pull-request, do lint rendered manifests on your CI, so that you can catch easy mistakes earlier/before ArgoCD finally deploys it
- See [this ArgoCD issue](https://github.com/argoproj/argo-cd/issues/2143#issuecomment-570478329) for why you may want this, and see [this helmfile issue](https://github.com/roboll/helmfile/pull/1357) for how `--output-dir-template` works. - See [this ArgoCD issue](https://github.com/argoproj/argo-cd/issues/2143#issuecomment-570478329) for why you may want this, and see [this helmfile issue](https://github.com/roboll/helmfile/pull/1357) for how `--output-dir-template` works.
# Attribution ### Azure ACR Integration
Azure offers helm repository [support for Azure Container Registry](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-helm-repos) as a preview feature.
To use this you must first `az login` and then `az acr helm repo add -n <MyRegistry>`. This will extract a token for the given ACR and configure `helm` to use it, e.g. `helm repo update` should work straight away.
To use `helmfile` with ACR, on the other hand, you must either include a username/password in the repository definition for the ACR in your `helmfile.yaml` or use the `--skip-deps` switch, e.g. `helmfile template --skip-deps`.
An ACR repository definition in `helmfile.yaml` looks like this:
```yaml
repositories:
- name: <MyRegistry>
url: https://<MyRegistry>.azurecr.io/helm/v1/repo
```
## Attribution
We use: We use: