Skip to content
Memcached icon
v1.1.0App: v1.6.45Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Memcached

Memcached for Kubernetes using the official docker.io/library/memcached image.

The chart supports a simple standalone cache for development and a distributed set of independent Memcached nodes for production workloads where clients perform sharding or consistent hashing.

Install

Standard Memcached pool

For a typical production-style Memcached pool, run independent cache nodes and let the application client distribute keys across them:

architecture: distributed
replicaCount: 3
helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install memcached helmforge/memcached -f values.yaml

This creates three Memcached pods. The chart does not replicate cache entries or shard keys inside Kubernetes. Use a Memcached client library that supports multiple servers, preferably with consistent hashing. The headless Service gives pod-aware clients stable DNS names for explicit pool membership.

HTTPS repository

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install memcached helmforge/memcached -f values.yaml

OCI registry

helm install memcached oci://ghcr.io/helmforgedev/helm/memcached -f values.yaml

Features

  • official Memcached image with pinned default tag
  • standalone and distributed topologies
  • stable StatefulSet pod DNS through a headless Service
  • client Service with optional dual-stack fields
  • optional ASCII auth file or SASL startup mode
  • optional TLS using an existing Kubernetes TLS Secret
  • optional extstore for flash-backed cache extension
  • optional Prometheus memcached exporter sidecar
  • optional ServiceMonitor and PrometheusRule
  • optional NetworkPolicy ingress, metrics, and egress rules
  • optional PodDisruptionBudget and HPA
  • optional External Secrets Operator v1 integration
  • hardened default pod and container security contexts
  • extension points through extraEnv, extraVolumes, extraContainers, and extraManifests

Topologies

Architecture Contract Typical use
standalone One Memcached pod behind one Service. Development, tests, small non-critical caches.
distributed Multiple independent Memcached pods with a client Service and stable pod DNS. Standard Memcached pools where the client library distributes keys.

Memcached does not replicate cache entries between nodes. In distributed mode, the client is responsible for choosing a node for each key. Use client-side consistent hashing when cache hit ratio matters during scale events.

Development quick start

architecture: standalone
replicaCount: 1
helm install memcached helmforge/memcached -f values.yaml

Test from inside the cluster:

kubectl run memcached-client --rm -it --restart=Never \
  --image=docker.io/library/busybox:1.37.0 -- \
  sh -ec "printf 'set hello 0 60 5\r\nworld\r\nget hello\r\nquit\r\n' | nc memcached 11211"

Production path

Production-ready deployments are possible through values. The defaults stay development-friendly because many users first need a disposable cache for local and CI environments.

Start from examples/production.yaml and adapt:

  • use architecture: distributed with at least three nodes (replicaCount: 3)
  • size memcached.memoryLimitMB and Kubernetes memory limits together
  • set explicit CPU and memory requests
  • disable flush_all with memcached.disableFlushAll=true
  • enable authentication or place Memcached behind trusted network boundaries
  • enable TLS when clients and Memcached exchange data across untrusted networks
  • enable networkPolicy.enabled when the cluster CNI enforces policies
  • keep serviceAccount.automountServiceAccountToken=false
  • enable metrics and alerts
  • use topology spread constraints or anti-affinity across nodes

For a production checklist, cache sizing guidance, and operational probes, read docs/production.md.

Examples

Authentication

Authentication is disabled by default. Memcached authentication is not a full authorization system; it is a connection gate.

ASCII auth file mode:

auth:
  enabled: true
  mode: ascii
  username: app
  password: change-me

Existing Secret:

auth:
  enabled: true
  existingSecret: memcached-auth
  authFileKey: authfile

The Secret key must contain lines in Memcached auth-file format:

app:change-me

ASCII auth forces Memcached to start with ASCII protocol because upstream disables binary protocol when -Y is active. Clients authenticate by sending a fake set command with a username password payload before regular cache commands. The payload byte length must match the credentials string.

SASL mode starts Memcached with -S and should be used only with clients that support binary protocol SASL. The official Memcached image does not build a SASL database from plain username/password values at startup, so SASL requires an existing Secret with a memcached.conf file and a prepared sasldb file:

auth:
  enabled: true
  mode: sasl
  existingSecret: memcached-sasl
  sasl:
    configKey: memcached.conf
    databaseKey: memcachedsasldb

memcached:
  protocol: binary

The memcached.conf file should point at the mounted database path, for example:

mech_list: plain
sasldb_path: /sasl2/memcachedsasldb

External Secrets

External Secrets Operator integration is optional and uses external-secrets.io/v1. It is only valid together with auth.enabled=true; otherwise the chart would create credentials that Memcached does not consume.

auth:
  enabled: true
  existingSecret: memcached-auth

externalSecrets:
  enabled: true
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  data:
    - secretKey: authfile
      remoteRef:
        key: memcached/auth
        property: authfile

TLS

TLS uses an existing Secret. The chart does not generate private keys.

tls:
  enabled: true
  existingSecret: memcached-tls
  certKey: tls.crt
  keyKey: tls.key
  caKey: ca.crt
  verifyMode: "0"
  minVersion: "2"

verifyMode and minVersion map to Memcached OpenSSL extended options. tls.caKey is optional and should be set only when the Secret contains a CA file. For mutual TLS, provide a CA certificate and set the verify mode required by your client policy.

When TLS is enabled, the chart omits TCP liveness/readiness probes because kubelet TCP probes do not perform a TLS handshake and cause noisy Memcached accept logs.

Extstore

Extstore allows Memcached to keep larger or colder objects on a local file-backed cache path. It is cache storage, not durable application data.

Ephemeral extstore:

extstore:
  enabled: true
  size: 4G

PVC-backed extstore:

extstore:
  enabled: true
  persistence:
    enabled: true
    size: 20Gi
    retentionPolicy:
      whenDeleted: Retain
      whenScaled: Retain

Do not combine PVC-backed extstore with HPA. The chart blocks that combination because each PVC is pod-local. The default retention policy preserves extstore PVCs when the StatefulSet is deleted or scaled down. Set either policy to Delete only when discarding the associated cache files is intentional. On Kubernetes 1.26, Delete also requires the StatefulSetAutoDeletePVC feature gate on both the API server and controller manager. Without that gate, use the default Retain policy and manage PVC deletion explicitly. The gate is enabled by default from Kubernetes 1.27 through 1.31 but can still be disabled, so operators must verify the controller manager setting before relying on automatic deletion. The feature is stable from Kubernetes 1.32.

Autoscaling

HPA is available only for architecture=distributed. Standalone mode is intentionally fixed to one pod. When CPU utilization scaling is enabled, set resources.requests.cpu; when memory utilization scaling is enabled, set resources.requests.memory. Kubernetes needs those requests to compute utilization percentages.

Metrics

Metrics are exposed through a sidecar exporter.

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

The exporter scrapes localhost:11211 from the pod. Validate exporter compatibility before combining it with strict auth or TLS-only listener policies.

The upstream exporter supports TLS but does not support Memcached authentication. The chart blocks metrics.enabled=true together with auth.enabled=true.

Exporter with Memcached TLS:

tls:
  enabled: true
  existingSecret: memcached-tls

metrics:
  enabled: true
  memcachedTLS:
    enabled: true

When metrics.memcachedTLS.enabled=true, the exporter still connects to the local pod address but verifies TLS with metrics.memcachedTLS.serverName. If unset, the chart uses <release>-memcached.<namespace>.svc; make sure the Memcached certificate includes that Service DNS name or set an explicit server name.

Networking

The chart creates:

  • <release>-memcached-headless for StatefulSet pod DNS
  • <release>-memcached for clients
  • <release>-memcached-metrics when metrics are enabled

Dual-stack Services:

service:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv4
    - IPv6

When service.ipFamilies includes IPv6 and memcached.listenAddress is left at the default 0.0.0.0, the chart starts Memcached with 0.0.0.0,:: so both IPv4 and IPv6 Service paths have a listener. Explicit memcached.listenAddress overrides are preserved for clusters that require a specific bind policy. The same dual-stack fields are applied to the client, headless, and metrics Services so monitoring traffic follows the same cluster IP family policy as cache traffic.

NetworkPolicy:

networkPolicy:
  enabled: true
  egress:
    enabled: true
    allowSameNamespace: true
    allowDNS: true
    extraEgress: []
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-------|---------|-------------| | architecture | standalone | standalone or distributed. | | replicaCount | 1 | Number of Memcached pods. Must be 1 for standalone. | | commonAnnotations | {} | Annotations added to every rendered resource; resource-specific annotations take precedence. | | image.repository | docker.io/library/memcached | Official Memcached image. | | image.tag | 1.6.45 | Pinned image tag. | | memcached.memoryLimitMB | 64 | Memcached item memory limit passed to -m. | | memcached.maxConnections | 1024 | Maximum simultaneous connections. | | memcached.threads | 4 | Worker threads. | | memcached.maxItemSize | 1m | Maximum item size passed to -I. | | auth.enabled | false | Enables auth file mounting. | | auth.mode | ascii | ascii or sasl. | | auth.sasl.configKey | memcached.conf | Secret key containing SASL configuration for SASL mode. | | auth.sasl.databaseKey | memcachedsasldb | Secret key containing a prepared SASL database for SASL mode. | | tls.enabled | false | Enables TLS startup flags. | | extstore.enabled | false | Enables Memcached extstore options. | | extstore.persistence.retentionPolicy.whenDeleted | Retain | PVC retention when the StatefulSet is deleted. | | extstore.persistence.retentionPolicy.whenScaled | Retain | PVC retention when replicas are scaled down. | | metrics.enabled | false | Enables Prometheus exporter sidecar and metrics Service. | | metrics.memcachedTLS.enabled | false | Enables TLS when the exporter scrapes Memcached. | | metrics.memcachedTLS.serverName | computed Service DNS | TLS verification name used by the metrics exporter. | | networkPolicy.enabled | false | Enables NetworkPolicy resources. | | networkPolicy.egress.allowSameNamespace | true | Allows cache and metrics responses to same-namespace clients. | | networkPolicy.egress.extraEgress | [] | Additional full NetworkPolicy egress rules appended to generated egress. | | pdb.maxUnavailable | "" | Optional PDB disruption limit. Explicit 0 is honored. | | service.ipFamilyPolicy | "" | Optional Kubernetes Service dual-stack policy. | | service.ipFamilies | [] | Optional ordered Service IP families. | | externalSecrets.enabled | false | Renders External Secrets Operator v1 resource. | | serviceAccount.automountServiceAccountToken | false | Keeps Kubernetes API token disabled by default. |

Security Scan

Security Scan: memcached

Framework Score
MITRE + NSA 80%

Security posture: acceptable. Kubescape reported full MITRE coverage and expected NSA hardening gaps for development defaults such as unset resource limits and optional runtime controls. Production values should enable resource requests/limits, NetworkPolicy, authentication or TLS where required, and anti-affinity or topology spread constraints.

Operations

Memcached 1.6.45 is the pinned upstream release. Upgrading is strongly advised when Memcached is reachable by untrusted clients; validate connectivity with a version or stats command after rollout.

Scale distributed mode:

helm upgrade memcached helmforge/memcached \
  --reuse-values \
  --set architecture=distributed \
  --set replicaCount=3

Inspect endpoints:

kubectl get endpoints memcached
kubectl get pods -l app.kubernetes.io/name=memcached

Check logs:

kubectl logs statefulset/memcached -c memcached

Troubleshooting

Use the release name and namespace chosen during installation:

RELEASE=memcached
NAMESPACE=default
kubectl rollout status statefulset \
  --selector "app.kubernetes.io/instance=${RELEASE}" --namespace "${NAMESPACE}"
kubectl get service,endpoints,pod \
  --selector "app.kubernetes.io/instance=${RELEASE}" --namespace "${NAMESPACE}"
kubectl logs --selector "app.kubernetes.io/instance=${RELEASE},app.kubernetes.io/component=memcached" \
  --namespace "${NAMESPACE}" --container memcached --tail=200
helm test "${RELEASE}" --namespace "${NAMESPACE}"

If distributed clients lose keys after scaling, confirm that the client uses consistent hashing; the servers do not replicate entries. For authentication failures, verify auth.mode, the mounted Secret keys, and client protocol support. For TLS, inspect the certificate SAN and remember that TCP probes are intentionally absent. For exporter failures, do not combine metrics with Memcached authentication, and verify the TLS server name when TLS is enabled.

