Deploy NCache with Kubernetes On-Premises

An on-premises Kubernetes deployment allows you to run NCache within your own infrastructure, where your organization manages the cluster, worker nodes, and networking. You can deploy NCache using the Helm chart or YAML files to create the server containers and gateway services for cache connections and NCache Management Center.

This page explains how to prepare the required load balancer, install NCache on an existing Kubernetes cluster, and connect applications through the client gateway. The examples use the default two-server configuration.

Prerequisites

You have access to an existing cluster, or permission to create one as described below.
You must have kubectl installed and configured.
You have permission to create namespace resources and cluster-wide RBAC resources. If deploying with Helm, Helm 3.14 or later is installed and configured.
You have the Enterprise YAML files or access to the selected NCache OCI chart version.
You must have access to the NCache Docker image.
You must have a valid deployment key and, for a production license, the license key and matching environment name.
You must have a load balancer installed, configured, and running for Kubernetes LoadBalancer services before deploying NCache. In on-premises or bare-metal Kubernetes environments, you can use MetalLB or another on-premises load balancer.
If you use MetalLB, you must also have a valid and dedicated IP address range available for the MetalLB IP address pool.
The cluster must run Kubernetes version 1.25.0 or later and provide at least two schedulable Linux worker nodes for the default two-server deployment. For Helm, the default setting, deployment.podAntiAffinity=true, places each server on a separate node. If shared-node placement is acceptable, this value can be set to false during installation.

Create an On-Premises Cluster

If you do not already have a Kubernetes cluster, create one on your physical servers or virtual machines. The following outlines the setup using kubeadm; follow Creating a Cluster with kubeadm for the complete procedure.

Prepare the control-plane and worker machines with a supported container runtime and the required Kubernetes tools. Provide at least two Linux worker nodes for the default two-server NCache deployment.
Initialize the control plane using kubeadm init, with the network settings required by your chosen Pod network.
Configure cluster access using the generated Kubernetes configuration file, and install a compatible Container Network Interface (CNI) plugin to enable communication between pods.
Add the worker nodes using the kubeadm join command generated during initialization.
Configure MetalLB or another load balancer to support the NCache gateway services, and ensure that the worker nodes are ready before deploying NCache.

Deployment Process

Choose the deployment method below after connecting to your cluster. The Helm examples use the ncache namespace; the Enterprise YAML examples use default. Use one method for a deployment so that the same resources are not managed by both Helm and YAML files.

Verify Cluster Access

Confirm that kubectl targets the intended cluster and that the worker nodes are ready:

kubectl config current-context
kubectl get nodes

Deploy Using Helm

After confirming cluster access, prepare the chart and install NCache using the following steps.

Step 1: Prepare the NCache Helm Chart

Open a PowerShell terminal connected to your cluster. The NCache chart is available directly from the OCI registry.
Inspect the defaults for the NCache chart you intend to install:

helm show values oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8

Step 2: Install Helm Chart

Run the following command to deploy two NCache servers with defaultCache enabled. Replace xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your deployment key:

helm install ncache oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8 --namespace ncache --create-namespace `
  --set-string deployment.key="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" `
  --set-string deployment.platform="on-prem"

Tip

For guidance on deploying in different scenarios, refer to Manage an Existing Deployment.

Verify the Server Pods

Check the pods and their worker-node placement after installation:

kubectl rollout status statefulset/ncache --namespace ncache
kubectl get pods,jobs --namespace ncache
kubectl get pods --namespace ncache -o wide

After Helm installs the release, NCache completes cache configuration and licensing through a configuration job. Follow Verify an Update to check the job result, then verify the caches in NCache Management Center before using the deployment.

Verify that all configured NCache server pods are ready; the default deployment contains two. If a pod fails to start, inspect its events and logs using its actual name, and check the deployment key, licensing values, and image access:

