Kubernetes Self-Deployment

NCache Kubernetes self-deployment uses a unified Helm chart configuration for a single-site NCache cluster on Linux. The chart supports on-premises Kubernetes, Azure Kubernetes Service (AKS), Amazon Elastic Kubernetes Service (EKS), Google Kubernetes Engine (GKE), and OpenShift, providing a common configuration across these environments.

This section describes the chart settings, gateways, licensing, TLS, and upgrade behavior. The deployment guides explain how to install NCache in each environment, while the management guide covers changes to an existing deployment.

Helm Chart Files and Templates

The NCache Helm chart is installed from oci://registry-1.docker.io/alachisoft/ncache. The same chart is used across the supported Kubernetes environments, with deployment values identifying the target platform.

Note

Visit the NCache GitHub repository for NCache source code and resources.

The values.yaml File

The values.yaml file defines the deployment settings and defaults. Use helm show values for the selected chart version to inspect them, and override the required settings through Helm. The templates also accept optional values listed below, such as tls.secretName, image.pullSecretName, gateway.mgmtCenterEndpoint, and eks.publicSubnetIds, even though they are not listed in the default values file.

Important values include:

  • deployment.key: Specifies the deployment key used to register an evaluation when each server starts. After an evaluation extension has been approved, follow Extend the Evaluation Period to update the key if necessary and restart the servers to complete registration.
  • deployment.name: Specifies the name of the NCache deployment, which defaults to ncache.
  • deployment.servers: Specifies the number of NCache server pods, with a default of 2. You can increase the server count after installation using helm upgrade.
  • deployment.podAntiAffinity: Determines whether NCache server pods must run on separate worker nodes. The default value, true, requires a separate node for each server; setting it to false allows pods to share a node while still preferring separate nodes.
  • deployment.platform: Identifies the Kubernetes environment in which NCache will be deployed. It defaults to on-prem and accepts on-prem, AKS, EKS, GKE, or OpenShift.
  • image.repository: Specifies the repository from which the NCache container image is pulled. The default repository is alachisoft/ncache.
  • image.tag: Specifies the container image tag and defaults to latest. This tag selects the NCache image independently of the Helm chart version.
  • image.pullPolicy: Controls when Kubernetes pulls the container image and defaults to Always. If the repository requires credentials, use image.pullSecretName to identify an existing image pull Secret.
  • image.upgradeStabilityWaitMinutes: Specifies the number of minutes used for each server when calculating the rolling upgrade timeout. The default is 10; the total timeout also includes the configured delay between servers.
  • image.upgrade: Determines whether an image upgrade is performed in rolling or offline mode. The default is rolling.
  • image.delayMinutes: Specifies how long a pod must remain ready before the next pod is upgraded during a rolling upgrade. The default delay is 2 minutes.
  • license.licenseKey: Specifies the license key for a licensed deployment. It is empty by default and can be supplied during installation or in a subsequent configuration update.
  • license.envName: Specifies the environment associated with the NCache license. It defaults to Eval and must match the environment for which the license was issued.
  • license.action: Specifies whether the license is activated or deactivated on the NCache servers. It accepts activate or deactivate and defaults to activate.
  • tls.enabled: Determines whether TLS is enabled and defaults to false. When TLS is enabled without mutual authentication, NCache uses its own certificate; custom certificates require mutual TLS.
  • tls.customCertificate: Provides the server PEM bundle used for mutual TLS. This value is empty by default and is supplied from a file through --set-file.
  • tls.mutualEnabled: Determines whether mutual TLS authentication is enabled and defaults to false.
  • tls.customClientCertificate: Provides the client PEM certificate used for mutual TLS. This value is empty by default and is supplied through --set-file together with the custom server certificate.
  • tls.customCertificatePassword and tls.customClientCertificatePassword: Provide the passwords for encrypted server and client private keys, respectively. Both values are empty by default and are required only when the corresponding key is encrypted.
  • tls.secretName: Identifies the existing Secret containing the mutual TLS certificates when certificate files are not supplied. The default Secret name is ncache-tls-secret.
  • gateway.mgmtCenterEndpoint: Specifies an optional IPv4 address or DNS name for the management gateway. For EKS deployments, this value must be a DNS name.
  • eks.publicSubnetIds: Specifies the public subnet IDs used by the EKS management gateway, separated by +. This value is required when a management hostname is supplied for EKS.
  • gateway.clientPort: Specifies the port used for client connections and defaults to 9800.
  • gateway.mgmtPorts: Specifies the management gateway port range, which defaults to 9801-9802. The management gateway uses session affinity.
  • gateway.ports: Specifies the additional ports exposed through the client gateway and defaults to 9803-9997.
  • gateway.portalPorts: Specifies the portal port range, which defaults to 9998-9999. These ports are exposed through the management gateway with session affinity.
  • caches[0]: Configures defaultCache as a Distributed Cache store, which is enabled by default.
  • caches[1]: Configures sessionCache as a Distributed Cache store, which is disabled by default.
  • caches[2]: Configures pubsubCache as a Pub/Sub store, which is disabled by default.
  • caches[3]: Configures dataCache as a Distributed Cache store, which is disabled by default.

