niceos/yc-redis-cluster repository overview

EN:
Redis Open Source cluster appliance for Yandex Cloud, built on NiceOS.Container: 6 Redis nodes, Russian/English diagnostics, /status, Prometheus /metrics, backup helper, and Yandex Cloud-friendly configuration.

RU:
Redis Open Source cluster appliance для Yandex Cloud на базе НАЙС.ОС Контейнер: 6 Redis-нод, русская/английская диагностика, /status, Prometheus /metrics, backup helper и конфигурация, адаптированная под Yandex Cloud.

⁠Badges

⁠English README

⁠NiceOS Cache Cluster for Yandex Cloud

niceos/yc-redis-cluster is a self-managed Redis Open Source cluster appliance built on NiceOS.Container and designed for Yandex Cloud Container Solution / Marketplace scenarios.

It packages a ready-to-run Redis Cluster topology with clear startup diagnostics, a machine-readable /status endpoint, Prometheus /metrics, a backup helper, and configuration defaults that avoid the most common Redis Cluster mistakes in container/NAT environments.

This image is intended for users who want a transparent, portable, self-managed Redis Open Source appliance rather than a fully managed database service.

⁠What is inside

The default topology is:

1 VM / 1 container
└── 6 Redis server processes
    ├── node-0 :6379  / cluster bus :16379
    ├── node-1 :6380  / cluster bus :16380
    ├── node-2 :6381  / cluster bus :16381
    ├── node-3 :6382  / cluster bus :16382
    ├── node-4 :6383  / cluster bus :16383
    └── node-5 :6384  / cluster bus :16384

Redis Cluster:
  3 masters
  3 replicas
  16384 hash slots

Runtime layout:

/etc/niceos/redis-cluster
/run/niceos/redis-cluster
/var/lib/niceos/redis-cluster
/var/lib/niceos/redis-cluster-backups
/usr/libexec/niceos-yc-redis-cluster

This image does not use legacy migration paths such as /opt/bitnami or /bitnami.

⁠Main features

• Redis Open Source 8.8.0 built for NiceOS.Container.
• Container-first runtime without systemd.
• Runs as the existing niceos:niceos application user.
• 6-node Redis Cluster topology in one container.
• Yandex Cloud-friendly cluster-announce-* handling.
• Russian product-grade startup logs.
• Optional colored logs.
• Optional startup banner.
• /status JSON endpoint.
• /healthz and /readyz endpoints.
• Prometheus-compatible /metrics.
• Yandex Unified Agent / Prometheus scrape profile.
• Backup helper for local backup archives and Object Storage workflows.
• Strict validation of Redis Cluster announce endpoint, password, ports, persistence, memory and expert overrides.
• No tdnf, dnf, yum, systemctl in the final runtime image.
• Support contact: [email protected].

⁠When to use this image

Use this image when you need:

• a self-managed Redis Open Source cache in Yandex Cloud;
• fast deployment through a container product or Docker/Podman;
• transparent Redis configuration;
• direct access to Redis admin commands that are often restricted in managed services;
• a portable image that can run locally, on a VM, or in a private registry;
• a product-grade appliance with built-in health, metrics and backup tooling;
• Russian-language diagnostics and support workflow.

Good use cases:

• application cache;
• session storage;
• test/staging Redis Cluster;
• small production workloads where the VM itself is already managed by the user;
• demo environments;
• migration and compatibility labs;
• teams that require full control over Redis Open Source rather than a managed Valkey service.

⁠When not to use this image

Do not use this single-VM topology when you require:

• managed SLA from a cloud database service;
• automatic multi-zone failover;
• cloud-managed patching;
• cloud-managed automatic backups;
• elastic managed scaling;
• managed host replacement;
• zero-administration database operations.

For those scenarios, a managed database service such as Yandex Managed Service for Valkey may be a better fit.

This image is a self-managed appliance, not a replacement for a managed database SLA.

⁠Quick start with Podman

podman volume create yc-redis-data

podman run -d --name yc-redis-cluster \
  -e YC_REDIS_PASSWORD=ChangeMeRedisPassword1234567890 \
  -e YC_REDIS_CLUSTER_ANNOUNCE_MODE=manual \
  -e YC_REDIS_CLUSTER_ANNOUNCE_IP=127.0.0.1 \
  -e YC_REDIS_CLUSTER_STRICT_EXTERNAL=no \
  -p 6379:6379 -p 6380:6380 -p 6381:6381 -p 6382:6382 -p 6383:6383 -p 6384:6384 \
  -p 16379:16379 -p 16380:16380 -p 16381:16381 -p 16382:16382 -p 16383:16383 -p 16384:16384 \
  -p 9121:9121 \
  -v yc-redis-data:/var/lib/niceos \
  docker.io/niceos/yc-redis-cluster:8.8.0-niceos13-r1

