agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/dragonfly/SKILL.md

dragonfly

Skill4 starsChanged 5 months agoMITView on GitHub

Use when working with DragonflyDB operator on Kubernetes — creating or troubleshooting Dragonfly resources, configuring replication, snapshots, TLS, authentication, or affinity/scheduling for Dragonfly instances.

The file

Files
SKILL.md

DragonflyDB Operator

Overview

Dragonfly operator manages Dragonfly (Redis-compatible) in-memory data store instances on Kubernetes. API: dragonflydb.io/v1alpha1. Single CRD: Dragonfly (plural: dragonflies). Deployed via Helm chart oci://ghcr.io/dragonflydb/dragonfly-operator/helm/dragonfly-operator. Latest operator: v1.5.0 (Mar 2026). Deployed chart: v1.5.0.

CRD Fields

FieldTypeSinceDescription
replicasint—Total instances (1 = standalone primary, 2 = 1 primary + 1 replica)
imagestring—Dragonfly image (default: docker.dragonflydb.io/dragonflydb/dragonfly:v1.21.2)
args[]string—Dragonfly server args (e.g. --maxmemory=2gb)
resourcesResourceRequirements—Container CPU/memory
affinityAffinity—Pod affinity (nodeAffinity, podAntiAffinity, etc.)
nodeSelectormapv1.1.1Node selector for pod scheduling
tolerations[]Toleration—Pod tolerations
topologySpreadConstraints[]TopologySpreadConstraintv1.1.1Spread pods across topology domains
annotationsobject—Annotations on Dragonfly pods
labelsobject—Labels on Dragonfly pods
env[]EnvVar—Environment variables
authentication.passwordFromSecretSecretKeySelector—Password from Secret key
authentication.clientCaCertSecretSecretReference—Client CA certificate Secret
tlsSecretRefSecretReference—TLS cert Secret for server TLS
snapshot.cronstring—Cron schedule for snapshots (e.g. "\*/5 * * * *")
snapshot.persistentVolumeClaimSpecPVC Spec—PVC for snapshot storage
aclFromSecretSecretKeySelectorv1.1.1ACL file from Secret
serviceAccountNamestring—Pod service account
serviceSpec.typestring—Service type (ClusterIP, LoadBalancer, etc.)
serviceSpec.namestringv1.1.3Custom service name
serviceSpec.annotationsobject—Service annotations
priorityClassNamestringv1.1.1Pod priority class
skipFSGroupboolv1.1.2Skip FSGroup assignment (OpenShift)
memcachedPortintv1.1.2Memcached port (alternative to --memcached_port arg)
additionalContainers[]Container—Sidecar containers
additionalVolumes[]Volume—Extra volumes

Dragonfly Spec Patterns

apiVersion: dragonflydb.io/v1alpha1
kind: Dragonfly
metadata:
  name: my-cache
spec:
  replicas: 1                    # 1 = standalone primary
  args:
    - --maxmemory=2gb
    - --logtostderr
    - --cluster_mode=emulated    # Enable cluster-compatible mode
    - --lock_on_hashtags         # Hashtag-based locking
    - --default_lua_flags=allow-undeclared-keys

  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: "1"
      memory: 2Gi

  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: kubernetes.io/hostname
                operator: In
                values:
                  - worker-01

  authentication:
    passwordFromSecret:
      name: dragonfly-password
      key: password

  snapshot:
    cron: "*/5 * * * *"
    persistentVolumeClaimSpec:
      accessModes:
        - ReadWriteOnce
      storageClassName: ceph-block
      resources:
        requests:
          storage: 2Gi

  serviceSpec:
    type: ClusterIP
    annotations:
      external-dns.alpha.kubernetes.io/hostname: dragonfly.example.com

Replication Model

  • replicas=1 — standalone primary
  • replicas=2 — 1 primary + 1 replica
  • replicas=3 — 1 primary + 2 replicas
  • Always exactly 1 primary regardless of replica count
  • Operator manages automatic failover if primary fails
  • Service <name>.<ns>.svc.cluster.local always points to current primary

Authentication

MethodConfigDescription
Passwordauthentication.passwordFromSecretBasic password auth (maps to --requirepass)
Client CAauthentication.clientCaCertSecretTLS client cert verification
ACL fileaclFromSecretACL rules file from Secret (v1.1.1+)

Password can also be set via args: ["--requirepass=<pw>"] or env: [{name: DFLY_requirepass, value: "<pw>"}].

TLS

spec:
  tlsSecretRef:
    name: dragonfly-tls    # Secret must have tls.crt, tls.key

Secret must exist in same namespace. Optionally combine with authentication.clientCaCertSecret for mutual TLS.

Snapshots

Snapshots store Dragonfly data to PVC for persistence across restarts:

spec:
  snapshot:
    cron: "*/5 * * * *"
    persistentVolumeClaimSpec:
      storageClassName: ceph-block
      accessModes: [ReadWriteOnce]
      resources:
        requests:
          storage: 2Gi
  • cron is optional — omit for on-demand only
  • Snapshots not auto-pruned — manage disk or use static --dbfilename to overwrite
  • PVC spec follows standard Kubernetes PersistentVolumeClaimSpec

Exposing Dragonfly as Cache

Applications connect via the service at <name>.<ns>.svc.cluster.local:6379. In apps using Dragonfly as Redis-compatible cache (valkey/Redis clients):

# In the app's ConfigMap or env
REDIS_URL: redis://:${REDIS_PASSWORD}@my-cache.namespace:6379
REDIS_PASSWORD: # from Dragonfly auth secret

For cluster-mode emulated (--cluster_mode=emulated), Redis cluster clients (e.g. ioredis cluster mode) can connect as if it's a Redis Cluster — but there's only one actual Dragonfly instance behind the service.

Monitoring

Dragonfly exposes metrics on the admin port. Use a PodMonitor to scrape:

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: dragonfly-monitor
spec:
  selector:
    matchLabels:
      app: my-cache               # Must match Dragonfly resource name
  podMetricsEndpoints:
    - port: admin

The operator creates pods with label app: <dragonfly-name> by default.

Common Mistakes

  • replicas confusion — replicas=2 means 1 primary + 1 replica, NOT 2 primaries
  • No snapshot cron — without cron + PVC, restarts lose all data; always configure for stateful use
  • cluster_mode=emulated without lock_on_hashtags — emulated cluster needs hashtag locking for multi-key ops
  • Password collision — don't set password via both authentication.passwordFromSecret AND --requirepass arg; use the CRD field
  • Same storageClass for all — immich with ceph-block fine; if latency-sensitive, use local SSD via nodeSelector + local storage
  • No resource limits — Dragonfly can OOM under load; always set resources.limits.memory
  • Helm chart OCI URL — use oci://ghcr.io/dragonflydb/dragonfly-operator/helm, chart name dragonfly-operator, version v1.5.0

Version History

OperatorHelm ChartDateNotes
v1.5.0v1.5.0Mar 2026Latest (deployed)
v1.4.0v1.4.0Jan 2026
v1.3.1v1.3.1Nov 2025

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.