The deployment name, platform, pod anti-affinity, and TLS settings must be configured during installation. After deployment, changes to the container image are treated as upgrades, while increases to the server count and changes to licensing, caches, gateways, and the deployment key are treated as configuration updates. Both use helm upgrade, with one configuration group changed per operation.

Within the deployment group, you can updatedeployment.key and increase deployment.servers; changes to the other deployment settings require redeployment. NCache configuration changes that require an NCache service restart are not supported in this deployment. See Manage Deployment for the supported procedures.

The configuration job establishes the default cache in caches[0]. When names are not supplied for the first four entries, the chart assigns defaultCache, sessionCache, pubsubCache, and dataCache, respectively. Only the default cache is enabled automatically. During an update, an omitted name retains its previously configured value.

Each of the four cache entries accepts the following values:

  • enabled: Determines whether the cache is created or removed. Only caches[0] is enabled by default; setting an existing entry to false removes its cache.
  • name: Specifies the cache name. If no name is supplied, the chart uses the default for that entry, as listed above.
  • storeType: Determines whether the entry creates a Distributed Cache or a Pub/Sub store. The defaults for each entry are listed above.
  • topology: Specifies the cache topology and accepts Partition-Replica, Partitioned, or Replicated. The default is Partition-Replica.
  • asyncReplica: Determines whether replication is asynchronous and defaults to true. This value must remain true for a Pub/Sub store.
  • size: Specifies the cache size in MB as a positive whole number. The default size is 1024 MB.
  • compression: Determines whether compression is enabled and defaults to false.
  • threshold: Specifies the compression threshold in KB as a positive whole number. It defaults to 100 and is used when compression is enabled.
  • eviction: Specifies the eviction policy and accepts LRU, LFU, or Priority. The default is LRU.
  • evictionRatio: Specifies the eviction ratio used when removing cached items to free space.
  • encryptionProvider: Specifies the encryption provider and accepts None, AES-128, AES-192, or AES-256. Encryption is disabled by default through the value None.
  • encryptionKey: Provides the key for the selected encryption provider. The key must contain exactly 16, 24, or 32 characters for AES-128, AES-192, or AES-256, respectively, and must be empty when the provider is None.
Warning

Disabling a cache removes it without saving its data. Changing an existing cache definition recreates that cache without preserving its data. Preserve required data before applying either change.

Cache names must start with a letter, contain only letters, digits, underscores, or hyphens, and be at most 64 characters. Enabled cache names must be unique. Enable caches[1] before caches[2], and caches[2] before caches[3].

Provider-specific values include:

  • On-premises: Use deployment.platform=on-prem, the default. gateway.mgmtCenterEndpoint can request an IPv4 address from the configured load balancer pool.
  • AKS: Use deployment.platform=AKS. gateway.mgmtCenterEndpoint can request a reserved management IPv4 address available to the cluster.
  • EKS: Use deployment.platform=EKS. For a management hostname, set gateway.mgmtCenterEndpoint and eks.publicSubnetIds with at least two public subnet IDs joined with +. Configure DNS to resolve to the management load balancer.
  • GKE: Use deployment.platform=GKE. gateway.mgmtCenterEndpoint can request a management IPv4 address supported by the cluster's load balancer configuration.
  • OpenShift: Use deployment.platform=OpenShift. gateway.mgmtCenterEndpoint can request a management IPv4 address supported by the cluster infrastructure.

Cache authentication and authorization are not currently supported in this deployment. TLS and mutual TLS can be configured during installation, as described in TLS Deployment.

The ncache.yaml File

The ncache.yaml file defines the NCache server deployment and its supporting resources. The Helm values determine the server configuration, including the number of servers, licensing, and TLS settings.

The deployment is controlled through the following settings:

  • Server count: deployment.servers defaults to 2.You can increase this value after installation using helm upgrade to deploy additional NCache server pods.
  • Registration: Supply the required deployment.key during installation, including when supplying a license key.
  • Cache configuration: Use the caches values for deployment-time cache configuration and the NCache Management Center for ongoing cache management and monitoring.
  • Rolling upgrade: image.upgrade=rolling upgrades one pod at a time, starting with the highest-numbered pod, with image.delayMinutes=2 by default. If the upgrade fails, the chart attempts to restore the previous image. Verify readiness and cache availability after the operation. A failed upgrade also requires restoring the Helm release revision; follow Perform a Rolling Upgrade.
  • Offline upgrade: image.upgrade=offline backs up configuration and data, stops all pods, upgrades them, and restores configuration and data. Plan for downtime. Stop writes before taking independent configuration and data backups, and keep writes stopped until restoration has been verified.

Configure Pod Anti-Affinity

