Deploy Valkey / Redis

Use the valkey package to deploy a Redis-compatible data store with a StatefulSet, Services, health checks, authentication, and persistent storage.

This guide uses one Valkey node for a small cluster. The target cluster must provide a default StorageClass, or you must supply one in the instance configuration.

Add the Valkey instance

Add the package in the namespace where applications will resolve it:

how-to/package-stacks/valkey-cluster.nix (L16–L30)

      instances.cache.valkey = {
        package = packages.valkey;
        config = {
          replicaCount = 1;
          sentinel.enabled = false;

          persistence = {
            enabled = true;
            size = "2Gi";
          };

          # Use SOPS or an existing Secret outside local development.
          auth.password = "development-only-password";
        };
      };

View source on GitHub ↗

Disabling Sentinel and using one replica gives this example a single Valkey process. Keep Sentinel enabled and use at least three replicas when the cluster spans enough nodes to make automatic failover useful.

The package creates a 2 GiB claim for the node. Set persistence.storageClass when the cluster’s default class is not the one you want.

The password in the example is only for local development. For a deployed environment, set auth.existingSecret to a Secret managed outside Kix, or set auth.secretSource to a SOPS-encrypted file. The password key defaults to valkey-password and can be changed with auth.existingSecretPasswordKey.

Check the generated resources

Evaluate the cluster:

Run in kix-examples/

❱ kix check how-to-package-valkey
 TOOL         RESULT  DETAILS                                                       
 eval         pass    16 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 scorecard    pass    0 errors, 0 warnings, 0 info

Inspect the StatefulSet and client Service:

Run in kix-examples/ Output excerpt

❱ kix build how-to-package-valkey --output json
[
  {
    "apiVersion": "apps/v1",
    "kind": "StatefulSet",
    "metadata": {
      "name": "valkey-primary",
      "namespace": "cache"
    },
    "spec": {
      "replicas": 1,
      "serviceName": "valkey-headless",
      "containers": [
        {
          "name": "valkey",
          "image": "docker.io/bitnamilegacy/valkey:8.1.3-debian-12-r3",
          "ports": [
            {
              "containerPort": 6379,
              "name": "redis",
              "protocol": "TCP"
            }
          ]
        }
      ],
      "volumeClaimTemplates": [
        {
          "metadata": {
            "name": "valkey-data"
          },
          "spec": {
            "accessModes": [
              "ReadWriteOnce"
            ],
            "resources": {
              "requests": {
                "storage": "2Gi"
              }
            }
          }
        }
      ]
    }
  },
  {
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {
      "name": "valkey",
      "namespace": "cache"
    },
    "spec": {
      "ports": [
        {
          "name": "tcp-redis",
          "port": 6379,
          "protocol": "TCP",
          "targetPort": 6379
        }
      ]
    }
  }
]

The StatefulSet requests the configured 2 GiB volume and uses the headless Service for stable pod identity. Applications connect to the valkey Service on port 6379.

Deploy and connect

Deploy the cluster and check the instance:

Run in kix-examples/

❱ kix deploy how-to-package-valkey

❱ kix status how-to-package-valkey

To test it locally, forward the service port:

Run in kix-examples/

❱ kix pf how-to-package-valkey valkey 6379:6379

While the forward is running, use a Redis-compatible client from another terminal:

❱ REDISCLI_AUTH=development-only-password redis-cli ping

A successful connection returns PONG. Stop the port-forward with Ctrl-C.

If the pod remains pending, inspect its PVC and confirm that the requested StorageClass exists and can provision ReadWriteOnce volumes in the target cluster.