Solace Cache Helm Chart

This Helm chart deploys Solace Cache instances on Kubernetes with high availability configuration.

Overview

Solace Cache is a distributed cache solution that connects to a Solace message broker. This chart is designed to deploy cache instances as "pets" not "cattle" - meaning these are stateful services that should maintain consistent availability rather than be scaled elastically.

Important: This chart uses a StatefulSet (not a Deployment) to ensure each cache instance has a stable identity and can be configured with a unique cache instance name that matches the configuration on the Solace broker.

Prerequisites

• Kubernetes 1.19+
• Helm 3.0+
• A running Solace broker configured for cache usage
• Container image for Solace Cache (see Building the Container Image below)

Building the Container Image

Before deploying this chart, you need to build a Docker image for Solace Cache:

1. Follow the instructions at: https://github.com/SolaceLabs/PubSubCacheDocker
2. Download the required Solace Cache and C API packages
3. Build the Docker image
4. Push the image to your container registry

Update values.yaml with your image repository and tag:

image:
  repository: your-registry/solace-cache
  tag: "1.0.0"

Installation

Basic Installation

Important: You must configure cache instance names that match what you've configured on your Solace broker.

helm install my-cache ./solace-cache \
  --set solaceCache.instanceNames[0]="cache-inst-1" \
  --set solaceCache.instanceNames[1]="cache-inst-2" \
  --set solaceCache.distributedCacheName="my-distributed-cache" \
  --set solaceCache.broker.host="tcp://my-broker.example.com:55555" \
  --set solaceCache.broker.vpn="my-vpn" \
  --set solaceCache.broker.usernames[0]="cache-user" \
  --set solaceCache.broker.passwords[0]="cache-password"

usernames and passwords are arrays — one entry per replica. If you supply a single entry it is reused for every instance; otherwise provide one per pod ordinal (e.g. usernames[0], usernames[1]).

Installation with Existing Secret

For production, use Kubernetes Secrets for credentials. The secret must contain one key pair per pod ordinal: username-0/password-0, username-1/password-1, etc. (see example-external-secret.yaml):

# Create a secret with per-instance credentials (2 replicas shown)
kubectl create secret generic solace-cache-creds \
  --from-literal=username-0=cache-user \
  --from-literal=password-0=cache-password \
  --from-literal=username-1=cache-user \
  --from-literal=password-1=cache-password

# Install using the secret
helm install my-cache ./solace-cache \
  --set solaceCache.broker.host="tcp://my-broker.example.com:55555" \
  --set solaceCache.broker.vpn="my-vpn" \
  --set solaceCache.broker.existingSecret="solace-cache-creds"

Installation with SSL/TLS

# Create a secret with the broker's CA certificate
kubectl create secret generic solace-broker-ca \
  --from-file=ca.crt=/path/to/ca-certificate.pem

# Install with SSL enabled
helm install my-cache ./solace-cache \
  --set solaceCache.broker.host="tcps://my-broker.example.com:55443" \
  --set solaceCache.broker.vpn="my-vpn" \
  --set solaceCache.broker.existingSecret="solace-cache-creds" \
  --set solaceCache.broker.ssl.enabled=true \
  --set solaceCache.broker.ssl.trustStoreSecret="solace-broker-ca"

Configuration

Key Configuration Parameters

Parameter	Description	Default
replicaCount	Number of cache instances	2
updateStrategy.type	OnDelete (manual restart to apply changes) or RollingUpdate (auto)	OnDelete
image.repository	Container image repository	your-registry/solace-cache
image.tag	Container image tag (empty = chart appVersion)	""
solaceCache.instanceNames	Array of cache instance names (must match broker config)	["cache-instance-0", "cache-instance-1"]
solaceCache.distributedCacheName	Distributed cache name on broker	default-cache
solaceCache.broker.host	Solace broker connection URL	tcp://solace-broker.default.svc.cluster.local:55555
solaceCache.broker.vpn	Message VPN name	default
solaceCache.broker.usernames	Client usernames, one per replica (single entry reused for all)	["cache"]
solaceCache.broker.passwords	Client passwords, one per replica (use existingSecret in production)	["cache"]
solaceCache.broker.existingSecret	Use existing secret for credentials (keys username-N/password-N)	""
solaceCache.broker.ssl.enabled	Enable SSL/TLS connection	false
solaceCache.broker.ssl.trustStoreSecret	Secret containing CA certificate	""
solaceCache.settings.sdkLogLevel	API/SDK log level	NOTICE
solaceCache.settings.debugCacheLogLevel	Use DEBUG cache logging (false = INFO, required by readiness wrapper)	false
podDisruptionBudget.enabled	Enable PodDisruptionBudget	true
podDisruptionBudget.minAvailable	Minimum available pods	1
resources.requests.memory	Memory request	512Mi
resources.requests.cpu	CPU request	500m
resources.limits.memory	Memory limit	2Gi
resources.limits.cpu	CPU limit	2000m

High Availability Features

This chart includes several HA features:

1. StatefulSet: Uses StatefulSet for stable pod identities
2. Dual Replicas: Runs 2 cache instances by default
3. Unique Instance Names: Each pod gets a unique cache instance name that must match the broker configuration
4. Pod Disruption Budget: Ensures at least 1 instance is always available during disruptions
5. Pod Anti-Affinity: Spreads instances across different nodes when possible
6. Resource Limits: Sets appropriate resource requests and limits

