Manage an Existing Deployment

After deploying NCache, you can change server capacity, manage licensing and caches, and update gateway, TLS, and image settings. The procedure depends on whether the servers were deployed through Helm or YAML files. Select the matching tab for each task and retain the platform settings used during installation.

Run the commands from a terminal connected to the intended cluster. The Helm examples use ncache for the release name and namespace; the Enterprise YAML examples use the ncache StatefulSet in the default namespace.

For Helm deployments, image changes are upgrades and other supported changes are configuration updates. Both use helm upgrade. Configuration updates can be combined, but changes to any image setting must run separately from other categories, including changes to pull settings, upgrade mode, or timing. The examples use --reuse-values to retain settings that are not being changed.

For YAML deployments, edit the source manifests and apply Kubernetes resource changes with kubectl apply. Manage cache configuration through NCache Management Center. Use the same deployment method for subsequent operations; applying YAML files to resources managed by Helm can leave the two configurations inconsistent.

Prepare for YAML Pod Replacements

Changes to a container image or environment variable take effect when server pods are replaced. Before applying such a change to an existing YAML deployment, back up required configuration and data, and set the StatefulSet's update strategy to OnDelete in ncache.yaml. This allows you to verify each server's caches before replacing the next server:

spec:
  updateStrategy:
    type: OnDelete

Merge this setting into the existing StatefulSet spec, retaining its other fields. With this strategy, applying a changed pod template does not replace running pods automatically. Follow Replace YAML Server Pods after applying an image, licensing, or TLS change that requires new pods.

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

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8 --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.

To reduce a three-server deployment to two server pods, use the following command:

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

Servers are removed one at a time, starting with the highest-numbered pod. The deployment waits for the caches to synchronize between removals. Ensure that the remaining servers have sufficient capacity for the caches and application workload.

Within the deployment group, you can update deployment.key and change deployment.servers. Changes to the deployment name, platform, or pod anti-affinity require redeployment. TLS settings can be changed through Helm, as described in Update TLS Settings. NCache configuration changes that require an NCache service restart are not supported as updates.

Set spec.replicas in the StatefulSet in ncache.yaml to the required server count. For example, change it from 2 to 3 to add one server, then apply the file:

kubectl apply --namespace default -f ncache.yaml
kubectl get pods --namespace default -l app=ncache -o wide

Ensure that the cluster has sufficient resources, and verify that the new server has joined the intended caches in NCache Management Center before adding another server.

Before reducing the count, preserve required data and ensure that the remaining servers can hold the caches and support the workload. Remove the highest-numbered server from each affected cache using Remove a Server Node, then reduce spec.replicas by one and apply the manifest. Verify cache membership, data availability, and client connections after each removal. Changing a StatefulSet's replica count does not provide the Helm chart's cache-synchronization checks.

Extend the Evaluation Period

Helm
YAML

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-helm --version 5.3.8 --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-helm --version 5.3.8 --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.

After support approves the extension, update NC_KEY in the NCache container's environment variables if a different key was supplied:

- name: NC_KEY
  value: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Follow Prepare for YAML Pod Replacements and apply ncache.yaml:

kubectl apply --namespace default -f ncache.yaml

Follow Replace YAML Server Pods to restart the servers and register the key. Restart them even when the key has not changed; applying the unchanged manifest does not restart the running servers. Verify the evaluation period on every server afterward.

Activate a Production License

Helm
YAML

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-helm --version 5.3.8 --namespace ncache --reuse-values --set-string license.licenseKey="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --set-string license.envName="Production" --set-string license.action="activate"

In ncache.yaml, set NC_LICENSE_KEY to your production license key and NC_LICENSE_ENV to the environment associated with the license. Retain the deployment key in NC_KEY:

- name: NC_LICENSE_KEY
  value: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
- name: NC_LICENSE_ENV
  value: "Production"

For an existing deployment, follow Prepare for YAML Pod Replacements, apply ncache.yaml, and follow Replace YAML Server Pods so that the servers start with the updated licensing settings:

kubectl apply --namespace default -f ncache.yaml

Verify license activation on every server before completing the update. For a new deployment, supply these values before the initial application of the manifest.

Deactivate a Production License

