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 server Helm release. The supplied app.yaml illustrates the application settings; you must create a manifest for your own application.

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 configured an OutProc Client Cache for that distributed cache using Create Regular Client Cache. Client Cache is not available for a Pub/Sub store.
You have an NCache client container image, a valid client registration key, and any image registry credentials required by that image.
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.

Deployment Process

Step 1: Prepare the Client Manifest

Obtain ncache-client-outproc.yaml from the NCache GitHub repository. In the client container definition, specify your NCache client image and registration key. The following example shows the relevant settings; replace the placeholders with your own values:

containers:
  - name: ncache-client
    image: "<ncache-client-image>"
    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. The example uses ncache-secret; remove that entry if your image does not require a pull Secret.
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. The supplied application example uses a locally preloaded test image, imagePullPolicy: Never, and sleep infinity; replace these with the image-pull policy and startup command appropriate for 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

The example app.yaml places its two application replicas on different nodes, which requires at least two eligible worker nodes if that anti-affinity setting is retained. 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 that the application connects to the intended distributed cache using its configured Client Cache.
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; upgrading the NCache server Helm release does not update this separate client deployment.

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 server Helm release are not removed by this command.