Documentation / memcached
Memcached Helm Chart
An enterprise-grade Helm chart for deploying Memcached on Kubernetes. Provides a production-ready, highly-configurable distributed memory caching system with built-in observability, security hardening, and high-availability features.
Prerequisites
- Kubernetes 1.23+
- Helm 3.x
- (Optional) Netdata or any OpenMetrics-compatible collector for metrics scraping
Installation
helm install my-cache ./charts/memcached
With custom values:
helm install my-cache ./charts/memcached -f my-values.yaml
Uninstallation
helm uninstall my-cache
Architecture
The chart supports two workload types:
- Deployment (default) – Best for stateless caching where pod identity is not important.
- StatefulSet – Enable with
useStatefulSet: truefor stable network identities and headless service DNS. Useful when clients need to address individual memcached nodes (e.g., consistent hashing).
Parameters
Global
| Parameter | Description | Default |
|---|---|---|
replicaCount |
Number of memcached replicas | 1 |
image.repository |
Memcached image repository | 1x.ax/tersane/core/memcached/memcached |
image.tag |
Image tag, pinned by digest (empty means appVersion) |
Set in each release |
image.pullPolicy |
Image pull policy | IfNotPresent |
imagePullSecrets |
Image pull secrets | [{name: 1x-ax}] |
test.image |
Image of the helm test Pod, pinned by digest |
Set in each release |
nameOverride |
Override chart name | "" |
fullnameOverride |
Override full release name | "" |
useStatefulSet |
Deploy as StatefulSet instead of Deployment | false |
Memcached Configuration
All core memcached tuning parameters are exposed as values:
| Parameter | Description | Default |
|---|---|---|
memcached.maxMemory |
Max memory for items in MB (-m) |
64 |
memcached.maxConnections |
Max simultaneous connections (-c) |
1024 |
memcached.threads |
Number of worker threads (-t) |
4 |
memcached.defaultExpiry |
Default item TTL in seconds (0 = no expiry) | 0 |
memcached.maxItemSize |
Max item size, supports k/m units (-I) |
"1m" |
memcached.growthFactor |
Chunk size growth factor (-f) |
1.25 |
memcached.minItemSize |
Min allocated space per key in bytes (-n) |
48 |
memcached.listenBacklog |
Listen backlog queue limit (-b) |
1024 |
memcached.enableCas |
Enable CAS (Check And Set) operations | true |
memcached.disableFlushAll |
Disable the flush_all command |
false |
memcached.disableWatch |
Disable the watch / live logging command |
false |
memcached.largepages |
Enable large memory pages (requires OS support) | false |
memcached.protocol |
Protocol mode: "auto", "ascii", or "binary" |
"auto" |
memcached.verbosity |
Log verbosity: 0=none, 1=verbose, 2=very verbose | 0 |
memcached.extraFlags |
Additional CLI flags passed to memcached | [] |
SASL Authentication
| Parameter | Description | Default |
|---|---|---|
memcached.sasl.enabled |
Enable SASL authentication | false |
memcached.sasl.existingSecret |
Name of an existing Secret with the keys username and password |
"" |
memcached.sasl.username |
SASL username (if not using existing secret); it must not contain @ or : |
"" |
memcached.sasl.password |
SASL password (if not using existing secret) | "" |
memcached.sasl.realm |
The realm clients name after their username | memcached |
memcached.sasl.initResources |
Requests and limits of the init container that writes the SASL files | 10m/16Mi requested, 100m/32Mi limit |
With SASL enabled, memcached accepts only clients that authenticate with SASL PLAIN over the binary protocol:
- Clients authenticate as
<username>@<realm>, for exampletester@memcachedwith the default realm. memcached adds a realm to every username, and without one named by the client it uses the Pod’s hostname, which differs for each Pod. - Changing
memcached.sasl.realmon a running release breaks every client, until each one uses the new realm. - The binary protocol is required. The chart sets it, and refuses
memcached.protocol: asciiwith SASL. A client that uses the ASCII protocol cannot use SASL. - SASL PLAIN sends the password unencrypted. Limit which clients can connect with
networkPolicy.enabledandnetworkPolicy.allowFrom. - The metrics exporter cannot authenticate with SASL, so the chart refuses
metrics.enabledtogether with SASL. A collector that reads memcached’s statistics directly, such as Netdata’s, does not authenticate either and is refused by memcached. A release with SASL therefore has no metrics by either route. This is a known gap. - An init container, on the memcached image, writes memcached’s SASL configuration and password file from the Secret into a memory-backed volume. The password is read from the Secret’s file, never from an argument or an environment variable. The Secret is not mounted in the memcached container.
Service
| Parameter | Description | Default |
|---|---|---|
service.type |
Kubernetes service type | ClusterIP |
service.port |
Service port | 11211 |
service.nodePort |
Node port (when type is NodePort) | "" |
service.annotations |
Service annotations | {} |
headlessService.enabled |
Create headless service (for StatefulSet) | false |
headlessService.annotations |
Headless service annotations | {} |
Service Account
| Parameter | Description | Default |
|---|---|---|
serviceAccount.create |
Create a service account | false |
serviceAccount.automount |
Automount service account token | true |
serviceAccount.annotations |
Service account annotations | {} |
serviceAccount.name |
Service account name override | "" |
Security
| Parameter | Description | Default |
|---|---|---|
podSecurityContext.fsGroup |
Pod filesystem group | 11211 |
podSecurityContext.seccompProfile.type |
Seccomp profile for every container in the Pod | RuntimeDefault |
securityContext.runAsUser |
Container user ID | 11211 |
securityContext.runAsGroup |
Container group ID | 11211 |
securityContext.runAsNonRoot |
Require non-root execution | true |
securityContext.readOnlyRootFilesystem |
Read-only root filesystem | true |
securityContext.allowPrivilegeEscalation |
Disallow privilege escalation | false |
securityContext.capabilities.drop |
Linux capabilities to drop | ["ALL"] |
Resources and Probes
| Parameter | Description | Default |
|---|---|---|
resources.limits.cpu |
CPU limit | 500m |
resources.limits.memory |
Memory limit | 256Mi |
resources.requests.cpu |
CPU request | 100m |
resources.requests.memory |
Memory request | 128Mi |
startupProbe.enabled |
Enable startup probe | true |
livenessProbe.enabled |
Enable liveness probe | true |
readinessProbe.enabled |
Enable readiness probe | true |
Pod Disruption Budget
| Parameter | Description | Default |
|---|---|---|
podDisruptionBudget.enabled |
Enable PDB | false |
podDisruptionBudget.minAvailable |
Minimum available pods | 1 |
podDisruptionBudget.maxUnavailable |
Max unavailable pods (alternative) | - |
Network Policy
| Parameter | Description | Default |
|---|---|---|
networkPolicy.enabled |
Enable NetworkPolicy | false |
networkPolicy.allowFrom |
Allowed ingress sources (podSelector/namespaceSelector) | [] |
Metrics and Monitoring
The chart deploys a memcached-exporter sidecar that exposes a /metrics endpoint in OpenMetrics/Prometheus format. When enabled, pod annotations are added so that Netdata (or any annotation-based collector) auto-discovers and scrapes the pods directly.
| Parameter | Description | Default |
|---|---|---|
metrics.enabled |
Enable Prometheus exporter sidecar | false |
metrics.image.repository |
Exporter image | 1x.ax/tersane/core/prometheus/memcached-exporter |
metrics.image.tag |
Exporter image tag, pinned by digest | Set in each release |
metrics.port |
Exporter listen port | 9150 |
metrics.resources |
Exporter resource limits/requests | See values.yaml |
metrics.podAnnotations |
Pod annotations for metrics discovery | prometheus.io/scrape: "true", etc. |
Default pod annotations when metrics are enabled:
prometheus.io/scrape: "true"
prometheus.io/port: "9150"
prometheus.io/path: "/metrics"
Scheduling
| Parameter | Description | Default |
|---|---|---|
nodeSelector |
Node selector labels | {} |
tolerations |
Pod tolerations | [] |
affinity |
Pod affinity rules | {} |
topologySpreadConstraints |
Topology spread constraints | [] |
priorityClassName |
Pod priority class | "" |
terminationGracePeriodSeconds |
Graceful shutdown timeout | 30 |
Extensions
| Parameter | Description | Default |
|---|---|---|
podAnnotations |
Additional pod annotations | {} |
podLabels |
Additional pod labels | {} |
extraEnv |
Extra environment variables | [] |
extraInitContainers |
Extra init containers | [] |
extraVolumes |
Extra volumes | [] |
extraVolumeMounts |
Extra volume mounts | [] |
Pod Security
The chart meets the Kubernetes restricted Pod Security Standard by default, and can be installed in a namespace that enforces it. Every container, the metrics exporter and the test Pod included, runs as a user other than root, cannot escalate its privileges, drops all Linux capabilities and runs under the container runtime’s default seccomp profile.
An upgrade from a release without the seccomp profile restarts the Pods. To remove the profile, which is not recommended, set podSecurityContext.seccompProfile to null; the Pods then meet baseline only. Containers added through extraInitContainers must carry their own security context to keep the Pod at restricted.
Examples
Minimal production setup
replicaCount: 3
memcached:
maxMemory: 256
maxConnections: 2048
threads: 4
disableFlushAll: true
resources:
limits:
cpu: "1"
memory: 512Mi
requests:
cpu: 250m
memory: 384Mi
podDisruptionBudget:
enabled: true
minAvailable: 2
topologySpreadConstraints:
- maxSkew: 1
topologyKey: kubernetes.io/hostname
whenUnsatisfiable: DoNotSchedule
labelSelector:
matchLabels: {}
With metrics for Netdata scraping
metrics:
enabled: true
That’s it – Netdata auto-discovers pods via the prometheus.io/* annotations that are added automatically. The exporter sidecar exposes memcached stats on port 9150 at /metrics.
StatefulSet with headless service
useStatefulSet: true
replicaCount: 3
headlessService:
enabled: true
This creates stable DNS names like my-cache-memcached-0.my-cache-memcached-headless.namespace.svc.cluster.local for client-side consistent hashing.
With SASL authentication
memcached:
sasl:
enabled: true
existingSecret: my-memcached-credentials # keys: username, password
networkPolicy:
enabled: true
allowFrom:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: my-app
A client in PHP, with the Memcached extension, if the Secret’s username is app:
$cache = new Memcached();
$cache->setOption(Memcached::OPT_BINARY_PROTOCOL, true);
$cache->setSaslAuthData('app@memcached', getenv('MEMCACHED_PASSWORD'));
$cache->addServer('my-cache-memcached.my-namespace.svc', 11211);
$cache->set('key', 'value');
High-throughput tuning
memcached:
maxMemory: 1024
maxConnections: 4096
threads: 8
maxItemSize: "5m"
growthFactor: 1.05
listenBacklog: 2048
extraFlags:
- "-o modern"
- "-o slab_reassign"
- "-o slab_automove=1"
- "-o hashpower=20"
resources:
limits:
cpu: "4"
memory: 2Gi
requests:
cpu: "2"
memory: 1536Mi
With NetworkPolicy (restrict access)
The policy is a Calico projectcalico.org/v3 NetworkPolicy, so it requires Calico with its API server, the network fabric the Bahriya Kubernetes Engine installs; the chart has no standard networking.k8s.io NetworkPolicy in its place. It is off by default.
networkPolicy:
enabled: true
allowFrom:
- podSelector:
matchLabels:
app: my-app
- namespaceSelector:
matchLabels:
name: my-namespace
Testing
Run the built-in Helm test:
helm test my-cache
This verifies the memcached service is reachable and responding to stats commands. With SASL enabled, it checks instead that memcached offers SASL PLAIN, which needs no credentials.
Upgrading
To 1.2
- The memcached image is built on Alpine Linux. Earlier versions ran on Debian. It runs as the same user (11211), with the same command.
- memcached and the exporter move to newer releases, which the release notes name.
- Every image is pinned by digest.
- The upgrade replaces the memcached Pods, so the cache starts empty.
- SASL now works. In earlier versions memcached did not start with
memcached.sasl.enabled: true. See SASL Authentication for how clients authenticate. - No values need to change.
To 1.1
The Pods gain the container runtime’s default seccomp profile, so the upgrade restarts them. No values need to change; see Pod Security.
To 1.x
This is the initial release. No migration steps required.