Deploy TLS With NCache Kubernetes

NCache supports TLS encryption for communication between client applications and cache servers in Kubernetes. TLS is configured through the Helm chart during installation, with mutual TLS available when client certificate authentication is required.

This page explains how to prepare certificates, configure the Helm TLS settings, and verify secure client connections. These settings must be selected before installation because the chart does not support changing them through a subsequent Helm upgrade.

Prerequisites

Before enabling TLS, make sure that:

You have a Kubernetes cluster ready for a new NCache Helm installation.
kubectl and Helm are configured to access the cluster.
You have a deployment key and have selected the release name, namespace, and platform.
You have inspected the chart's TLS settings.
If using custom certificates, you have the server certificate and any required trust chain and credentials in the format accepted by the chart.
If using mutual TLS with custom certificates, you have both custom server and client certificates.
The NCache container image is accessible from the Kubernetes cluster.

Step 1: Create TLS Secret

For TLS without mutual authentication, use the NCache-provided certificate; no custom Secret is required. Custom certificates are supported only with mutual TLS.

For mutual TLS, prepare a server PEM bundle containing its private key, certificate, and intermediate certificates, and a client PEM certificate. Supply both files with --set-file during installation, as shown in Step 5, or create a Secret in the installation namespace:

kubectl create namespace ncache
kubectl create secret generic ncache-tls-secret --namespace ncache --from-file=server-certificate=server.pem --from-file=client-certificate=client.pem

If the namespace already exists, only the Secret creation command is required. When a private key is encrypted, include its password in the corresponding server-certificate-password or client-certificate-password entry in the Secret.

Step 2: Mount TLS Secret in NCache Pods

The chart mounts the certificate Secret automatically. When using an existing Secret, set tls.secretName to its name; the default is ncache-tls-secret. When supplying both certificate files, the chart creates the certificate Secret.

Inspect the chart defaults using:

helm show values oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0

Step 3: Configure TLS Settings

Configure the following Helm values instead of editing TLS environment variables in the deployment manifest:

Helm Value	Default	Description
`tls.enabled`	`false`	Enables TLS with the NCache-provided certificate when mutual TLS is disabled.
`tls.mutualEnabled`	`false`	Enables mutual TLS; requires `tls.enabled=true` and both certificate files or an existing certificate Secret.
`tls.customCertificate`	Empty	Server PEM bundle for mutual TLS, supplied with `--set-file`.
`tls.customCertificatePassword`	Empty	Password for the encrypted server private key, when applicable.
`tls.customClientCertificate`	Empty	Client PEM certificate for mutual TLS, supplied with `--set-file`.
`tls.customClientCertificatePassword`	Empty	Password for the encrypted client private key, when applicable.
`tls.secretName`	`ncache-tls-secret`	Existing Secret used for mutual TLS when certificate files are not supplied.

For example, save the following values in ncache-tls-values.yaml to enable TLS with the NCache-provided certificate:

tls:
  enabled: true
  mutualEnabled: false

TLS settings, including the certificate values, must be configured during installation and cannot be updated through helm upgrade.

Step 4: Configure TLS for Client Deployment

Configure the client application to use TLS consistently with the NCache servers and to trust the server certificate. For a .NET client, use ConnectionOptions with CacheManager.GetCache. Set Servers to the client gateway endpoint and mark its ServerInfo entry with isLoadBalancer: true, as shown in Configure the External Client.

For mutual TLS, specify the client certificate path through TLSCertPath, using PEM format or, for .NET Framework applications, PFX format. If the certificate's private key is encrypted, provide its password through TLSCertPassword using your application's secure configuration.

The cache server supplies client connection tuning, load balancing, logging, and client cache settings on connection. Client certificate credentials and application-specific connection settings belong in ConnectionOptions.

Step 5: Install NCache with TLS

The following examples install NCache with the selected TLS configuration. Replace <platform> with on-prem, AKS, EKS, GKE, or OpenShift, supply your deployment key, and include any additional values required by your platform deployment guide.

For TLS with the NCache-provided certificate, install using the values file from Step 3:

helm install ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --create-namespace --set-string deployment.key="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --set-string deployment.platform="<platform>" -f ncache-tls-values.yaml

To install NCache with mutual TLS using certificate files, use the following command:

helm install ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --create-namespace --set-string deployment.key="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --set-string deployment.platform="<platform>" --set tls.enabled=true --set tls.mutualEnabled=true --set-file tls.customCertificate=server.pem --set-file tls.customClientCertificate=client.pem

If a private key is encrypted, supply its corresponding password value from Step 3 through a protected values file.

To install NCache with mutual TLS using the existing Secret from Step 1, use the following command:

helm install ncache oci://registry-1.docker.io/alachisoft/ncache --version 1.0.0 --namespace ncache --create-namespace --set-string deployment.key="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --set-string deployment.platform="<platform>" --set tls.enabled=true --set tls.mutualEnabled=true --set-string tls.secretName="ncache-tls-secret"

Apply client-side configuration through the client application's own deployment process.

Step 6: Verify the Server Pods and Caches

The chart applies TLS as part of installation; a separate manual service restart is not required for this procedure. Check that the NCache server pods are ready and investigate failed configuration jobs:

kubectl get pods,jobs -n ncache

Verify that the configured caches are running in NCache Management Center before testing client connectivity.

Step 7: Verify TLS Deployment

Connect to a deployed cache from a client configured for TLS. For mutual TLS, also verify that the configured client certificate is accepted. Use the NCache Management Center to inspect cache status and logs for connection or certificate errors.

If further diagnosis is needed, inspect the pod logs using the actual pod name:

kubectl logs "<pod-name>" -n ncache

Important Considerations

TLS and mutual TLS are disabled by default.
NCache uses its own certificate for TLS without mutual authentication. Mutual TLS requires customer certificates, supplied through files or an existing Secret.
Supply custom certificates as PEM files with --set-file, or use an existing Secret with the required keys.
Mutual TLS requires both server and client certificates. Custom certificates are not supported for non-mutual TLS.
TLS settings and certificates cannot be changed through helm upgrade in chart 1.0.0.
Client applications must use TLS settings consistent with the server deployment.
This chart workflow is single-site only and does not define bridge TLS settings.

Troubleshooting

Pod Fails During Startup

Incorrect certificate inputs or inaccessible certificate resources can prevent startup.

Workaround: Check the chart's certificate requirements and inspect the pod events using the actual pod name.

kubectl describe pod "<pod-name>" -n ncache

Certificate is Not Found

A custom certificate may be unavailable if its value does not use the chart's accepted input format or references an unavailable resource.

Workaround: Verify tls.customCertificate and, for mutual TLS, tls.customClientCertificate against the selected chart's instructions. If a Secret reference is required, confirm that the referenced Secret is available in the appropriate namespace.

Client Cannot Connect to Cache

Client applications may fail to connect when client and server TLS settings, certificate trust, or mutual TLS credentials are inconsistent.

Workaround: Verify the client TLS configuration, trust chain, and certificate validity. For mutual TLS with custom certificates, verify that both server and client certificates have been supplied correctly.

Management Center is Not Accessible

The NCache Management Center may be unavailable if the gateway endpoint is unreachable or the NCache pods are not ready.

Workaround: Check the gateway services and pods. Use the Management Center endpoint and port documented for the installed chart. Management Center uses HTTP 9801 and HTTPS 9802; the portal uses HTTPS 9998 and HTTP 9999. HTTPS load balancers forward to HTTP 9801 for Management Center and HTTP 9999 for the portal, with sticky sessions. See Firewalls and Ports.

kubectl get svc -n ncache
kubectl get pods -n ncache