Memcached Operator

Appearance

Installation ​

This guide covers installing the Memcached Operator on a Kubernetes cluster, verifying the deployment, and creating your first Memcached instance.

Prerequisites ​

Cluster Requirements ​

  • Kubernetes v1.28 or later
  • kubectl configured to communicate with your cluster
  • cert-manager installed (required for webhook TLS certificate provisioning)
  • Prometheus Operator CRDs installed (optional, required only if you plan to use ServiceMonitor resources for monitoring)

Install cert-manager ​

If cert-manager is not yet installed on your cluster, install it before deploying the operator:

bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
kubectl wait --for=condition=Available deployment --all -n cert-manager --timeout=120s

Install Prometheus Operator CRDs (optional) ​

If you plan to use ServiceMonitor resources for Prometheus-based monitoring, install the Prometheus Operator CRDs:

bash
kubectl apply -f https://github.com/prometheus-operator/prometheus-operator/releases/latest/download/stripped-down-crds.yaml

Verify prerequisites ​

bash
# Check Kubernetes version
kubectl version

# Verify cert-manager is running
kubectl get pods -n cert-manager

# Check if Prometheus Operator CRDs are available (optional)
kubectl get crd servicemonitors.monitoring.coreos.com

Local Development Requirements ​

If you plan to build the operator from source or run it locally, you also need:

  • Go 1.25 or later
  • Docker or Podman (for building container images)
  • kind or minikube (for local Kubernetes clusters)
  • Operator SDK v1.42 or later (optional, for scaffolding changes)

Install CRDs ​

Before deploying the operator, install the Memcached Custom Resource Definition into your cluster. Choose one of the following methods:

Apply the CRD manifest directly from a GitHub Release:

bash
kubectl apply -f https://github.com/c5c3/memcached-operator/releases/download/v0.2.0/memcached.c5c3.io_memcacheds.yaml

Replace v0.2.0 with the desired version. Available releases are listed at github.com/c5c3/memcached-operator/releases.

Option B: From source ​

If you have the repository cloned, use the Makefile target:

bash
make install

Verify CRD installation ​

bash
kubectl get crd memcacheds.memcached.c5c3.io

Expected output:

text
NAME                            CREATED AT
memcacheds.memcached.c5c3.io    2025-01-15T10:00:00Z

Deploy the Operator ​

Install the operator using Helm from the GHCR OCI registry:

bash
helm install memcached-operator oci://ghcr.io/c5c3/charts/memcached-operator \
  --version 0.2.0 \
  --namespace memcached-operator-system \
  --create-namespace

Replace 0.2.0 with the desired chart version. Override default values with --set or a values file:

bash
helm install memcached-operator oci://ghcr.io/c5c3/charts/memcached-operator \
  --version 0.2.0 \
  --namespace memcached-operator-system \
  --create-namespace \
  --set serviceMonitor.enabled=true

See the chart README for the full list of configurable values.

Option B: From a GitHub Release ​

Each release includes a ready-to-use install.yaml that contains all resources (CRDs, RBAC, Deployment, webhooks, cert-manager resources) in a single file:

bash
kubectl apply -f https://github.com/c5c3/memcached-operator/releases/download/v0.2.0/install.yaml

Replace v0.2.0 with the desired version. Available releases are listed at github.com/c5c3/memcached-operator/releases.

Option C: From source ​

If you have the repository cloned, you can deploy using the Makefile:

bash
make deploy IMG=ghcr.io/c5c3/memcached-operator:v0.2.0

Replace v0.2.0 with the desired version tag. This builds the full manifest from config/default/ using Kustomize and applies it to the cluster.

All options install the following resources under the memcached-operator-system namespace with the memcached-operator- name prefix:

  • CRD definitions
  • RBAC resources: ClusterRole, ClusterRoleBinding, ServiceAccount
  • Operator Deployment with the controller manager
  • Webhook configurations (MutatingWebhookConfiguration, ValidatingWebhookConfiguration)
  • cert-manager Certificate and Issuer for webhook TLS

Verify the Installation ​

After deploying, verify that all components are running correctly.

Check the operator pod ​

bash
kubectl get pods -n memcached-operator-system

Expected output:

text
NAME                                                     READY   STATUS    RESTARTS   AGE
memcached-operator-controller-manager-5b8f4c7d9f-x2k4l   1/1     Running   0          30s