Check logs:

podman logs -f yc-redis-cluster

Check cluster:

podman exec yc-redis-cluster sh -lc '
  export REDISCLI_AUTH=ChangeMeRedisPassword1234567890
  redis-cli --no-auth-warning -h 127.0.0.1 -p 6379 cluster info
  redis-cli --no-auth-warning -h 127.0.0.1 -p 6379 cluster nodes
  redis-cli --no-auth-warning -c -h 127.0.0.1 -p 6379 set niceos:test local-ok
  redis-cli --no-auth-warning -c -h 127.0.0.1 -p 6379 get niceos:test
'

⁠Quick start with Docker

docker volume create yc-redis-data

docker run -d --name yc-redis-cluster \
  -e YC_REDIS_PASSWORD=ChangeMeRedisPassword1234567890 \
  -e YC_REDIS_CLUSTER_ANNOUNCE_MODE=manual \
  -e YC_REDIS_CLUSTER_ANNOUNCE_IP=127.0.0.1 \
  -e YC_REDIS_CLUSTER_STRICT_EXTERNAL=no \
  -p 6379:6379 -p 6380:6380 -p 6381:6381 -p 6382:6382 -p 6383:6383 -p 6384:6384 \
  -p 16379:16379 -p 16380:16380 -p 16381:16381 -p 16382:16382 -p 16383:16383 -p 16384:16384 \
  -p 9121:9121 \
  -v yc-redis-data:/var/lib/niceos \
  docker.io/niceos/yc-redis-cluster:8.8.0-niceos13-r1

⁠Yandex Cloud mode

For a Yandex Cloud VM, use the private IP of the VM as the Redis Cluster announce endpoint, or let the container discover it through Yandex metadata:

-e YC_REDIS_CLUSTER_ANNOUNCE_MODE=metadata-private-ip
-e YC_REDIS_CLUSTER_STRICT_EXTERNAL=yes

The Redis Cluster announce endpoint is important because cluster-mode clients follow MOVED and ASK redirects. If the cluster advertises 127.0.0.1, Docker bridge addresses, or an unreachable address, external clients will fail.

For local testing only, 127.0.0.1 is acceptable:

-e YC_REDIS_CLUSTER_ANNOUNCE_MODE=manual
-e YC_REDIS_CLUSTER_ANNOUNCE_IP=127.0.0.1
-e YC_REDIS_CLUSTER_STRICT_EXTERNAL=no

⁠Status API

The container exposes a JSON status endpoint on port 9121 by default:

curl -s http://127.0.0.1:9121/status

The response includes:

• product metadata;
• NiceOS.Container version;
• Redis version;
• health and readiness;
• cluster state;
• slot coverage;
• masters and replicas;
• node list;
• memory usage;
• persistence state;
• backup state;
• warnings.

Example fields:

{
  "schema": "ru.niceos.yandex.redis_cluster.status.v1",
  "product": {
    "name": "НАЙС.ОС Cache Cluster для Yandex Cloud",
    "runtime": "niceos-yc-redis-cluster",
    "architecture": "cluster-6-single-vm",
    "support": "[email protected]"
  },
  "health": {
    "healthy": true,
    "ready": true,
    "redis_nodes_up": 6
  },
  "cluster": {
    "state": "ok",
    "slots_assigned": 16384,
    "slots_ok": 16384,
    "known_nodes": 6,
    "masters": 3,
    "replicas": 3
  }
}

Health endpoints:

curl -fsS http://127.0.0.1:9121/healthz
curl -fsS http://127.0.0.1:9121/readyz

⁠Observability & monitoring

Prometheus metrics are available at:

curl -s http://127.0.0.1:9121/metrics

Key metrics:

niceos_redis_cluster_up
niceos_redis_cluster_redis_nodes_up
niceos_redis_cluster_slots_assigned
niceos_redis_cluster_slots_ok
niceos_redis_cluster_known_nodes
niceos_redis_cluster_masters
niceos_redis_cluster_replicas
niceos_redis_cluster_connected_nodes
niceos_redis_cluster_used_memory_bytes
niceos_redis_cluster_warnings
niceos_redis_node_up
niceos_redis_node_used_memory_bytes
niceos_redis_node_connected_clients
niceos_redis_node_instantaneous_ops_per_sec
niceos_redis_node_evicted_keys_total
niceos_redis_node_expired_keys_total
niceos_redis_node_keyspace_hits_total
niceos_redis_node_keyspace_misses_total
niceos_redis_backup_local_count
niceos_redis_backup_latest_size_bytes
niceos_redis_backup_latest_age_seconds

A Yandex Unified Agent profile is provided in the product repository:

monitoring/yandex/unified-agent-prometheus.yaml

Prometheus scrape example:

