diff --git a/docs/valuesYaml-valuesFiles.md b/docs/valuesYaml-valuesFiles.md new file mode 100644 index 000000000..ce883cbc8 --- /dev/null +++ b/docs/valuesYaml-valuesFiles.md @@ -0,0 +1,64 @@ +# Understanding Helm values.yaml vs. Fleet valuesFiles + +When using Fleet with Helm, you often confuse the chart’s built-in `values.yaml` with additional values files referenced in `fleet.yaml`. These files serve different purposes, and it’s important to understand how they interact. + +![Understanding Helm values.yaml vs Fleet valuesFiles with best practices](../static/img/helm-value-fleet-yaml.svg) + +## Helm chart’s values.yaml + +Every Helm chart includes a `values.yaml`. This file contains the default configuration values used when deploying the chart. + +* It’s automatically applied by Helm and Fleet. You don’t need to reference it in `fleet.yaml`. +* It always acts as the baseline when the Fleet agent installs the chart. +* Any overrides you provide later (via Fleet `valuesFiles` or `values: parameters`) replace or extend these defaults. + +**Example directory:** + +```bash +. +├── Chart.yaml +├── fleet.yaml +├── README.md +├── templates/ +│ ├── deployment.yaml +│ └── service.yaml +└── values.yaml \# chart defaults +``` + +You can use Helm chart’s `values.yaml` file to: + +* Provide default settings and allow users to override defaults without modifying the chart itself. +* Define common Kubernetes resource defaults. + +:::note +Helm chart `values.yaml` does not support templating. Any substitutions happen during chart rendering before Fleet applies the chart. + +* You cannot use shell-style variables (for example, `${var}`) inside this file. +* If `${var}` appears, Helm treats it as plain text—you don’t need to escape it. +::: + +## **Fleet valuesFiles referenced from fleet.yaml** + +Fleet lets you reference additional values files through `fleet.yaml`. These files override or extend the chart’s baseline defaults. + +* A values Files entry is equivalent to copy-pasting the contents of that file into the values: section of `fleet.yaml`. +* It’s mainly a convenience feature for splitting values into multiple files. +* Unlike Helm chart `values.yaml`, Fleet’s values files support templating, which enables dynamic configuration per environment. + +**Example fleet.yaml:** +```yaml +helm: + valuesFiles: + \- values.prod.yaml \# overrides baseline +``` + +You can use fleet `valuesFiles` referenced from `fleet.yaml` to: + +* Apply environment-specific overrides (dev, staging, prod). +* Enable advanced features not included in chart defaults. + +## **Best practice** + +Whether you use helm `values.yaml`, `fleet.yaml` values:, or `valuesFiles`, never store credentials in these files. + +The recommended and safer approach is to use `valuesFrom`, which references Kubernetes Secrets or ConfigMaps. Although this requires creating the Secrets on downstream clusters, it ensures sensitive data is stored securely. diff --git a/sidebars.js b/sidebars.js index 5d352366e..829b1aa9f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -53,7 +53,8 @@ module.exports = { {type:'doc', id:'observability'}, {type:'doc', id:'helm-ops'}, {type:'doc', id:'rollout'}, - {type:'doc', id:'fine-tune-error'} + {type:'doc', id:'fine-tune-error'}, + {type:'doc', id:'valuesYaml-valuesFiles'} ], }, { diff --git a/static/img/helm-value-fleet-yaml.svg b/static/img/helm-value-fleet-yaml.svg new file mode 100644 index 000000000..42cb09d26 --- /dev/null +++ b/static/img/helm-value-fleet-yaml.svg @@ -0,0 +1,4 @@ + + +Helm chart's values.yamlFleet valuesFilesfleet.yaml values: overwrite valuesValues applied by FleetvaluesFrom (secrets) \ No newline at end of file