Design

Read DESIGN.md for architecture diagrams, production trade-offs, and non-goals.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

Standalone is intentionally small. It is appropriate for development, CI, or production cases where a single cache instance is acceptable.

flowchart LR
  application[Application] --> service[Client Service]
  service --> pod[Memcached pod]
  pod --> cache[Volatile memory cache]
Official Contractvalues.schema.json

Memcached Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

140 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Common Annotations(1)

ParameterTypeDefaultDescription
commonAnnotationsobject-Chart configuration parameter

Cluster Domain(1)

ParameterTypeDefaultDescription
clusterDomainstring-Chart configuration parameter

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Headless Service(1)

ParameterTypeDefaultDescription
headlessService.annotationsobject-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Chart configuration parameter

Pod Security(5)

ParameterTypeDefaultDescription
podSecurityContext.runAsNonRootboolean-Chart configuration parameter
podSecurityContext.runAsUserinteger-Chart configuration parameter
podSecurityContext.runAsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter

Container Security(3)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Extra Env(1)

ParameterTypeDefaultDescription
extraEnvarray-Chart configuration parameter

Extra Env From(1)

ParameterTypeDefaultDescription
extraEnvFromarray-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Init Containers(1)

ParameterTypeDefaultDescription
extraInitContainersarray-Chart configuration parameter

Extra Containers(1)

ParameterTypeDefaultDescription
extraContainersarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

Architecture(1)

ParameterTypeDefaultDescription
architecturestring-Deployment topology. standalone creates one pod; distributed creates independent cache nodes.
Allowed:standalonedistributed

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger-Chart configuration parameter

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring1.6.45Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Memcached(15)

ParameterTypeDefaultDescription
memcached.memoryLimitMBinteger-Chart configuration parameter
memcached.maxConnectionsinteger-Chart configuration parameter
memcached.threadsinteger-Chart configuration parameter
memcached.maxItemSizestring-Chart configuration parameter
memcached.protocolstring-Chart configuration parameter
Allowed:autoasciibinary
memcached.listenAddressstring-Chart configuration parameter
memcached.udpPortinteger-Chart configuration parameter
memcached.disableFlushAllboolean-Chart configuration parameter
memcached.disableEvictionsboolean-Chart configuration parameter
memcached.disableCasboolean-Chart configuration parameter
memcached.disableWatchboolean-Chart configuration parameter
memcached.disableDumpingboolean-Chart configuration parameter
memcached.verbositystring-Chart configuration parameter
memcached.extendedOptionsarray-Chart configuration parameter
memcached.extraArgsarray-Chart configuration parameter

Authentication(9)

ParameterTypeDefaultDescription
auth.enabledboolean-Chart configuration parameter
auth.modestring-Chart configuration parameter
Allowed:asciisasl
auth.usernamestring-Chart configuration parameter
auth.passwordstring-Chart configuration parameter
auth.existingSecretstring-Chart configuration parameter
auth.authFileKeystring-Chart configuration parameter
auth.sasl.mountPathstring-Chart configuration parameter
auth.sasl.configKeystring-Chart configuration parameter
auth.sasl.databaseKeystring-Chart configuration parameter

External Secrets(6)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Chart configuration parameter
externalSecrets.refreshIntervalstring-Chart configuration parameter
externalSecrets.secretStoreRef.namestring-Chart configuration parameter
externalSecrets.secretStoreRef.kindstring-Chart configuration parameter
Allowed:SecretStoreClusterSecretStore
externalSecrets.target.creationPolicystring-Chart configuration parameter
externalSecrets.dataarray-Chart configuration parameter

TLS(12)

ParameterTypeDefaultDescription
tls.enabledboolean-Chart configuration parameter
tls.existingSecretstring-Chart configuration parameter
tls.certKeystring-Chart configuration parameter
tls.keyKeystring-Chart configuration parameter
tls.caKeystring-Chart configuration parameter
tls.verifyModestring-Chart configuration parameter
tls.minVersionstring-Chart configuration parameter
tls.volumePermissions.enabledboolean-Chart configuration parameter
tls.volumePermissions.image.repositorystring-Chart configuration parameter
tls.volumePermissions.image.tagstring-Chart configuration parameter
tls.volumePermissions.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
tls.volumePermissions.resourcesobject-Chart configuration parameter