Pod anti-affinity controls the distribution of NCache server pods across worker nodes. The unified chart uses the Boolean deployment.podAntiAffinity setting.

The supported values are:

  • false: Prefers separate worker nodes but permits shared-node placement.
  • true: The default; requires a separate schedulable worker node for every NCache server.

The cachejob.yaml File

The cachejob.yaml file defines the configuration job that applies cache settings, licensing operations, and image upgrades. Configure these operations through Helm values. After installation or an upgrade, check job status and verify the resulting caches and licensing in NCache Management Center; the Helm command returning successfully does not by itself confirm that this work has completed.

The ncache-lifecycle.sh File

The files/ncache-lifecycle.sh script carries out the configuration job's lifecycle operations. Use the procedures in Manage Deployment for supported changes and recovery steps.

The gatewayservice.yaml File

The gatewayservice.yaml file defines both the management and client gateway services.

Management Gateway

The management gateway provides access to NCache management services through any matching server pod, with ClientIP session affinity. Configure gateway ports through the unified chart values.

  • Management Ports: gateway.mgmtPorts defaults to 9801-9802 and requires session affinity.
  • Portal Ports: gateway.portalPorts defaults to 9998-9999 and requires session affinity.
  • Management Center: The default HTTP port is 9801 and the default HTTPS port is 9802. When an HTTPS load balancer fronts the Management Center, forward requests to HTTP port 9801 and enable sticky sessions.
  • Cloud Portal: The default HTTPS port is 9998 and the default HTTP port is 9999. When an HTTPS load balancer fronts the portal, forward requests to HTTP port 9999 and enable sticky sessions.

Client Gateway

The client gateway provides connectivity for applications outside the Kubernetes cluster.

  • Client Port: gateway.clientPort defaults to 9800.
  • Gateway Port Range: gateway.ports defaults to 9803-9997.
  • Network Access: Follow Firewalls and Ports for the port assignments. Client/server traffic uses 9800; CacheHost processes use 9831-9880, cache cluster communication uses 9881-9980, and RESP servers use 9981-9989. For firewall or blind port-forwarding configurations, allow the documented TCP range 9800-9999, with access limited to the networks that need it.

Load Balancer Integration

The Kubernetes environment must provide the networking needed to expose NCache gateways. Inspect the selected chart's gateway services and confirm their reachability from the intended clients and administrators.

  • On-premises or bare-metal Kubernetes: Configure MetalLB or another implementation of Kubernetes LoadBalancer services before deployment. The chart allows its two gateways to share a MetalLB address.
  • AKS: The chart requests external Azure load balancers for both gateways. Provide the required permissions and address allocation.
  • EKS: The client gateway uses an internal AWS Network Load Balancer; the management gateway uses an internet-facing Network Load Balancer. Clients need access to the internal network. The default client gateway exposes 196 TCP ports, so ensure sufficient listener capacity or configure a smaller range covering every required NCache port.
  • GKE: The chart creates generic LoadBalancer services. Address allocation and exposure follow the cluster's load balancer configuration.
  • OpenShift: The chart creates generic LoadBalancer services. Cloud or bare-metal infrastructure must supply address allocation and TCP connectivity.

The Chart.yaml File

The Chart.yaml file identifies the Helm chart and its version. The chart version selects the deployment package, while the container image version determines which NCache image is deployed. The target environment is selected through the deployment values.

The _helpers.tpl File

The _helpers.tpl file contains shared definitions used by the chart templates. Deployment settings are configured through Helm values, so this file does not need to be modified during installation or routine management.

NCache Kubernetes Licensing

An evaluation deployment requires a deployment.key, which NCache registers when each server starts. If support approves an extension, the servers must be restarted to register the extended evaluation, even when the key remains unchanged. The Extend the Evaluation Period procedure explains how to update the key when necessary and complete registration.

For a licensed deployment, provide license.licenseKey during installation or through a subsequent helm upgrade command, together with the environment associated with the license in license.envName. The environment defaults to Eval, so it must be changed to match the license when applicable. The license.action setting controls whether the license is activated or deactivated on all server pods, using activate or deactivate, respectively. For details about the available licenses, see NCache licenses.

In This Section

On-Premises Deployment
Step-by-step instructions for deploying NCache in an on-premises Kubernetes environment.

AKS Deployment
Step-by-step instructions for deploying NCache with Azure Kubernetes Service.

EKS Deployment
Step-by-step instructions for deploying NCache with Amazon Elastic Kubernetes Service.

GKE Deployment
Step-by-step instructions for deploying NCache with Google Kubernetes Engine.

OpenShift Deployment
Step-by-step instructions for deploying NCache with OpenShift.

OutProc Client Cache
Deploy client containers separately from Helm and configure application pods to use a local Client Cache.

Manage Deployment
Manage licensing, cache settings, gateways, and rolling or offline upgrades with Helm.

TLS Deployment
Configure TLS and mutual TLS through the unified Helm chart.