Manage an Existing Deployment

After deploying NCache, you can use Helm to increase the server count, manage licensing, update cache settings and gateway configuration, and upgrade container images. These operations follow the same procedure on on-premises Kubernetes, AKS, EKS, GKE, and OpenShift, except where platform-specific gateway settings are required. Existing platform settings are retained during each operation.

This page describes the supported changes and the procedures for evaluation re-registration, image upgrades, and recovery. Run the commands from a terminal connected to the cluster, using the release name and namespace specified during installation. The examples use ncache for both and can be run in PowerShell or Bash.

A change to the NCache container image is an image upgrade; other supported changes are configuration updates. Both operations use helm upgrade. Each operation must be limited to one configuration group: deployment settings, image settings, licensing, cache settings, or gateway settings, including EKS subnets. The examples include --reuse-values to retain settings that are not being changed. When more than one group requires an update, complete each operation before starting the next.

Scale the Cluster

The number of NCache servers is specified through deployment.servers, which defaults to 2. You can increase this value after installation using helm upgrade. For example, the following command increases the deployment to three server pods:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set deployment.servers=3

Ensure that the cluster has sufficient resources for the additional servers. When deployment.podAntiAffinity is true, each server pod requires a separate worker node.

Within the deployment group, you can update deployment.key and increase deployment.servers. Changes to the deployment name, platform, or pod anti-affinity require redeployment. TLS settings must also be configured during installation, as described in Deploy TLS With NCache Kubernetes. NCache configuration changes that require an NCache service restart are not supported as updates.

Extend the Evaluation Period

The deployment key is registered when each server starts. After support approves an evaluation extension, update the stored key if a different key was supplied:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set-string deployment.key="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

If the previous operation was an offline image upgrade, first return the deployment to rolling mode in a separate Helm operation:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set image.upgrade=rolling

Once the operation has completed, restart the servers to register the key. This restart is also required when support extends the evaluation associated with the existing key, because reapplying that key through helm upgrade does not restart or re-register running servers.

kubectl rollout restart statefulset/ncache --namespace ncache
kubectl rollout status statefulset/ncache --namespace ncache

The restart replaces servers one at a time. Data availability depends on the cache topology and healthy remaining replicas; do not assume data preservation for a single-server or non-replicated cache. An image using a mutable tag such as latest can also pull a different image during restart, so use a fixed image version when the restart must retain the installed version. Replace ncache in statefulset/ncache if you installed with a different deployment.name. Verify the updated evaluation period in NCache Management Center after the rollout completes.

Activate a Production License

The following command activates the production license on all server pods. Replace xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your license key and Production with the environment associated with that license:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set-string license.licenseKey="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --set-string license.envName="Production" --set-string license.action="activate"

Deactivate a Production License

The following command deactivates the production license on all server pods. Replace xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your license key and Production with the environment associated with that license:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set-string license.licenseKey="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --set-string license.envName="Production" --set-string license.action="deactivate"

Perform a Rolling Upgrade

A rolling upgrade replaces one pod at a time, starting with the highest-numbered pod and proceeding in descending order. For the default two-server deployment, ncache-1 is upgraded before ncache-0. Each pod must become ready and complete the configured delay before the next pod is upgraded. The upgrade succeeds only when all server pods have been upgraded; otherwise, the chart attempts to restore the previous image. Verify all server pods and caches after a failed upgrade.

Use a different image tag from the installed image; re-publishing the same tag does not trigger this upgrade. For a supported patch or minor version transition, upgrade the NCache image in rolling mode:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set-string image.repository="alachisoft/ncache" --set-string image.tag="<target-image-tag>" --set image.upgrade=rolling --set image.delayMinutes=2

If an upgrade fails, the rollout stops at the first failed server and attempts to restore the previous image. Recovery relies on healthy remaining replicas retaining configuration and data; this recovery does not restore a backup. A single-server or non-replicated cache does not provide the same data-preservation guarantee. An upgraded server becomes ready after joining every cache.

The image revert does not restore the Helm release's recorded values. Inspect the release history and roll back to the revision used before the failed upgrade; otherwise, the next --reuse-values upgrade can retry the failed image:

helm history ncache --namespace ncache
helm rollback ncache "<previous-revision>" --namespace ncache

Replace <previous-revision> with the numeric revision from the release history. If the image revert also fails, correct the underlying problem, such as an image-pull failure or insufficient resources, delete only the affected stuck pod, and then run the Helm rollback:

kubectl delete pod "<stuck-pod-name>" --namespace ncache

Verify server readiness and cache availability after recovery. If required data is no longer available on surviving servers, restore it from your backup.

Perform an Offline Upgrade

An offline upgrade requires downtime while the chart backs up configuration and data, stops all server pods, replaces them with the target image, and restores the caches. Application writes are not stopped automatically, so stop writes and take an independent backup of both configuration and data before starting the upgrade. Keep writes stopped until restoration has been verified. The upgrade job uses temporary backup storage that is lost if its pod fails; in that situation, recover the configuration manually and restore data from the independent backup before resuming writes.

For a supported major version transition, upgrade in offline mode:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set-string image.repository="alachisoft/ncache" --set-string image.tag="<target-image-tag>" --set image.upgrade=offline

Update Cache Settings

The caches entries configure the caches in the deployment. Only caches[0], named defaultCache by default, is enabled during a default installation. The chart provides names for the first four cache entries, so a name does not need to be supplied when enabling an entry.

The following command enables caches[1] using its default name, sessionCache, or its previously configured name:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set 'caches[1].enabled=true'

Additional cache entries must be enabled in order: caches[1] before caches[2], followed by caches[3]. You can also configure evictionRatio for each cache entry to control eviction. The available settings for each entry are described under cache values.

Warning

Disabling a cache deletes it. Changing an existing cache definition recreates it without preserving its data. Preserve required data before applying these changes.

After the update completes, verify the caches in NCache Management Center, which provides tools for cache management and monitoring.

Update Gateway Settings

The chart creates client and management LoadBalancer services. Their endpoints must be reachable from the networks used by client applications and administrators. Apply gateway changes separately from deployment, licensing, image, or cache changes.

On-Premises, AKS, GKE, and OpenShift

To request a specific management IPv4 address, set gateway.mgmtCenterEndpoint to an address available to the cluster's load balancer. For on-premises and bare-metal OpenShift deployments, allocate the address through the configured load balancer infrastructure. For AKS and GKE, ensure that the reserved address is compatible with the cluster's load balancer configuration.

Replace <management-ip> with the address allocated for your deployment:

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

EKS

The chart requests an internal AWS Network Load Balancer for client connections and an internet-facing Network Load Balancer for management. Client applications must have network access to the internal endpoint.

For a custom management hostname, supply gateway.mgmtCenterEndpoint and at least two public subnet IDs from different Availability Zones, joined with +. An IPv4 address is not accepted for the EKS management endpoint.

Replace the example hostname and subnet IDs with those for your environment:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --reuse-values --set-string gateway.mgmtCenterEndpoint="ncache.example.com" --set-string eks.publicSubnetIds="subnet-0123456789abcdef0+subnet-0fedcba9876543210"

Configure DNS to resolve the management hostname to the assigned load balancer.

After updating gateway settings on any platform, check the services and verify that the assigned endpoints are reachable:

kubectl get svc -n ncache

The unified chart values describe the available gateway ports and settings.

Verify the Deployment

Check server readiness and any remaining configuration jobs, then verify licensing and cache availability in NCache Management Center. A successful Helm command alone does not confirm completion of the configuration work.

kubectl get pods,jobs -n ncache

If a job fails, use its actual name to inspect the logs:

kubectl logs -n ncache "job/<job-name>"