Extstore(13)

ParameterTypeDefaultDescription
extstore.enabledboolean-Chart configuration parameter
extstore.pathstring-Chart configuration parameter
extstore.sizestring-Chart configuration parameter
extstore.pageSizeMBinteger-Chart configuration parameter
extstore.wbufSizeMBinteger-Chart configuration parameter
extstore.threadsinteger-Chart configuration parameter
extstore.itemSizeBytesinteger-Chart configuration parameter
extstore.persistence.enabledboolean-Chart configuration parameter
extstore.persistence.storageClassstring-Chart configuration parameter
extstore.persistence.accessModesarray-Chart configuration parameter
extstore.persistence.sizestring-Chart configuration parameter
extstore.persistence.retentionPolicy.whenDeletedstring-Chart configuration parameter
Allowed:RetainDelete
extstore.persistence.retentionPolicy.whenScaledstring-Chart configuration parameter
Allowed:RetainDelete

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.ipFamilyPolicystring-Service IP family policy. One of SingleStack, PreferDualStack, RequireDualStack, or empty for cluster default.
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Ordered Service IP families. Each entry is IPv4 or IPv6. Empty uses the cluster default.

Metrics & Observability(19)

ParameterTypeDefaultDescription
metrics.enabledboolean-Chart configuration parameter
metrics.image.repositorystring-Chart configuration parameter
metrics.image.tagstring-Chart configuration parameter
metrics.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
metrics.portinteger-Chart configuration parameter
metrics.resourcesobject-Chart configuration parameter
metrics.service.annotationsobject-Chart configuration parameter
metrics.memcachedTLS.enabledboolean-Chart configuration parameter
metrics.memcachedTLS.insecureSkipVerifyboolean-Chart configuration parameter
metrics.memcachedTLS.serverNamestring-Chart configuration parameter
metrics.serviceMonitor.enabledboolean-Chart configuration parameter
metrics.serviceMonitor.namespacestring-Chart configuration parameter
metrics.serviceMonitor.intervalstring-Chart configuration parameter
metrics.serviceMonitor.scrapeTimeoutstring-Chart configuration parameter
metrics.serviceMonitor.labelsobject-Chart configuration parameter
metrics.prometheusRule.enabledboolean-Chart configuration parameter
metrics.prometheusRule.namespacestring-Chart configuration parameter
metrics.prometheusRule.labelsobject-Chart configuration parameter
metrics.prometheusRule.rulesarray-Chart configuration parameter

Network Policy(12)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.ingress.allowSameNamespaceboolean-Chart configuration parameter
networkPolicy.ingress.extraFromarray-Chart configuration parameter
networkPolicy.metrics.enabledboolean-Chart configuration parameter
networkPolicy.metrics.allowSameNamespaceboolean-Chart configuration parameter
networkPolicy.metrics.extraFromarray-Chart configuration parameter
networkPolicy.egress.enabledboolean-Chart configuration parameter
networkPolicy.egress.allowSameNamespaceboolean-Chart configuration parameter
networkPolicy.egress.allowDNSboolean-Chart configuration parameter
networkPolicy.egress.allowHTTPSboolean-Chart configuration parameter
networkPolicy.egress.extraEgressarray-Chart configuration parameter
networkPolicy.egress.extraToarray-Chart configuration parameter

Autoscaling(5)

ParameterTypeDefaultDescription
autoscaling.enabledboolean-Chart configuration parameter
autoscaling.minReplicasinteger-Chart configuration parameter
autoscaling.maxReplicasinteger-Chart configuration parameter
autoscaling.targetCPUUtilizationPercentageinteger-Chart configuration parameter
autoscaling.targetMemoryUtilizationPercentageintegerstring-Chart configuration parameter

Pdb(3)

ParameterTypeDefaultDescription
pdb.enabledboolean-Chart configuration parameter
pdb.minAvailableintegerstring-Chart configuration parameter
pdb.maxUnavailableintegerstring-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter