proxysql

proxysql

A proxysql Helm chart for Kubernetes. Offers option to expose web interface through Ingress. Uses ServiceMonitor to collect metrics.

TL;DR;

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

Introduction

This chart bootstraps a ProxySQL deployment on a Kubernetes cluster using the Helm package manager.

Prerequisites

• Kubernetes 1.19+

Installing the Chart

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

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 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:

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.

Values

Key	Type	Default	Description
affinity	object	{}	Affinity settings for pod assignment
autoscaling.enabled	bool	false
autoscaling.maxReplicas	int	100
autoscaling.minReplicas	int	1
autoscaling.targetCPUUtilizationPercentage	int	80
fullnameOverride	string	""	String to fully override "proxysql.fullname"
image.pullPolicy	string	"Always"	image pull policy
image.registry	string	"docker.io"	image registory
image.repository	string	"proxysql/proxysql"	image repository
image.tag	string	"3.0.11"	Overrides the image tag
imagePullSecrets	list	[]	If defined, uses a Secret to pull an image from a private Docker registry or repository.
ingress.annotations."nginx.ingress.kubernetes.io/backend-protocol"	string	"HTTPS"
ingress.className	string	""
ingress.enabled	bool	false
ingress.hosts[0].host	string	"chart-example.local"
ingress.hosts[0].paths[0].path	string	"/"
ingress.hosts[0].paths[0].pathType	string	"ImplementationSpecific"
ingress.tls	list	[]
metrics.enabled	bool	false
metrics.serviceMonitor.additionalLabels	object	{}
metrics.serviceMonitor.enabled	bool	false
nameOverride	string	""	Provide a name in place of proxysql
nodeSelector	object	{}	Node labels for pod assignment
podAnnotations	object	{}	Annotations to be added to pods
podSecurityContext	object	{"fsGroup":999,"runAsGroup":999,"runAsNonRoot":true,"runAsUser":999}	pod-level security context
proxysql.admin.password	string	"admin"
proxysql.admin.user	string	"admin"
proxysql.cluster.claim.accessModes[0]	string	"ReadWriteOnce"
proxysql.cluster.claim.enabled	bool	true
proxysql.cluster.claim.size	string	"1Gi"
proxysql.cluster.claim.storageClassName	string	"default"
proxysql.cluster.enabled	bool	false
proxysql.cluster.password	string	"cluster"
proxysql.cluster.user	string	"cluster"
proxysql.config.existingSecret	string	""	Use an existing Secret containing the proxysql.cnf config. The secret has to contain the key proxysql.cnf. When it's set the chart will not generate a Secret.
proxysql.config.reloadOnRestart	bool	true	Start ProxySQL with the --reload flag. When true, the rendered proxysql.cnf is merged into the persisted config DB on every container start, overwriting runtime admin changes (LOAD ... TO RUNTIME; SAVE ... TO DISK) for every key present in the config file. When false, the config file is only read when no config DB exists yet (first boot), making runtime admin changes durable across restarts, but Helm values changes to the config then no longer apply over an existing config DB.
proxysql.monitor.enabled	bool	false
proxysql.monitor.replicationLagInterval	int	10000
proxysql.monitor.replicationLagTimeout	int	1500
proxysql.monitor.slaveLagWhenNull	int	60
proxysql.monitor.writerAsReader	bool	true
proxysql.mysql.autocommitFalseIsTransaction	bool	false
proxysql.mysql.connectionMaxAgeMS	int	0
proxysql.mysql.galera.enabled	bool	false
proxysql.mysql.galera.maxWriters	int	1
proxysql.mysql.galera.writerAsReader	bool	true
proxysql.mysql.maxConnections	int	2048
proxysql.mysql.port	int	3306
proxysql.mysql.queryRetriesOnFailure	int	2
proxysql.mysql.queyCacheSizeMB	int	256
proxysql.mysql.readWriteSplit	bool	true
proxysql.mysql.servers	list	[]
proxysql.mysql.slave.checkType	string	"read_only"
proxysql.mysql.slave.enabled	bool	false
proxysql.mysql.users	list	[]
proxysql.mysql.version	string	"5.7.34"
proxysql.mysql.waitTimeout	int	28800000
proxysql.port	int	6032
proxysql.web.enabled	bool	true
proxysql.web.password	string	"sadmin"
proxysql.web.port	int	443
proxysql.web.user	string	"sadmin"
replicaCount	int	1	Number of replicas
resources	object	{}	Resource limits and requests for the headwind pods.
revisionHistoryLimit	int	10	The number of old ReplicaSets to retain
route.main.additionalRules	list	[]	Additional custom rules that can be added to the route
route.main.annotations	object	{}	Add annotations to the route
route.main.apiVersion	string	"gateway.networking.k8s.io/v1"	Set the route apiVersion, e.g. gateway.networking.k8s.io/v1 or gateway.networking.k8s.io/v1alpha2
route.main.enabled	bool	false	Enables or disables the route
route.main.filters	list	[]	Filters define the filters that are applied to requests that match this rule.
route.main.hostnames	list	[]	Hostnames to be matched
route.main.httpsRedirect	bool	false	adds a filter for redirecting to https (HTTP 301 Moved Permanently). To redirect HTTP traffic to HTTPS, you need to have a Gateway with both HTTP and HTTPS listeners. Matches and filters do not take effect if enabled. Ref. https://gateway-api.sigs.k8s.io/guides/http-redirect-rewrite/
route.main.kind	string	"HTTPRoute"	Set the route kind Valid options are GRPCRoute, HTTPRoute, TCPRoute, TLSRoute, UDPRoute
route.main.labels	object	{}	Add labels to the route
route.main.matches	list	see values.yaml	define conditions used for matching the rule against incoming HTTP requests.
route.main.parentRefs	list	[]	Parent references (Gateway)
route.main.timeouts	object	{}	defines the timeouts that can be configured for an HTTP request
securityContext	object	{}	container-level security context
service.type	string	"ClusterIP"	Kubernetes service type
serviceAccount.annotations	object	{}	Annotations to add to the service account
serviceAccount.create	bool	true	Specifies whether a service account should be created
serviceAccount.name	string	""	The name of the service account to use. If not set and create is true, a name is generated using the fullname template
tolerations	list	[]	Toleration labels for pod assignment

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,

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.