Helm
YAML

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-helm --version 5.3.8 --namespace ncache --reuse-values --set-string license.licenseKey="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --set-string license.envName="Production" --set-string license.action="deactivate"

Deactivate the license on each server using Unregister-NCacheLicense, following License Management. Run the cmdlet from an NCache PowerShell environment that can reach each server's management endpoint.

Clearing NC_LICENSE_KEY in the manifest does not deactivate a license already registered on a server. Before any subsequent pod replacement, update the deployment's licensing settings so that the license is not activated again at startup. Verify the license state on every server after deactivation.

Perform a Rolling Upgrade

Helm
YAML

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-helm --version 5.3.8 --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.

For a supported patch or minor version transition, follow Prepare for YAML Pod Replacements and change the NCache container's image in ncache.yaml to the target version. Use a fixed image tag and retain the remaining container settings:

image: "alachisoft/ncache:<target-image-tag>"

Apply the file, then follow Replace YAML Server Pods to replace one server at a time, starting with the highest-numbered pod:

kubectl apply --namespace default -f ncache.yaml

Before proceeding to the next server, verify that the replacement has joined every intended cache and that data and client operations are available. Data availability during replacement depends on healthy replicas and the cache topology; use an offline procedure when the caches cannot remain available during a server replacement.

For YAML deployments, a failed replacement requires manual recovery. If a replacement fails, stop the procedure and inspect the affected pod's events and logs. Correct the cause before replacing another server. Restore configuration and data from independent backups if they are no longer available.

Perform an Offline Upgrade

Helm
YAML

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-helm --version 5.3.8 --namespace ncache --reuse-values --set-string image.repository="alachisoft/ncache" --set-string image.tag="<target-image-tag>" --set image.upgrade=offline

Plan downtime for a supported major version transition. Stop application writes, export the required configuration and cache data, and keep the backups outside the server pods. Record the existing image and replica count before proceeding.

Set the StatefulSet's spec.replicas to 0 in ncache.yaml, apply the file, and wait for the server pods to terminate:

kubectl apply --namespace default -f ncache.yaml
kubectl get pods --namespace default -l app=ncache

Change the container's image to the target version, restore the required replica count in ncache.yaml, and apply the file again:

kubectl apply --namespace default -f ncache.yaml
kubectl get pods --namespace default -l app=ncache -o wide

Restore the cache configuration and data using the export/import procedures for the supported version transition. Verify the cache members and data, then test client connectivity before resuming writes.

Keep writes stopped until you have completed and verified restoration.

Update Cache Settings

Helm
YAML

The chart configures caches through the caches list. Only caches[0], named defaultCache by default, is enabled during a default installation. Its Client Cache is also enabled by default with a size of 1024 MB and an isolation level of outproc.

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-helm --version 5.3.8 --namespace ncache --reuse-values --set 'caches[1].enabled=true'

Each setting uses the value supplied in the update, its previously applied value if omitted, or its default if no previous value exists. For example, the following command changes only the configured size of caches[1]:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8 --namespace ncache --reuse-values --set 'caches[1].size=2048'

Additional cache entries must be enabled in order and disabled in reverse order, starting with the highest enabled entry. Each entry from caches[2] onward requires the preceding entry to be enabled; caches[1] does not depend on caches[0]. Entries from caches[4] onward use the name cache<N> unless a name is supplied.

To enable caches[1] with a 512 MB in-process Client Cache, use the following command:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8 --namespace ncache --reuse-values --set 'caches[1].enabled=true' --set 'caches[1].clientCache.enabled=true' --set 'caches[1].clientCache.size=512' --set 'caches[1].clientCache.isolationLevel=inproc'

For an out-of-process Client Cache, set clientCache.isolationLevel to outproc and deploy the client containers separately, as described in Deploy an Out-of-Process Client Cache with Kubernetes. Enabling the Client Cache through Helm does not deploy these containers.

Cache configuration updates can be combined with other configuration updates, but image upgrades must be performed separately. The accepted values and defaults are described under cache values.

Warning

Disabling a cache deletes it. Changing an existing cache definition, including its enabled Client Cache configuration, recreates the cache 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.

Use NCache Management Center to create caches and change their configuration. The static server manifest does not contain the Helm caches list.