scrape_configs:
  - job_name: niceos-yc-redis-cluster
    metrics_path: /metrics
    static_configs:
      - targets:
          - 127.0.0.1:9121

⁠Backup

Create a backup inside the container:

podman exec yc-redis-cluster \
  /usr/libexec/niceos-yc-redis-cluster/backup.sh create

List local backups inside the container:

podman exec yc-redis-cluster \
  /usr/libexec/niceos-yc-redis-cluster/backup.sh list-local

Copy a backup to the host:

podman cp \
  yc-redis-cluster:/var/lib/niceos/redis-cluster-backups/<backup>.tar.gz \
  ./

The product repository also includes a host-side helper:

CONTAINER_ENGINE=podman \
CONTAINER_NAME=yc-redis-cluster \
OUT_DIR=./backups \
tools/host-backup.sh create-copy

Object Storage upload can be performed from the host using AWS CLI with the Yandex Object Storage endpoint:

aws --endpoint-url https://storage.yandexcloud.net \
  s3 cp ./backups/<backup>.tar.gz \
  s3://<bucket>/redis-cluster/backups/

The image intentionally does not include awscli in the runtime image. Keeping S3 credentials and cloud upload tools outside the Redis container reduces image size and credential exposure.

⁠Configuration

Important environment variables:

⁠Profiles

cache:

• optimized for cache workloads;
• AOF/RDB can be disabled;
• eviction policy usually allkeys-lru.

balanced:

• default profile;
• AOF enabled with everysec;
• RDB enabled;
• good general-purpose behavior.

durable:

• stronger persistence defaults;
• safer but slower.

streams:

• better for Redis Streams use cases;
• persistence enabled.

custom:

• use explicit environment variables and safe overrides.

⁠Production notes

Recommended VM setting for Redis persistence:

sysctl -w vm.overcommit_memory=1

Persistent configuration example:

cat >/etc/sysctl.d/99-niceos-redis.conf <<'EOF'
vm.overcommit_memory = 1
net.core.somaxconn = 1024
EOF

sysctl --system

Security group recommendations:

Allow inbound TCP 6379-6384 only from trusted clients.
Allow inbound TCP 16379-16384 only where Redis Cluster bus traffic is required.
Allow inbound TCP 9121 only from monitoring systems or localhost.
Do not expose Redis ports to the public internet.
Use Yandex Lockbox for the Redis password in Marketplace deployments.

⁠Single-VM topology: honest limitation

This image starts a 6-node Redis Cluster on one VM. This is useful for cluster-mode compatibility, sharding behavior, local replication, diagnostics and self-managed operation.

It is not multi-zone high availability.

If the VM fails, the Redis Cluster becomes unavailable. Replicas inside the same VM cannot protect against VM-level failure.

For real HA, use a future multi-VM topology or a managed service.

⁠Multi-VM HA roadmap

A future multi-VM topology should distribute Redis nodes across several VMs:

VM-1: master shard-0 + replica of another shard
VM-2: master shard-1 + replica of another shard
VM-3: master shard-2 + replica of another shard

or:

VM-1: node-0 master
VM-2: node-1 master
VM-3: node-2 master
VM-4: node-3 replica
VM-5: node-4 replica
VM-6: node-5 replica

Required future variables:

YC_REDIS_TOPOLOGY=cluster-6-multi-vm-3x2
YC_REDIS_CLUSTER_NAME
YC_REDIS_NODE_INDEX
YC_REDIS_NODE_ANNOUNCE_IP
YC_REDIS_CLUSTER_SEED_ENDPOINTS
YC_REDIS_CLUSTER_CREATE_ROLE=bootstrap|join|manual
YC_REDIS_FAILURE_DOMAIN
YC_REDIS_REPLICA_AFFINITY=strict

⁠Comparison with managed Valkey services

This image should not be marketed as a better managed database service. A managed service usually wins on:

• SLA;
• automatic failover;
• multi-zone host placement;
• managed backups;
• managed patching;
• host replacement;
• cloud provider support boundaries;
• elastic scaling.

This image can be better for:

• full Redis Open Source control;
• transparent runtime and configuration;
• portability;
• local and cloud parity;
• Docker/Podman workflows;
• direct filesystem backup access;
• custom status and diagnostics;
• environments where a managed service is too heavy, too expensive, restricted, or not desired.

⁠License

Redis 8 is distributed under the Redis tri-license:

• AGPLv3;
• SSPLv1;
• RSALv2.

Check your intended usage and distribution model before publishing derivative images.

NiceOS packaging, runtime scripts, documentation and product integration files may have their own license metadata in the source repository.

⁠Trademark and affiliation notice

This image is provided by NiceSOFT / NiceOS.

It is not an official Yandex Cloud, Redis, or Valkey product.

Yandex Cloud, Redis and Valkey names may be trademarks of their respective owners. They are used here only to describe compatibility and deployment target.