kubectl describe pod "<pod-name>" --namespace ncache
kubectl logs "<pod-name>" --namespace ncache

Step 3: Verify NCache Services

Check the gateway services created by the installed chart:

kubectl get svc --namespace ncache

Check the client endpoint and the configured Service ports. Configure public management access in Step 4:

Client connections: gateway.clientPort defaults to 9800.
Management: gateway.mgmtPorts defaults to 9801-9802, with session affinity.
Additional gateway ports: gateway.ports defaults to 9803-9997.
Portal: gateway.portalPorts defaults to 9998-9999, with session affinity.

Step 4: Access NCache Management Center

To access NCache Management Center through a public endpoint, configure gateway.mgmtCenterEndpoint. This value can be supplied during helm install or added afterward using helm upgrade.

If you have already installed NCache, use the following command. Replace <management-public-ip> with a public IPv4 address available through your cluster's load balancer infrastructure:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8 --namespace ncache --reuse-values --set-string gateway.mgmtCenterEndpoint="<management-public-ip>"

Check the management gateway Service and confirm that its external endpoint has been assigned:

kubectl get svc --namespace ncache

Use the configured endpoint to open NCache Management Center at http://<management-public-ip>:9801 or, when HTTPS is configured, https://<management-public-ip>:9802.

Verify that the intended caches are running on both servers, then follow Connect Client Applications from Outside Kubernetes to connect an application and verify it by adding and retrieving an item. Management Center also provides the tools for ongoing cache management and monitoring.

Deploy Using YAML Files

After confirming cluster access, prepare and apply the server and gateway manifests using the following steps.

Step 1: Prepare the Deployment Files

Obtain the Enterprise Kubernetes YAML files from the NCache GitHub repository, and work from the folder containing ncache.yaml and the platform gateway folders. Use the shared ncache.yaml for the servers and the two gateway files identified below.

Use the default namespace for these manifests.
In the NCache container's environment variables, set NC_KEY to your deployment key:

- name: NC_KEY
  value: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Ensure that the StatefulSet's spec.serviceName is ncache-cacheserver, matching the headless Service in the same file. Add the following field under the StatefulSet's existing spec; retain the other settings:

spec:
  serviceName: ncache-cacheserver

Verify that the container image is accessible. If it requires registry credentials, create the ncache-secret image pull Secret in the default namespace; otherwise, remove the imagePullSecrets entry.
Keep replicas: 2 for the default two-server deployment and NC_START_DEFAULT_CACHE set to "true". The supplied YAML prefers separate worker nodes but allows both pods to run on the same node. Configure required pod anti-affinity if each server must run on a separate node.
If TLS is required, prepare the Secret and environment variables before applying the files, as described in Deploy Using YAML Files.

Retain the Service selectors and pod labels so that the gateways continue to route traffic to the NCache servers.

Use Kubernetes/client-gatewayservice.yaml and Kubernetes/mgmt-gatewayservice.yaml. Configure MetalLB with an address pool reachable from the application and administrator networks. The supplied files include MetalLB shared-IP annotations; if you use another load balancer, replace these with the settings required by that implementation.

To request a particular management address from the pool, set spec.loadBalancerIP in Kubernetes/mgmt-gatewayservice.yaml. Otherwise, allow the load balancer to allocate the address and use the endpoint reported by the Service.

Step 2: Deploy NCache

Apply the server manifest and both gateway manifests from the package root:

kubectl apply --namespace default -f ncache.yaml
kubectl apply --namespace default -f Kubernetes/client-gatewayservice.yaml
kubectl apply --namespace default -f Kubernetes/mgmt-gatewayservice.yaml

Verify the Server Pods

Check that both server pods have started and inspect their worker-node placement:

kubectl rollout status statefulset/ncache --namespace default
kubectl get pods --namespace default -l app=ncache -o wide

The default deployment creates ncache-0 and ncache-1. If a pod fails to start, inspect its events and logs, and check the deployment key, image access, and any certificate settings:

