Deploy NCache Open Source with Kubernetes
NCache Open Source is deployed on Kubernetes using its own YAML manifests to create the server pods and networking services. A StatefulSet maintains the server deployment, while Kubernetes Services provide access to the NCache servers. Helm charts and NCache Management Center are not available for Open Source.
This page describes how to prepare your Kubernetes environment, deploy two NCache servers, configure a clustered cache, and apply configuration changes. Cache configuration is managed by editing the NCache configuration file and restarting the NCache service for changes to take effect. The Enterprise Helm values and YAML automation described on other deployment pages do not apply to these files.
Prerequisites
Before you begin, make sure that:
- You have a running Kubernetes cluster at version
1.25or later, with Linux worker nodes and sufficient resources for two NCache servers. kubectlis installed and configured to access the intended cluster.- You have permission to create StatefulSets and Services in the deployment namespace.
- You have access to the NCache Open Source container image and any credentials required by its registry.
- Your application can reach the cache server endpoints and the ports required by the cache. The verification example on this page runs inside the Kubernetes cluster.
- You have a valid Open Source registration key for the server containers.
Prepare Your Kubernetes Environment
Prepare cluster access and networking for your platform before applying the deployment files. The Open Source Kubernetes folder includes cluster-creation scripts for on-premises Kubernetes, AKS, EKS, and GKE. Follow the instructions for your platform if you need to provision a cluster.
Use the cluster-creation and connection links below to prepare your platform, then follow the YAML deployment procedure on this page.
On-Premises Kubernetes
- If you need to create a cluster, follow Create an On-Premises Cluster.
Configure
kubectlusing the cluster access configuration supplied by your administrator.To create the cluster using the Open Source automation, download create-onprem-cluster.sh from the Open Source Kubernetes folder. On Ubuntu, copy create-onprem-cluster.sh to the control-plane machine and each worker. Review
POD_CIDRfor your network, runsudo bash create-onprem-cluster.sh control-planeon the control plane, then runsudo bash create-onprem-cluster.sh workeron each worker and execute the completesudo kubeadm join ...command printed by the control plane. Continue with the context and node checks under Deployment Process after joining every worker.
Azure Kubernetes Service (AKS)
- If you need to create a cluster, follow Create an AKS Cluster.
Follow Connect kubectl to AKS to configure access to the cluster.
To create the cluster using the Open Source automation, download create-aks-cluster.sh from the Open Source Kubernetes folder. Set
CLUSTER_NAME,REGION,RESOURCE_GROUP,NODE_COUNT, andVM_SIZEat the top of the script. Provide at least two worker nodes and run the script from a Bash terminal with Azure CLI andkubectlinstalled.
bash create-aks-cluster.sh
The script configures cluster access. Continue with the context and node checks under Deployment Process, then follow Step 1 to prepare the Open Source deployment files.
Amazon Elastic Kubernetes Service (EKS)
- If you need to create a cluster, follow Create an EKS Cluster.
Follow Connect kubectl to EKS to configure access to the cluster.
To create the cluster using the Open Source automation, download create-eks-cluster.sh from the Open Source Kubernetes folder. Configure your AWS CLI credentials and set
CLUSTER_NAME,REGION,SUBNET_IDS,IAM_ROLE,NODE_COUNT, andNODE_TYPEat the top of the script. Supply two public subnet IDs in different Availability Zones, separated by a space, and an existing IAM role with the permissions described in the Open Source repository README. Use at least two worker nodes and run the script from a Bash terminal with AWS CLI andkubectlinstalled.
bash create-eks-cluster.sh
The script configures cluster access. Continue with the context and node checks under Deployment Process, then follow Step 1 to prepare the Open Source deployment files.
Google Kubernetes Engine (GKE)
- If you need to create a cluster, follow Create a GKE Cluster.
Follow Connect kubectl to GKE to configure access to the cluster.
To create the cluster using the Open Source automation, download create-gke-cluster.sh from the Open Source Kubernetes folder. Set
CLUSTER_NAME,ZONE,PROJECT_ID,NODE_COUNT, andMACHINE_TYPEat the top of the script. Provide at least two worker nodes and run the script from a Bash terminal with Google Cloud CLI andkubectlinstalled.
bash create-gke-cluster.sh
The script configures cluster access. Continue with the context and node checks under Deployment Process, then follow Step 1 to prepare the Open Source deployment files.
OpenShift
- If you need to create a cluster, follow Create an OpenShift Cluster.
- Configure
kubectlusing the cluster access configuration supplied by your OpenShift administrator. Confirm that the Open Source container image can run under the cluster's security policies.
Ensure that network policies and platform network rules allow application pods to reach both NCache server pods, and allow the servers to communicate on the configured cluster port.
Deployment Process
After preparing your environment, confirm that kubectl targets the intended cluster:
kubectl config current-context
kubectl get nodes
Once you have confirmed access to the intended cluster, follow the steps below to deploy NCache Open Source and configure the cache.
Step 1: Prepare the Deployment Files
Obtain the Open Source deployment files from the Open Source Kubernetes folder. Use the Open Source files for this procedure; the Enterprise package has different resources and gateway settings. The deployment uses the following YAML files:
- ncache.yaml defines the StatefulSet and NCache server containers, with two server pods configured by default.
- discoveryservice.yaml defines the headless Service used to identify the server pods.
The examples below use NCache Open Source 5.3.603 and its matching client package, so set the image in ncache.yaml to alachisoft/ncache:5.3.603-oss. If the registry requires authentication, create an image pull Secret in the deployment namespace and reference it through imagePullSecrets. Remove the imagePullSecrets entry if authentication is not required.
Set the StatefulSet's serviceName in ncache.yaml to match the headless Service name in the supplied discoveryservice.yaml:
spec:
serviceName: cacheserver
Retain the remaining StatefulSet settings, including its selectors, pod labels, and container ports.
Step 2: Deploy the NCache Servers
Create a namespace for the deployment:
kubectl create namespace ncache
If the namespace already exists, continue with the deployment commands.
If you need the StatefulSet and discovery Service names to match as described in Step 1, apply the edited files using the manual commands below. To deploy the published manifests as supplied, select the deployment namespace and run the Open Source deployment script from the ncache-oss directory:
kubectl config set-context --current --namespace=ncache
bash deploy-ncache.sh
The script applies both manifests directly from GitHub. After it finishes, skip the two manual apply commands and continue with the server pod checks below. For a deployment that uses your local changes from Step 1, run these commands instead:
kubectl apply --namespace ncache -f discoveryservice.yaml
kubectl apply --namespace ncache -f ncache.yaml
Check the server pods and their assigned IP addresses:
kubectl get pods --namespace ncache -l app=ncache -o wide
The default deployment creates ncache-0 and ncache-1. If a container fails to start, inspect its events and logs before configuring the cache:
kubectl describe pod ncache-0 --namespace ncache
kubectl logs ncache-0 --namespace ncache
Once both pods are ready, register each server, then follow Steps 3 through 5 to configure the cache on every server, verify cluster membership, and test a write and read from an application inside the cluster. These steps apply to both installation methods.
Register both server containers with your Open Source key before starting a cache. Replace the key placeholder in each command:
kubectl exec --namespace ncache ncache-0 -- /opt/ncache/bin/tools/register-ncacheopensource -Key "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
kubectl exec --namespace ncache ncache-1 -- /opt/ncache/bin/tools/register-ncacheopensource -Key "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Step 3: Configure the Cache
To configure a Replicated cache named defaultCache on both servers, first copy each server's config.ncconf to your working directory and retain an unchanged backup of each file:
kubectl cp ncache/ncache-0:/opt/ncache/config/config.ncconf ./ncache-0-config.ncconf
kubectl cp ncache/ncache-1:/opt/ncache/config/config.ncconf ./ncache-1-config.ncconf
Prepare a complete updated configuration for each server from its own saved file. Update only the <cache-config> entry for defaultCache as shown below, retaining the XML declaration, enclosing <configuration> element, and all other cache definitions and server-specific settings, including any defaultPubSub and defaultLocalCache entries. If defaultCache is not already defined, add this entry inside <configuration> without duplicating the cache name. If it already has the required settings, add only the missing <server-node> line inside its <cache-deployment><servers> section. For example, add the 10.244.0.11 entry below when 10.244.0.10 is already listed, then apply the updated <cache-config> block to every server, including the new one.
<cache-config cache-name="defaultCache" alias="" config-id="44fb997a-f6a7-433b-9439-7ef9de9f47c7" config-version="0" store-type="distributed-cache">
<cache-settings inproc="False" data-format="Serialized" serialization="Json">
<logging enable-logs="True" trace-errors="True" trace-debug="False" log-path=""/>
<performance-counters enable-counters="True" snmp-port="0"/>
<cleanup interval="15sec"/>
<storage type="heap" cache-size="1024mb"/>
<eviction-policy enabled-eviction="True" default-priority="normal" policy="lru" eviction-ratio="5%"/>
<cache-topology topology="replicated">
<cluster-settings operation-timeout="60sec" stats-repl-interval="300sec">
<cluster-connection-settings port-range="1" connection-retries="1" connection-retry-interval="2secs" cluster-port="9881"/>
</cluster-settings>
</cache-topology>
<client-death-detection enable="False" grace-interval="60sec"/>
</cache-settings>
<cache-deployment deployment-version="0">
<servers>
<server-node ip="10.244.0.10" active-mirror-node="False"/>
<server-node ip="10.244.0.11" active-mirror-node="False"/>
</servers>
</cache-deployment>
</cache-config>
Replace 10.244.0.10 and 10.244.0.11 with the current IP addresses of ncache-0 and ncache-1 from Step 2, keeping the same cache definition and server list on both servers. The example allocates 1024 MB per server, uses LRU eviction with a 5% eviction ratio, and communicates between servers on TCP port 9881. Allow this port between the server pods; it is separate from the client connection port 9800.
If you configure additional clustered caches, give each one a different unused cluster port. The supplied defaultPubSub definition already uses 9882, so retain that port for it.
From the terminal where you run kubectl, open a shell on the first server to write its updated configuration without an editor inside the container:
kubectl exec -it --namespace ncache ncache-0 -- sh
Back up the existing configuration inside the container:
cp /opt/ncache/config/config.ncconf /opt/ncache/config/config.ncconf.bak
Use the following heredoc template to write a new copy of the complete configuration. Before running it, replace PASTE_COMPLETE_UPDATED_CONFIG_HERE with the entire updated file for this server, including the XML declaration, enclosing <configuration> element, and every cache definition from its saved file. The XML example above updates only the defaultCache entry and must not be used as the whole file.
cat > /opt/ncache/config/config.ncconf.new <<'EOF'
PASTE_COMPLETE_UPDATED_CONFIG_HERE
EOF
Place the closing EOF on a line by itself without indentation, then review the new file:
cat /opt/ncache/config/config.ncconf.new
Confirm that it contains the complete configuration, retains the other cache entries, and includes the correct server addresses for defaultCache. Once these checks pass, replace the existing file and return to your local terminal:
mv /opt/ncache/config/config.ncconf.new /opt/ncache/config/config.ncconf
exit
Open a shell on ncache-1 and repeat the backup, heredoc, review, and replacement commands above, then run exit. Use this server's own complete configuration while keeping the updated defaultCache definition identical on both servers:
kubectl exec -it --namespace ncache ncache-1 -- sh
For a larger cluster, apply the update on every server. Keep the complete edited files and their backups outside the pods so that you can restore them if Kubernetes replaces a container or pod.
Step 4: Apply the Configuration Changes
After completing Step 3 on every server, restart the NCache service inside both ncache-0 and ncache-1 so that each service reloads its updated config.ncconf. Plan an interruption and preserve required data before restarting an existing cache deployment.
From your local terminal, open a shell on the first server:
kubectl exec -it --namespace ncache ncache-0 -- sh
Inside the container, list the NCache daemon processes to identify the running service:
ps -eo pid,args | grep '[A]lachisoft.NCache.Daemon'
Identify the running service process, rather than the container's startup shell or a cache process. Replace 1234 below with its actual PID, then send it a termination signal:
kill -TERM 1234
Run the process-list command again and wait until that service process has exited before starting another instance. Restart the service in the background using the image's daemon executable:
nohup /opt/ncache/bin/service/Alachisoft.NCache.Daemon /opt/ncache/ > /tmp/ncache-service.log 2>&1 < /dev/null &
Check that the service process is running and inspect the startup output before leaving the shell:
ps -eo pid,args | grep '[A]lachisoft.NCache.Daemon'
cat /tmp/ncache-service.log
exit
Back in your local terminal, open a shell on ncache-1 and repeat the process identification, stop, background start, and verification commands, then run exit. Identify this server's service PID separately; do not reuse the PID from ncache-0:
kubectl exec -it --namespace ncache ncache-1 -- sh
For a larger cluster, repeat the procedure on every server before checking the cache. If the service does not start, inspect its startup output and configuration before proceeding.
Once the NCache services have restarted on every server, run the following from your local terminal to start defaultCache on the two example servers:
kubectl exec --namespace ncache ncache-0 -- /opt/ncache/bin/tools/start-cache -Name defaultCache
kubectl exec --namespace ncache ncache-1 -- /opt/ncache/bin/tools/start-cache -Name defaultCache
Check the configured caches on each server:
kubectl exec --namespace ncache ncache-0 -- /opt/ncache/bin/tools/get-caches
kubectl exec --namespace ncache ncache-1 -- /opt/ncache/bin/tools/get-caches
For a larger cluster, repeat the start-cache and get-caches commands for every additional server. Confirm that defaultCache is running on all configured members, then inspect the cache logs under /opt/ncache/log-files on each server to confirm that the Replicated cache includes every configured server: two members for this example. A running pod or a cache running on only one server is not sufficient verification. If the servers do not join the same cluster, compare their cache definitions, pod IP addresses, cluster ports, and network access before proceeding.
Do not delete the pods as a substitute for restarting the NCache service: pod replacement can discard the copied configuration and change the server addresses. If a pod is replaced, restore its configuration and update the member addresses on all affected servers before restarting the cache.
Step 5: Connect and Verify the Application
For this verification example, run the application inside the Kubernetes cluster and connect directly to both server pod IP addresses, since NCache Open Source does not support load balancers. An application outside the cluster requires network access to the server endpoints and ports used by the cache.
Add the Open Source client package matching your server version to the .NET console application. For this 5.3.603 example, use:
dotnet add package Alachisoft.NCache.OpenSource.SDK --version 5.3.603
Replace the console application's Program.cs contents with the following example, which uses the CacheConnectionOptions API available in that Open Source package. NCACHE_SERVER_0 and NCACHE_SERVER_1 are environment variables defined for this example; set them to the current server pod IP addresses when deploying the application.
using System;
using System.Collections.Generic;
using Alachisoft.NCache.Client;
class Program
{
static void Main()
{
string server0 = Environment.GetEnvironmentVariable("NCACHE_SERVER_0");
string server1 = Environment.GetEnvironmentVariable("NCACHE_SERVER_1");
if (string.IsNullOrWhiteSpace(server0) || string.IsNullOrWhiteSpace(server1))
throw new InvalidOperationException("Set both NCache server pod addresses.");
var options = new CacheConnectionOptions
{
ServerList = new List<ServerInfo>
{
new ServerInfo(server0, 9800),
new ServerInfo(server1, 9800)
}
};
using (ICache cache = CacheManager.GetCache("defaultCache", options))
{
string key = "oss-verification:" + Guid.NewGuid();
cache.Insert(key, "Kubernetes cache check");
string value = cache.Get<string>(key);
if (value != "Kubernetes cache check")
throw new InvalidOperationException("The retrieved value did not match.");
cache.Remove(key);
Console.WriteLine("Cache write and read succeeded.");
}
}
}
Build the application into your own container image and publish it to a registry accessible to the cluster. Run the image in the ncache namespace, replacing the image and server-address placeholders:
kubectl run ncache-oss-check --namespace ncache --image="<your-test-application-image>" --restart=Never --env="NCACHE_SERVER_0=<ncache-0-pod-ip>" --env="NCACHE_SERVER_1=<ncache-1-pod-ip>"
kubectl logs --namespace ncache -f ncache-oss-check --pod-running-timeout=2m
A successful run prints Cache write and read succeeded. and exits with the pod in the Completed state, which you can check using kubectl get pod ncache-oss-check --namespace ncache. This confirms that the application can connect to the cache and write and retrieve an item; the membership checks in Step 4 establish that both servers have joined the cluster.
If the application fails, inspect its logs and check the cache name, both pod addresses, registration, and network access from the application pod. After verification, remove the test application pod:
kubectl delete pod ncache-oss-check --namespace ncache
Update the Deployment
To change Kubernetes settings, edit the relevant YAML manifest and apply it again with kubectl apply.
To add a deployed server to an existing cache, add its pod IP address as a new <server-node> entry inside the <servers> element under <cache-deployment> in the cache's <cache-config> block. For example, the following adds 10.244.0.11 to a cache that already includes 10.244.0.10:
<cache-deployment deployment-version="0">
<servers>
<server-node ip="10.244.0.10" active-mirror-node="False"/>
<server-node ip="10.244.0.11" active-mirror-node="False"/>
</servers>
</cache-deployment>
Replace the example addresses with your server pod IP addresses, then copy the updated <cache-config> block into config.ncconf on every server, including the new one. Use the complete-file EOF procedure in Configure the Cache to save each server's configuration while retaining its other cache definitions. Then restart the NCache service on every server and verify the cache as described in Apply the Configuration Changes.
Apply other cache configuration changes to every affected server in the same way; updating a Kubernetes manifest alone does not update config.ncconf.
Because pod replacement can change server IP addresses, verify the configured cache members after each replacement and update the configuration to match the running servers.
Remove the Deployment
Remove the resources using the same manifests and namespace:
kubectl delete --namespace ncache -f ncache.yaml
kubectl delete --namespace ncache -f discoveryservice.yaml
Preserve any required data and configuration before removing the deployment, as deleting the StatefulSet removes its server pods and makes the caches unavailable.