mirror of
https://github.com/helmfile/helmfile.git
synced 2026-09-30 16:27:38 +02:00
yxxhero
e703b15075
* feat: add --write-output flag to helmfile fetch for air-gapped environments Add --write-output flag to helmfile fetch that outputs a modified helmfile.yaml with chart references updated to point to downloaded local chart paths. Combined with --output-dir, this enables preparing all charts for deployment in air-gapped environments. Usage: helmfile fetch --output-dir ./charts --write-output > helmfile-airgapped.yaml Fixes #2571 Signed-off-by: yxxhero <yxxhero@users.noreply.github.com> Signed-off-by: yxxhero <aiopsclub@163.com> * docs: restructure documentation and improve newcomer experience Split the monolithic index.md (1990 lines) into focused topic pages, update mkdocs.yml navigation, and add missing documentation for undocumented code features. Structure changes: - Extract configuration.md (helmfile.yaml reference) - Extract cli.md (CLI commands and flags) - Extract templating.md (template syntax and env vars) - Extract environments.md (environment configuration) - Extract releases.md (DAG, needs, selectors) - Extract hooks.md (lifecycle hooks) - Extract integrations.md (ArgoCD, Azure ACR, OCI) - Slim index.md to ~270 line landing page with step-by-step tutorial Newcomer improvements: - Add 5-step Getting Started tutorial with explanations - Reorganize nav: Getting Started now shows core learning path (Writing Helmfile → Values → Environments → Releases) - Add Quick Reference table to configuration.md - Simplify writing-helmfile.md title Code-vs-docs gap fixes: - Document 23 undocumented release fields (valuesTemplate, setTemplate, forceNamespace, adopt, trackMode, etc.) - Document 6 undocumented helmDefaults fields (enableDNS, forceConflicts, skipRefresh, takeOwnership, etc.) - Document print-env command and missing CLI flags - Document kubectlApply hook field - Document environment defaults field and merge order - Document kubedogQPS/kubedogBurst advanced settings - Document template partials (_*.tpl) auto-loading Cleanup: - Fix Docker image version from v0.156.0 to v1.1.0 - Fix heading nesting in advanced-features.md - Update experimental-features.md with current features - Fix broken cross-references and anchor links Signed-off-by: yxxhero <aiopsclub@163.com> * Revert changes to pkg/app from docs/restructure-and-improve branch Signed-off-by: yxxhero <aiopsclub@163.com> * docs: add create subcommand to README and CLI reference Signed-off-by: yxxhero <aiopsclub@163.com> --------- Signed-off-by: yxxhero <yxxhero@users.noreply.github.com> Signed-off-by: yxxhero <aiopsclub@163.com>
164 lines
7.4 KiB
Markdown
164 lines
7.4 KiB
Markdown
<!-- markdownlint-configure-file {
|
|
"MD013": {
|
|
"code_blocks": false,
|
|
"tables": false
|
|
},
|
|
"MD033": false,
|
|
"MD041": false
|
|
} -->
|
|
|
|
<div align="center" markdown="1">
|
|
|
|
# Helmfile
|
|
|
|
[](https://github.com/helmfile/helmfile/actions/workflows/ci.yaml?query=branch%3Amain)
|
|
[](https://github.com/helmfile/helmfile/pkgs/container/helmfile)
|
|
[](https://goreportcard.com/report/github.com/helmfile/helmfile)
|
|
[](https://slack.sweetops.com)
|
|
[](https://helmfile.readthedocs.io/en/latest/)
|
|
[](https://gurubase.io/g/helmfile)
|
|
[](https://zread.ai/helmfile/helmfile)
|
|
|
|
Deploy Kubernetes Helm Charts
|
|
<br />
|
|
|
|
</div>
|
|
|
|
English | [简体中文](./README-zh_CN.md)
|
|
|
|
## About
|
|
|
|
Helmfile is a declarative spec for deploying helm charts. It lets you...
|
|
|
|
* Keep a directory of chart value files and maintain changes in version control.
|
|
* Apply CI/CD to configuration changes.
|
|
* Periodically sync to avoid skew in environments.
|
|
|
|
To avoid upgrades for each iteration of `helm`, the `helmfile` executable delegates to `helm` - as a result, the following must be installed
|
|
- [helm](https://helm.sh/docs/intro/install/)
|
|
- [helm-diff](https://github.com/databus23/helm-diff)
|
|
|
|
## Highlights
|
|
|
|
**Declarative**: Write, version-control, apply the desired state file for visibility and reproducibility.
|
|
|
|
**Modules**: Modularize common patterns of your infrastructure, distribute it via Git, S3, etc. to be reused across the entire company (See [#648](https://github.com/roboll/helmfile/pull/648))
|
|
|
|
**Versatility**: Manage your cluster consisting of charts, [kustomizations](https://github.com/kubernetes-sigs/kustomize), and directories of Kubernetes resources, turning everything to Helm releases (See [#673](https://github.com/roboll/helmfile/pull/673))
|
|
|
|
**Patch**: JSON/Strategic-Merge Patch Kubernetes resources before `helm-install`ing, without forking upstream charts (See [#673](https://github.com/roboll/helmfile/pull/673))
|
|
|
|
## Status
|
|
|
|
May 2025 Update
|
|
|
|
* Helmfile v1.0 and v1.1 has been released. We recommend upgrading directly to v1.1 if you are still using v0.x.
|
|
* If you haven't already upgraded, please go over this v1 proposal [here](docs/proposals/towards-1.0.md) to see a small list of breaking changes.
|
|
|
|
## Installation
|
|
|
|
**1: Binary Installation**
|
|
|
|
download one of [releases](https://github.com/helmfile/helmfile/releases)
|
|
|
|
**2: Package Manager**
|
|
|
|
* Archlinux: install via `pacman -S helmfile`
|
|
* openSUSE: install via `zypper in helmfile` assuming you are on Tumbleweed; if you are on Leap you must add the [kubic](https://download.opensuse.org/repositories/devel:/kubic/) repo for your distribution version once before that command, e.g. `zypper ar https://download.opensuse.org/repositories/devel:/kubic/openSUSE_Leap_\$releasever kubic`
|
|
* Windows (using [scoop](https://scoop.sh/)): `scoop install helmfile`
|
|
* macOS (using [homebrew](https://brew.sh/)): `brew install helmfile`
|
|
* Linux/macOS/Windows (using [mise](https://mise.jdx.dev)): `mise use -g helmfile@latest`
|
|
|
|
**3: Container**
|
|
|
|
For more details, see [run as a container](https://helmfile.readthedocs.io/en/latest/#running-as-a-container)
|
|
|
|
> Make sure to run `helmfile init` once after installation. Helmfile uses the [helm-diff](https://github.com/databus23/helm-diff) plugin.
|
|
|
|
**4: Build from source**
|
|
|
|
requirements: [Go](https://golang.org/dl/)
|
|
|
|
|
|
|
|
` go install github.com/helmfile/helmfile@latest `
|
|
## Getting Started
|
|
|
|
Let's start with a simple `helmfile` and gradually improve it to fit your use-case!
|
|
|
|
Generate a project scaffold with best-practice directory structure:
|
|
|
|
```console
|
|
helmfile create my-project && cd my-project
|
|
```
|
|
|
|
Or create a `helmfile.yaml` manually. Suppose the `helmfile.yaml` representing the desired state of your helm releases looks like:
|
|
|
|
```yaml
|
|
repositories:
|
|
- name: prometheus-community
|
|
url: https://prometheus-community.github.io/helm-charts
|
|
|
|
releases:
|
|
- name: prom-norbac-ubuntu
|
|
namespace: prometheus
|
|
chart: prometheus-community/prometheus
|
|
set:
|
|
- name: rbac.create
|
|
value: false
|
|
```
|
|
|
|
Sync your Kubernetes cluster state to the desired one by running:
|
|
|
|
```console
|
|
helmfile apply
|
|
```
|
|
|
|
Congratulations! You now have your first Prometheus deployment running inside
|
|
your cluster.
|
|
|
|
Iterate on the `helmfile.yaml` by referencing:
|
|
|
|
* [Configuration](https://helmfile.readthedocs.io/en/latest/#configuration)
|
|
* [CLI reference](https://helmfile.readthedocs.io/en/latest/#cli-reference)
|
|
* [Helmfile Best Practices Guide](https://helmfile.readthedocs.io/en/latest/writing-helmfile/)
|
|
|
|
## More complex examples
|
|
|
|
See: [multi-env-helmfile](https://github.com/helmfile/multi-env-helmfile)
|
|
|
|
## Docs
|
|
|
|
Please read [complete documentation](https://helmfile.readthedocs.io/)
|
|
|
|
## Contributing
|
|
|
|
Welcome to contribute together to make helmfile better: [contributing doc](https://helmfile.readthedocs.io/en/latest/contributing/)
|
|
|
|
## Attribution
|
|
|
|
We use:
|
|
|
|
* [semtag](https://github.com/pnikosis/semtag) for automated semver tagging.
|
|
I greatly appreciate the author(pnikosis)'s effort on creating it and their
|
|
kindness to share it!
|
|
|
|
## Users
|
|
|
|
Helmfile has been used by many users in production:
|
|
|
|
* [gitlab.com](https://gitlab.com)
|
|
* [reddit.com](https://reddit.com)
|
|
* [Jenkins](https://jenkins.io)
|
|
* ...
|
|
|
|
For more users, please see: [Users](https://helmfile.readthedocs.io/en/latest/users/)
|
|
|
|
## License
|
|
|
|
[MIT](https://github.com/helmfile/helmfile/blob/main/LICENSE)
|
|
|
|
## Star History
|
|
|
|
[](https://star-history.com/#helmfile/helmfile&Date)
|