kubectl describe pod "<pod-name>" --namespace default
kubectl logs "<pod-name>" --namespace default

Pod status does not confirm that the caches are ready. Verify cache status in NCache Management Center after opening the management endpoint in Step 4.

Step 3: Verify NCache Services

Check that the headless Service and both gateway Services exist:

kubectl get svc ncache-cacheserver ncache-client-gateway ncache-mgmt-gateway --namespace default

Wait until the gateway endpoints have been assigned, and confirm that they are reachable from the application and administrator networks. The client gateway exposes port 9800. The management gateway exposes ports 9801 and 9802 for Management Center and ports 9998 and 9999 for the portal.

The client gateway also exposes ports 9803-9997. Confirm that the load balancer and firewall configuration permit the ports required by your deployment.

Step 4: Access NCache Management Center

Use the management gateway's assigned external IP address or DNS hostname:

kubectl get svc ncache-mgmt-gateway --namespace default

Open http://<management-gateway-endpoint>:9801 or, when Management Center HTTPS is configured, https://<management-gateway-endpoint>:9802. The endpoint is the value reported in the Service's EXTERNAL-IP column.

In NCache Management Center, verify that the intended cache is running on both server nodes before using it. Follow Configure the External Client to connect an application through the client gateway using ConnectionOptions, then add an item to the cache and retrieve it to verify the connection. For licensing, cache changes, and subsequent updates, follow the YAML tabs in Manage Deployment.

Connect Client Applications from Outside Kubernetes

Use the external IP address or DNS name assigned to the client gateway to connect applications outside Kubernetes. The endpoint must be reachable from the client network. Internal pod addresses and discovery names are not suitable for clients that cannot reach the cluster network.

Verify the Client Gateway Service

Identify the client gateway and its external endpoint. Use ncache for the Helm examples or default for the YAML examples:

kubectl get svc ncache-client-gateway --namespace "<deployment-namespace>"

Verify that the endpoint is reachable on the configured client port, which defaults to 9800.

Configure the External Client

Configure the external endpoint through ConnectionOptions and pass the options to CacheManager.GetCache. Add a ServerInfo entry with isLoadBalancer: true so that the endpoint is treated as a load balancer.

The following C# example connects to the default cache. Replace <client-gateway-endpoint> with the gateway's external IP address or DNS name, and change the port if you configured a different client Service port:

using System.Collections.Generic;
using Alachisoft.NCache.Client;

ConnectionOptions options = new ConnectionOptions
{
    IsInproc = false,
    Servers = new List<ServerInfo>
    {
        new ServerInfo(isLoadBalancer: true, name: "<client-gateway-endpoint>", port: 9800)
    }
};

ICache cache = CacheManager.GetCache("defaultCache", options);

For mutual TLS, set options.TLSCertPath to the client certificate path and options.TLSCertPassword when its private key is encrypted. The client certificate can use PEM format or, for .NET Framework applications, PFX format.

Client connection tuning, load balancing, logging, and client cache settings are managed by the cache server and provided to the client when it connects. Configure the application endpoint and any mutual TLS certificate settings through ConnectionOptions.

For information on managing licensing, changing cache settings, and upgrading the deployment, see Manage Deployment.

Deploy NCache with Kubernetes On-Premises

Prerequisites

Create an On-Premises Cluster

Deployment Process

Verify Cluster Access

Deploy Using Helm

Step 1: Prepare the NCache Helm Chart

Step 2: Install Helm Chart

Tip

Step 3: Verify NCache Services

Step 4: Access NCache Management Center

Deploy Using YAML Files

Step 1: Prepare the Deployment Files

Step 2: Deploy NCache

Step 3: Verify NCache Services

Step 4: Access NCache Management Center

Connect Client Applications from Outside Kubernetes

Verify the Client Gateway Service

Configure the External Client

See Also

Contact Us