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. The NCache Helm chart configures the server containers and gateway services that provide access to the caches 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 must have Helm installed and configured, with permission to create namespace resources and the chart’s cluster-wide RBAC resources.
  • The NCache OCI chart and selected chart version are accessible.
  • 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 installing the NCache Helm chart. 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. 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 proceeding with the Helm installation.

Deployment Process

Follow the steps below to deploy NCache with Kubernetes.

Step 1: Prepare the NCache Helm Chart

  • Open a PowerShell terminal connected to your cluster. The unified OCI chart can be installed directly, so uploading a provider-specific package is no longer required.

  • Inspect the defaults for the NCache chart you intend to install:

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

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 --version 1.0.0 --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 get pods,jobs -n ncache
kubectl get pods -n ncache -o wide

After Helm installs the release, NCache completes cache configuration and licensing through a configuration job. Check for failed jobs and 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 access to the selected image.

Step 3: Verify NCache Services

  • Check the gateway services created by the installed chart:
kubectl get svc -n ncache

Verify that the required endpoints are assigned and reachable:

  • 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

Use the gateway's external IP address or DNS name to access the NCache Management Center. The default direct-access URLs are http://<management-gateway-endpoint>:9801 and, when HTTPS is configured, https://<management-gateway-endpoint>:9802.

When accessing Management Center through an HTTPS load balancer, use the configured public HTTPS endpoint and forward requests to HTTP port 9801 with sticky sessions enabled. For the NCache Cloud Portal, which uses HTTPS port 9998 and HTTP port 9999, configure the HTTPS load balancer to forward requests to HTTP port 9999 with sticky sessions enabled. These port assignments are described in Firewalls and Ports.

After verifying the deployed caches in NCache Management Center, follow Getting Started to begin using NCache. Management Center also provides the tools for ongoing cache management and monitoring.

Step 5: 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 from the installed release:

kubectl get svc -n ncache

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 gateway.clientPort has been overridden:

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.

See Also

Evaluation Period Management
License Management