Cache Instance Names

Critical Configuration: Each cache instance must have a unique name that matches what you've configured on the Solace broker:

1. Configure cache instances on your Solace broker (e.g., "prod-cache-1", "prod-cache-2")
2. Set the same names in your Helm values:

solaceCache:
  instanceNames:
    - "prod-cache-1"  # Matches broker config
    - "prod-cache-2"  # Matches broker config
  distributedCacheName: "prod-distributed-cache"

The chart uses an init container to generate a unique config file for each pod based on its ordinal index.

Custom Configuration

If you need to provide a custom config.txt file instead of the generated one:

solaceCache:
  customConfig: |
    SESSION_USERNAME myuser
    SESSION_PASSWORD mypass
    SESSION_HOST tcp://broker:55555
    SESSION_VPN_NAME myvpn
    CACHE_INSTANCE_NAME my-cache-inst
    CACHE_SDK_LOG_LEVEL NOTICE
    CACHE_LOG_LEVEL INFO
    CACHE_DISABLE_SYSLOG 1
    # Add your custom configuration here

Note: The init container always runs placeholder substitution over the generated config. For per-pod values in a customConfig, include the placeholders (__CACHE_INSTANCE_NAME__, __SESSION_USERNAME__, __SESSION_PASSWORD__, __SESSION_APPLICATION_DESCRIPTION__) where you want the per-instance name and credentials injected — without them every replica shares the same hard-coded values. Keep INFO-level CACHE_LOG_LEVEL if you rely on the readiness wrapper, which watches the logs for state changes.

Upgrading & Applying Configuration Changes

IMPORTANT — restarts are manual by default. This chart ships with updateStrategy.type: OnDelete, because Solace Cache instances are stateful "pets" whose restarts you want to control. A helm upgrade stages changes (config, image, resources) but does not restart pods. The new configuration only takes effect when you restart each instance yourself.

# 1. Stage the change (updates the ConfigMap/StatefulSet, pods keep running as-is)
helm upgrade my-cache ./solace-cache -f custom-values.yaml

# 2. Apply it when ready, one instance at a time to preserve HA.
#    Restart the highest ordinal first; confirm it reconnects and warms before the next.
kubectl delete pod my-cache-solace-cache-1
kubectl delete pod my-cache-solace-cache-0

# Check which pods are still on the old revision:
kubectl rollout status statefulset/my-cache-solace-cache

To have helm upgrade restart pods automatically instead (e.g. in dev/test), set updateStrategy.type: RollingUpdate:

helm upgrade my-cache ./solace-cache -f custom-values.yaml \
  --set updateStrategy.type=RollingUpdate

Note: because each pod generates its config once at startup (via the init container), a changed ConfigMap has no effect on a running pod until that pod restarts — under either strategy. OnDelete simply puts the timing of that restart in your hands.

Uninstalling

helm uninstall my-cache

Monitoring

To check the status of your cache instances:

# View pods
kubectl get pods -l app.kubernetes.io/name=solace-cache

# Check logs
kubectl logs -l app.kubernetes.io/name=solace-cache -f

# Describe a specific pod
kubectl describe pod <pod-name>

Troubleshooting

Cache instances not connecting to broker

1. Check the logs: kubectl logs <pod-name>
2. Verify broker connectivity: kubectl exec <pod-name> -- ping <broker-host>
3. Verify credentials and VPN configuration
4. Check if the broker has cache configured

Pods not starting

1. Verify the image is available: kubectl describe pod <pod-name>
2. Check resource constraints: kubectl describe node
3. Review events: kubectl get events --sort-by='.lastTimestamp'

Important Notes

• These are "pets" not "cattle": Do not use autoscaling. Keep replica count fixed at 2 for production.
• StatefulSet: This chart uses StatefulSet for stable identities and unique per-pod configuration
• Instance names must match broker config: The cache instance names in Helm values must exactly match what you've configured on the Solace broker
• Health checks: The default health checks use pgrep. Adjust based on your actual health check mechanism.
• Resource sizing: Adjust memory and CPU based on your cache size and throughput requirements.
• Number of replicas: If you change replicaCount, ensure you provide the correct number of instance names in instanceNames array.

Next Steps

After deploying the cache instances:

1. Verify they are running and connected to the broker
2. Add the cache instances to your Distributed Cache on the Solace message router
3. Refer to Solace Cache documentation for configuration and management

Backup & Restore

Operator tooling for backing up and restoring cache contents lives in the scripts/ directory (it is excluded from the packaged chart). These are installable as kubectl plugins:

# Back up a running instance's cached messages to a local file
scripts/kubectl-backup-cache <release>-0 -n <namespace> --semp-url http://broker:8080

# Restore a backup file into a running instance
scripts/kubectl-restore-cache <release>-0 ./<instance>-<timestamp>.bkup -n <namespace>

Run either with -h for the full option list. Requirements: GNU grep (the scripts use grep -P) and network access to the broker's SEMP endpoint.

License

This Helm chart is provided as-is and is licensed under the Apache 2.0 License. See the full license text in the LICENSE file. Refer to Solace licensing for the Solace Cache and Solace C API software.