Wait until the pod status shows Running and READY is 1/1.

Check the CRD ​

bash
kubectl get crd memcacheds.memcached.c5c3.io

Check webhook configurations ​

bash
kubectl get mutatingwebhookconfigurations,validatingwebhookconfigurations | grep memcached

Expected output:

text
mutatingwebhookconfiguration.admissionregistration.k8s.io/memcached-operator-mutating-webhook-configuration      1          30s
validatingwebhookconfiguration.admissionregistration.k8s.io/memcached-operator-validating-webhook-configuration   1          30s

Check operator logs ​

bash
kubectl logs -n memcached-operator-system deployment/memcached-operator-controller-manager

Look for successful startup messages and confirm there are no error-level log entries. The operator exposes health probes on port 8081 (/healthz and /readyz) and serves metrics on port 8443 (/metrics).

Create Your First Memcached Instance ​

Once the operator is running, create a Memcached instance by applying a custom resource.

Minimal example ​

Create a file named memcached.yaml:

yaml
apiVersion: memcached.c5c3.io/v1alpha1
kind: Memcached
metadata:
  name: my-cache
  namespace: default
spec:
  replicas: 3
  image: "memcached:1.6"
  memcached:
    maxMemoryMB: 64

Apply it:

bash
kubectl apply -f memcached.yaml

Verify the instance ​

Check the Memcached custom resource:

bash
kubectl get memcached my-cache

Check the managed Deployment and pods:

bash
kubectl get deployment my-cache
kubectl get pods -l app.kubernetes.io/instance=my-cache

Check the headless Service:

bash
kubectl get service my-cache

Inspect the full status, including conditions and metrics:

bash
kubectl get memcached my-cache -o yaml

A healthy instance shows Available: True and Degraded: False in its status conditions.

Test the connection ​

Run a temporary pod to verify the Memcached instance is reachable:

bash
kubectl run memcached-test --image=busybox:1.36 --rm -it --restart=Never -- \
  sh -c 'echo "stats" | nc my-cache 11211'

You should see Memcached statistics output including STAT pid, STAT uptime, etc. This confirms the cache is running and accepting connections.

To set and retrieve a value:

bash
kubectl run memcached-test --image=busybox:1.36 --rm -it --restart=Never -- \
  sh -c 'printf "set hello 0 60 5\r\nworld\r\nget hello\r\nquit\r\n" | nc my-cache 11211'

Expected output:

text
STORED
VALUE hello 0 5
world
END

Delete the instance ​

To remove the Memcached instance and all its managed resources (Deployment, Service, PDB, etc.):

bash
kubectl delete memcached my-cache

The operator automatically cleans up all owned resources via Kubernetes owner references.

More examples ​

For advanced configurations including high availability, monitoring, TLS, SASL authentication, and NetworkPolicies, see the Examples guide.

Local Development Setup ​

For developing and testing the operator locally without deploying it to a cluster:

1. Install CRDs ​

bash
make install

2. Run the operator locally ​

The operator runs on your machine and connects to the cluster configured in your current kubeconfig context:

bash
make run

This compiles and runs the operator binary directly. Webhooks are not active in this mode because they require TLS certificates provisioned by cert-manager inside the cluster.

3. Apply a sample CR ​

In a separate terminal:

bash
kubectl apply -f config/samples/memcached_v1alpha1_memcached.yaml

4. Observe reconciliation ​

Watch the operator logs in the first terminal and verify that managed resources are created:

bash
kubectl get deployment,service,pdb -l app.kubernetes.io/managed-by=memcached-operator

Uninstallation ​

Remove all operator resources ​

If you installed via Helm:

bash
helm uninstall memcached-operator --namespace memcached-operator-system

If you installed via the release manifest:

bash
kubectl delete -f https://github.com/c5c3/memcached-operator/releases/download/v0.2.0/install.yaml

If you installed from source:

bash
make undeploy

All commands remove operator resources including the memcached-operator-system namespace.

Warning: Removing the CRDs also deletes all Memcached custom resources and their managed workloads (Deployments, Services, PDBs, etc.) across all namespaces. Back up your Memcached CRs before proceeding if you need to preserve their definitions.

Remove only CRDs ​

To remove just the CRDs without removing the operator:

bash
make uninstall