README.md.gotmpl

{{ template "chart.header" . }}
{{ template "chart.description" . }}

## TL;DR;

```console
helm repo add christianhuth https://charts.christianhuth.de
helm repo update
helm install my-release christianhuth/proxysql
```

## Introduction

This chart bootstraps a [ProxySQL](https://github.com/sysown/proxysql) deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.

## Prerequisites

- Kubernetes 1.19+

## Installing the Chart

To install the chart with the release name `my-release`:

```console
helm repo add christianhuth https://charts.christianhuth.de
helm repo update
helm install my-release christianhuth/proxysql
```

These commands deploy proxysql on the Kubernetes cluster in the default configuration. The [Values](#values) section lists the values that can be configured during installation.

> **Tip**: List all releases using `helm list`

## Uninstalling the Chart

To uninstall the `my-release` deployment:

```console
helm uninstall my-release
```

The command removes all the Kubernetes components associated with the chart and deletes the release.

## Configuration ownership: Helm values vs. runtime admin changes

ProxySQL can be configured two ways: through the config file this chart renders from Helm values (`/etc/proxysql.cnf`), and at runtime through the admin interface (`LOAD ... TO RUNTIME; SAVE ... TO DISK`), which persists to the config database (`/var/lib/proxysql/proxysql.db`).

The `proxysql.config.reloadOnRestart` value controls which side wins after a restart:

- `true` (default): ProxySQL starts with the `--reload` flag. On **every** container start the rendered config file is merged over the persisted config database — every key present in the config file is reset to its Helm-values state, silently reverting runtime admin changes to those keys, even with persistence enabled. Use this when Helm values are your single source of truth (e.g. GitOps). Note that ProxySQL's startup message "Ignoring configuration file ... as the config DB has higher precedence" is printed even when `--reload` has just merged the file, so do not rely on it.
- `false`: the config file is only read when no config database exists yet (first boot). Runtime admin changes are durable across restarts — this matches ProxySQL's documented operating model. The trade-off: with persistence enabled, later changes to Helm values are **not** applied to an existing config database; reconfigure through the admin interface, or delete `/var/lib/proxysql/proxysql.db` (or the PVC) to re-bootstrap from the config file.

If you manage ProxySQL configuration at runtime through the admin interface, set `reloadOnRestart: false` — otherwise a full restart of all replicas (node pool upgrade, StatefulSet recreation, scale-from-zero) reverts your runtime configuration. With multiple clustered replicas this revert is masked by peer-sync during rolling restarts and only surfaces when all pods boot fresh simultaneously.

{{ template "chart.valuesSection" . }}

Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`.

Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example,

```console
helm install my-release -f values.yaml christianhuth/proxysql
```

## Upgrading the Chart

### To 3.0.0

This major updates the way the configuration of ProxySQL is managed. The configuration is now stored in a Kubernetes Secret and mounted as a file into the container. This increases security, but comes with the cost of having to manage the configuration file outside of the chart, when using GitOps. The old way of managing the configuration via chart values is still supported.