Deploy an Out-of-Process Client Cache with Kubernetes

An out-of-process Client Cache stores frequently accessed data in an NCache process close to the application. In Kubernetes, an NCache client container runs on each eligible worker node so that application pods can use a Client Cache on the same node while remaining connected to the distributed cache.

This page explains how to deploy these client containers using ncache-client-outproc.yaml and configure your application to locate them through NCACHE_CLIENT_HOST. The client deployment is managed separately from the NCache servers, whether those servers use Helm or YAML files. The supplied app.yaml illustrates the application settings; you must create a manifest for your own application.

Configure the Client Cache for the distributed cache through Helm values or NCache Management Center, then deploy the client containers using the separate YAML manifest. Updating the server deployment does not automatically update these client containers.

Prerequisites

You have a Kubernetes cluster and kubectl configured for the intended context.
You have a running distributed cache and network access to its server or client-gateway endpoint from the application and client containers.
You have enabled an out-of-process Client Cache for the distributed cache, as described in Update Cache Settings. For Helm, use caches[N].clientCache.enabled=true and caches[N].clientCache.isolationLevel=outproc; the Client Cache for defaultCache is enabled with outproc isolation by default. For YAML server deployments, configure the Client Cache through NCache Management Center. Client Cache is not available for a Pub/Sub store.
You have the NCache container image alachisoft/ncache:5.3.800 or a later supported version, a valid client registration key, and any required image registry credentials. This Client Cache deployment requires NCache 5.3.800 or later.
The worker nodes permit the client container and have TCP host ports 9803 and 9804 available. The supplied manifest binds these ports on each eligible node; they must not conflict with another workload.
Your application uses the NCache client library and can run on the same worker nodes as the NCache client containers.
If standard or mutual TLS is enabled on the cache servers, apply the corresponding TLS settings to the out-of-process Client Cache as well. The server deployment does not configure TLS for these separate client containers.

Deployment Process

Step 1: Prepare the Client Manifest

Obtain ncache-client-outproc.yaml from the NCache Kubernetes GitHub repository. In the client container definition, use NCache 5.3.800 or a later supported version and supply your registration key. The following example uses alachisoft/ncache:5.3.800; replace the registration-key placeholder with your own key:

containers:
  - name: ncache-client
    image: "alachisoft/ncache:5.3.800"
    imagePullPolicy: Always
    env:
      - name: NC_REGISTER_AS
        value: "Client"
      - name: NC_KEY
        value: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

This excerpt illustrates the container settings within the manifest. Retain the other container settings, DaemonSet configuration, and Service port definitions when editing the file.

Keep NC_REGISTER_AS set to Client. If the image requires authentication, create the image pull Secret in the deployment namespace and set imagePullSecrets to its name. If the manifest references ncache-secret, create a Secret with that name or update the reference to your Secret. Remove the imagePullSecrets entry if your image does not require registry authentication.
Use a namespace shared by the application and client containers. These examples use ncache-client; create it if it does not already exist:

kubectl create namespace ncache-client

The ncache-client Service uses internalTrafficPolicy: Local to send traffic only to client pods on the application's worker node. Keep its TCP ports 9800, 9801, 9803, 9804, and 9831-9880 as declared in the supplied manifest. Port 9803 provides management RPC access, 9804 provides metrics and service health checks, and 9831-9880 is the CacheHost range. See Firewalls and Ports for port assignments.

Step 2: Deploy the NCache Client Containers

Apply the prepared client manifest using the following commands, replacing YAML_FILE_PATH.yaml with the path to your edited ncache-client-outproc.yaml file:

kubectl apply --namespace ncache-client -f "YAML_FILE_PATH.yaml"
kubectl rollout status daemonset/ncache-client --namespace ncache-client
kubectl get pods --namespace ncache-client -l app=ncache-client -o wide

Verify that an NCache client pod is ready on each node where an application pod will run. A node without a local client endpoint cannot serve traffic through this Service's local traffic policy.

Step 3: Configure Your Application Manifest

Create your own app.yaml using your application image, entry point, resource requirements, and replica count. If you start from the supplied app.yaml, replace its image, image-pull policy, and startup command with those required to run your application.

Set NCACHE_CLIENT_HOST in the application container to ncache-client so that the application can locate the local NCache client Service. It identifies the local client host rather than the remote distributed cache server. Add the following setting under your application's container definition:

env:
  - name: NCACHE_CLIENT_HOST
    value: "ncache-client"

Schedule application pods on nodes that have an NCache client pod. Add the following under the application pod's spec, retaining any other scheduling requirements your application needs:

affinity:
  podAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app: ncache-client
        topologyKey: kubernetes.io/hostname

If you retain the supplied app.yaml's two replicas and pod anti-affinity, provide at least two eligible worker nodes. These settings belong to the supplied application manifest and are not included in the excerpt above. Both workloads must use the same namespace for the Service name and pod-affinity selector to resolve as shown.

Configure the application to connect to the distributed cache by name through ConnectionOptions. Its Servers list identifies the distributed cache endpoint; NCACHE_CLIENT_HOST separately identifies the local client host. For a gateway endpoint, use ServerInfo with isLoadBalancer: true, as shown in Configure the External Client. Leave IgnoreClientCache disabled so that the application can use the server-provided Client Cache configuration.

Step 4: Deploy and Verify Your Application

Apply your application manifest after the client containers are ready:

kubectl apply --namespace ncache-client -f app.yaml
kubectl get pods --namespace ncache-client -o wide

Verify that each application pod shares a worker node with a ready NCache client pod and connects to the intended distributed cache using its configured Client Cache. Add an item and retrieve it from the application to verify the connection.
If a connection fails, check the exact NCACHE_CLIENT_HOST name and value, the namespace, local client pod readiness, image registration, and network access to the distributed cache. Inspect the affected pod's logs:

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

Changes to these manifests are applied with kubectl apply; updating the NCache server deployment does not update these separate client containers.

Step 5: Remove the Client Deployment

Remove the resources created by the client manifest using the same file and namespace:

kubectl delete --namespace ncache-client -f "YAML_FILE_PATH.yaml"

Replace YAML_FILE_PATH.yaml with the path used during deployment. This removes the client DaemonSet and Service, including its managed pods. Applications using these client containers lose their local Client Cache connection. The separately deployed application and NCache servers are not removed by this command.