Open the management gateway, select Clustered Caches, and open the intended cache's configuration. For a new cache, follow Create a Cache. For an existing cache, open its details and apply the required configuration changes. Preserve required data before stopping or removing a cache, and verify its server members and status after the change.

To configure a Client Cache, follow Create a Client Cache and select the required isolation level. For an out-of-process Client Cache, also deploy its containers through OutProc Client Cache. Creating the Client Cache configuration does not deploy those containers.

Update Gateway Settings

Helm
YAML

The chart creates client and management LoadBalancer services. To access NCache Management Center through a public endpoint, you must configure gateway.mgmtCenterEndpoint. EKS deployments also require eks.publicSubnetIds; this additional setting is not required for other platforms. These values can be supplied during helm install or updated through helm upgrade. The gateway endpoints must be reachable from the networks used by client applications and administrators. Apply gateway changes separately from image upgrades.

On-Premises, AKS, GKE, and OpenShift

For public access to NCache Management Center, set gateway.mgmtCenterEndpoint to a public IPv4 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-helm --version 5.3.8 --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 public access to NCache Management Center on EKS, set gateway.mgmtCenterEndpoint to the management DNS hostname and set eks.publicSubnetIds to at least two public subnet IDs from different Availability Zones, separated by commas escaped as \, when passed through Helm. 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-helm --version 5.3.8 --namespace ncache --reuse-values --set-string gateway.mgmtCenterEndpoint="ncache.example.com" --set eks.publicSubnetIds="subnet-123\,subnet-456"

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.

Edit the client or management gateway manifest used during deployment. Retain its Service name, namespace, selector, and management session affinity unless the corresponding deployment settings are also being changed.

On-premises, AKS, GKE, and OpenShift: Configure the management address using the load balancer settings appropriate to the platform. A compatible static address can be requested in the Service manifest; otherwise, use the address allocated by the load balancer.
EKS: Keep the management gateway's internet-facing scheme and place it in public subnets. Specify comma-separated public subnet IDs in service.beta.kubernetes.io/aws-load-balancer-subnets, or remove that annotation and use tagged-subnet discovery. Keep the client gateway internal. Follow EKS YAML Deployment for both choices.

Apply only the edited gateway file. For example:

kubectl apply --namespace default -f EKS/mgmt-gatewayservice.yaml
kubectl get svc ncache-mgmt-gateway --namespace default

Replace the path with the file used for your platform. The Helm values gateway.mgmtCenterEndpoint and eks.publicSubnetIds are not fields in these YAML manifests.

If a gateway must be recreated to apply a subnet or load balancer change, plan an interruption to management access. Delete only that Service and apply its manifest again:

kubectl delete svc ncache-mgmt-gateway --namespace default
kubectl apply --namespace default -f EKS/mgmt-gatewayservice.yaml

The assigned endpoint can change after recreation. Check the Service, update any DNS record that points to it, and verify management access and client connectivity as applicable. Do not recreate an existing gateway unless the change requires it.

Update TLS Settings

Helm
YAML

TLS settings can be updated through helm upgrade, separately from an image upgrade. Before applying a change, ensure that client applications support the selected TLS configuration and trust the server certificate.

The tls.protocolVersion value applies to standard and mutual TLS. It accepts tls12, tls13, or auto and defaults to tls12. Unsupported values are rejected during installation and upgrade.

When changing an existing TLS deployment from tls12 to tls13, first select auto and verify that the update completes. Then select tls13 in a second operation. Use the same intermediate auto setting when changing from tls13 to tls12:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8 --namespace ncache --reuse-values --set tls.protocolVersion=auto

Verify the operation using Verify an Update, then apply the target protocol:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8 --namespace ncache --reuse-values --set tls.protocolVersion=tls13

To enable mutual TLS, first create the certificate Secret in the deployment namespace, as described in Create TLS Secret.

Save the following settings in ncache-mutual-tls-values.yaml. These settings enable mutual TLS and clear custom-certificate values retained from an earlier configuration, because mutual TLS obtains its certificates and passwords from the existing Secret:

tls:
  enabled: true
  mutualEnabled: true
  secretName: ncache-tls-secret
  customCertificate: ""
  customCertificatePassword: ""
  customClientCertificate: ""
  customClientCertificatePassword: ""

Note

TLS certificates are mounted in /usr/local/share/ca-certificates inside the NCache containers. Ensure that the server and client certificate paths refer to valid certificate files. For the mutual TLS configuration shown above, the certificates are supplied through the Secret; leave tls.customCertificate and tls.customClientCertificate empty.

Replace ncache-tls-secret if your Secret has a different name, then apply the update:

helm upgrade ncache oci://registry-1.docker.io/alachisoft/ncache-helm --version 5.3.8 --namespace ncache --reuse-values -f ncache-mutual-tls-values.yaml

For mutual TLS, the chart automatically supplies the client certificate and its password, when required, to the NCache commands it runs. These credentials are read from the Secret identified by tls.secretName, so no additional command parameters are required. Configure client applications separately, as described in Configure TLS for Client Deployment.

Warning

Changes to TLS mode, protocol, or Secret name restart caches without replacing server pods. Adding or removing a custom server certificate also replaces server pods. These operations can interrupt client connections. Plan the update accordingly, and verify cache availability and client connectivity after it completes.

Prepare the ncache-tls-secret Secret in the default namespace and update the TLS environment variables in ncache.yaml, following TLS with YAML Files. Standard TLS uses NC_ENABLE_TLS="true"; mutual TLS also uses NC_MUTUAL_TLS="true". Retain the certificate paths and Secret password references in the supplied manifest.

Before applying the change to running servers, follow Prepare for YAML Pod Replacements. Apply the manifest and follow Replace YAML Server Pods:

kubectl apply --namespace default -f ncache.yaml

Coordinate the change with client applications and any out-of-process Client Cache. Certificate or TLS-mode changes can interrupt communication; plan downtime when the old and new settings cannot operate together. Afterward, verify every cache and test a client connection using the selected TLS configuration.

Replace YAML Server Pods

Use this procedure after applying a changed pod template with the OnDelete strategy. Back up required data first and verify that the remaining servers can keep the caches available during each replacement. If they cannot, schedule downtime.

For the default two-server deployment, replace ncache-1 first:

kubectl delete pod ncache-1 --namespace default
kubectl get pods --namespace default -l app=ncache -o wide

Wait for the replacement pod to start. In NCache Management Center, verify that it has joined every intended cache, that synchronization has completed, and that the caches are running. Test an application connection before continuing.

Replace ncache-0 only after these checks pass:

kubectl delete pod ncache-0 --namespace default
kubectl get pods --namespace default -l app=ncache -o wide

Repeat the same cache and client checks. For deployments with more servers, proceed one at a time in descending pod-number order. Stop if a replacement fails; a pod being reported as running does not establish that its caches have synchronized.

Verify an Update

Check the deployment after every operation and investigate failed pods or jobs before making another change.

Helm
YAML

kubectl get pods,jobs --namespace ncache
kubectl get svc --namespace ncache

A successful Helm command confirms that the operation was accepted; wait for the configuration job to finish before starting another update. Find the current release revision and use it in the job name:

helm history ncache --namespace ncache
kubectl logs --namespace ncache -f "job/ncache-lifecycle-<revision>" --pod-running-timeout=2m

Replace <revision> with the numeric revision shown by Helm. Successful jobs are removed after completion. If the job is no longer available, check the recorded result:

kubectl get configmap ncache-store --namespace ncache -o jsonpath='{.data.lifecycleLifecycleResult}'

Confirm that the result corresponds to the requested operation and indicates success. Inspect failed job logs before proceeding.

kubectl get pods --namespace default -l app=ncache -o wide
kubectl get svc --namespace default

Inspect the events and logs of any pod that fails to start. With OnDelete, verify that every intended pod has been replaced before considering a pod-template update complete.

In NCache Management Center, verify the expected server membership, cache status, and licensing. Confirm that management and client endpoints remain reachable, then add and retrieve an item through a client application. For TLS changes, use the corresponding client TLS settings when performing this check.

Manage an Existing Deployment

Prepare for YAML Pod Replacements

Scale the Cluster

Extend the Evaluation Period

Activate a Production License

Deactivate a Production License

Perform a Rolling Upgrade

Perform an Offline Upgrade

Update Cache Settings

Warning

Update Gateway Settings

On-Premises, AKS, GKE, and OpenShift

EKS

Update TLS Settings

Note

Warning

Replace YAML Server Pods

Verify an Update

See Also

Contact Us