Deploy TLS With NCache Kubernetes

NCache supports TLS encryption for communication between client applications and cache servers in Kubernetes. Configure TLS using the Helm settings or the environment variables and certificate Secret for a YAML deployment. Mutual TLS is available when client certificate authentication is required.

This page explains how to prepare certificates, configure TLS for the selected deployment method, and verify secure client connections. To change TLS settings on an existing deployment, follow Update TLS Settings.

Prerequisites

Before enabling TLS, make sure that:

You have a Kubernetes cluster ready for an NCache Enterprise deployment or an existing Enterprise deployment to update.
kubectl is configured to access the cluster. Helm 3.14 or later is also installed and configured when using the Helm procedure.
You have selected the deployment method and platform, and have a deployment key for a new installation. The examples use the ncache namespace for Helm and default for YAML.
You have inspected the TLS settings for the selected deployment method.
If using custom certificates, you have the server certificate and any required trust chain and credentials in PEM format.
You have the certificates required by the selected procedure and create any required Secret in the deployment namespace before enabling TLS.
The NCache container image is accessible from the Kubernetes cluster.

Deploy Using Helm

Step 1: Create TLS Secret

For TLS without mutual authentication, use the NCache-provided certificate or supply a custom server PEM bundle through tls.customCertificate, as shown in Step 5. The custom bundle must contain the private key, server certificate, intermediate certificates, and issuing CA certificate, in that order. No manually created certificate Secret is required for these configurations. When a custom certificate is supplied, the chart creates the Secret automatically.

For mutual TLS, prepare a server PEM bundle containing its private key, certificate, and certificate chain, and a client PEM bundle containing its certificate and private key. For certificates signed by your own CA, also provide the issuing CA certificate as a separate file. Create a Secret in the deployment namespace before enabling mutual TLS:

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 --from-file=issuer=ca.crt --from-literal=server-certificate-password='server certificate password' --from-literal=client-certificate-password='client certificate password'

Replace server.pem, client.pem, and ca.crt with your certificate file paths. If the namespace already exists, only the Secret creation command is required. The issuer entry supplies the CA certificate used to establish trust; including the CA certificate only inside the server PEM bundle is not sufficient.

Replace server certificate password and client certificate password with the passwords for the respective private keys. Omit the corresponding --from-literal argument if a private key is not encrypted. An encrypted server private key must use PKCS#8 format, identified by BEGIN ENCRYPTED PRIVATE KEY.

Mutual TLS uses certificates from this Secret. Do not supply tls.customCertificate, tls.customClientCertificate, or their password values when enabling mutual TLS.

Step 2: Mount TLS Secret in NCache Pods

The chart mounts the certificate Secret automatically. For mutual TLS, set tls.secretName to the existing Secret's name; the default is ncache-tls-secret.

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. This also applies when mutual TLS was enabled outside Helm, such as through NCache Management Center, provided that the required certificate Secret is available. Client applications still require the certificate configuration described in Step 4.

Inspect the chart defaults using:

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

Step 3: Configure TLS Settings

For standard TLS with the NCache-provided certificate, install NCache using the following command. If you require a custom server certificate or mutual TLS, review the settings below and use the corresponding command in Step 5 instead:

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

Replace the deployment-key placeholder with your key and <platform> with on-prem, AKS, EKS, GKE, or OpenShift. Include any additional values required by your platform deployment guide.

The command enables standard TLS with TLS 1.2 without a separate values file. After installation, configure the client in Step 4, then verify the deployment in Steps 6 and 7.

The following table describes the available TLS settings and their defaults:

Helm Value	Default	Description
`tls.enabled`	`false`	Enables TLS. Without mutual authentication, NCache uses its own certificate unless a custom server certificate is supplied.
`tls.mutualEnabled`	`false`	Enables mutual TLS; requires `tls.enabled=true` and an existing Secret containing the server and client certificates.
`tls.customCertificate`	Empty	Custom server PEM bundle for TLS without mutual authentication, supplied with `--set-file`.
`tls.customCertificatePassword`	Empty	Password for the encrypted private key in `tls.customCertificate`, when applicable.
`tls.secretName`	`ncache-tls-secret`	Existing Secret containing the mutual TLS certificates and any required private-key passwords.
`tls.protocolVersion`	`tls12`	Specifies the protocol version for standard and mutual TLS. Accepted values are `tls12`, `tls13`, and `auto`. Unsupported values are rejected during installation and upgrade.

TLS settings can also be changed through helm upgrade. Follow Update TLS Settings to apply changes to an existing deployment.

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 mutual TLS in a .NET application, supply the client certificate credentials through ConnectionOptions when calling CacheManager.GetCache.

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.

Deploy the out-of-process Client Cache using the separate ncache-client-outproc.yaml manifest, as described in Deploy an Out-of-Process Client Cache with Kubernetes. If standard or mutual TLS is enabled on the cache servers, apply the corresponding TLS settings to the out-of-process Client Cache as well. The server deployment does not configure TLS for these separate client containers.

Step 5: Install NCache with TLS

Use this step only when installing with a custom server certificate or mutual TLS. Run one of the following commands for the required configuration. Replace the deployment-key placeholder and <platform> as described in Step 3, and include any additional values required by your platform deployment guide. If you installed with the NCache-provided certificate in Step 3, continue with Step 6.

To use a custom server certificate without mutual authentication, supply the server PEM bundle through tls.customCertificate:

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

Replace server.pem with your server PEM bundle. If its private key is encrypted, add --set-string tls.customCertificatePassword="<server-certificate-password>" to the command and replace the password placeholder with the private-key password.

To install NCache with mutual TLS, use the existing Secret from Step 1. Replace ncache-tls-secret if you created it with a different name:

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

The protocol version defaults to tls12. To use TLS 1.3, add --set tls.protocolVersion=tls13 to the selected installation command before running it.

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 rollout status statefulset/ncache --namespace ncache
kubectl get pods,jobs --namespace ncache

Follow Verify an Update to confirm the configuration job completed, then 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, then add an item and retrieve it to verify the connection. 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.
For TLS without mutual authentication, NCache uses its own certificate unless a custom server PEM bundle is supplied through tls.customCertificate.
Mutual TLS requires an existing Secret containing both server and client certificates, together with passwords for encrypted private keys. For certificates signed by your own CA, include the issuing CA certificate in the separate issuer entry.
The chart automatically supplies certificate credentials to the NCache commands it runs. Client applications require their own certificate configuration.
tls.protocolVersion defaults to tls12 and accepts tls12, tls13, or auto.
TLS settings can be changed through helm upgrade. Applying TLS changes can restart caches, so plan for an interruption to client operations.
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: For TLS without mutual authentication, verify the PEM bundle supplied through tls.customCertificate. For mutual TLS, confirm that the Secret identified by tls.secretName exists in the deployment namespace and contains server-certificate, client-certificate, and the corresponding password entries for encrypted private keys.

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, verify that both server and client certificates have been supplied correctly. If the certificates are signed by your own CA, confirm that the TLS Secret contains the CA certificate in its issuer entry.

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

Deploy Using YAML Files

For an Enterprise YAML deployment, prepare the certificate Secret in the default namespace and configure the NCache container's TLS environment variables before applying ncache.yaml. Use this procedure with the platform deployment guide.

Step 1: Prepare the Certificate Secret

Prepare a server PEM bundle containing the private key, server certificate, intermediate certificates, and issuing CA certificate, in that order. Prepare a client PEM bundle containing its private key, certificate, and any intermediate certificates, together with a separate issuing CA certificate file.

Create the Secret using the entry names referenced by the supplied manifest:

kubectl create secret generic ncache-tls-secret --namespace default --from-file=server-certificate=server.pem --from-file=client-certificate=client.pem --from-file=issuer=ca.crt --from-literal=server-certificate-password='server certificate password' --from-literal=client-certificate-password='client certificate password'

Replace the sample file paths with your certificate files and replace server certificate password and client certificate password with the passwords for the respective private keys. Omit the corresponding --from-literal argument if a private key is not encrypted.

Step 2: Configure the Server Manifest

In ncache.yaml, set NC_ENABLE_TLS to "true". For standard TLS, retain NC_MUTUAL_TLS as "false":

- name: NC_ENABLE_TLS
  value: "true"
- name: NC_MUTUAL_TLS
  value: "false"

For mutual TLS, set both values to "true":

- name: NC_ENABLE_TLS
  value: "true"
- name: NC_MUTUAL_TLS
  value: "true"

Update the existing entries rather than adding duplicate environment variables. Retain the Secret volume, its mount, and the certificate paths already present in the file:

NC_TLS_CUSTOM_CERTIFICATE points to /usr/local/share/ca-certificates/server-certificate.
NC_TLS_CLIENT_CERTIFICATE points to /usr/local/share/ca-certificates/client-certificate.
NC_TLS_CUSTOM_PASSWORD reads server-certificate-password from ncache-tls-secret.
NC_TLS_CLIENT_PASSWORD reads client-certificate-password from the same Secret.

Set the TLS environment variables as well as creating the Secret, and retain the certificate paths in the server manifest.

Step 3: Apply and Verify the Deployment

For a new deployment, apply the prepared server manifest and the platform's gateway files as described in its deployment guide. To update existing servers, follow the YAML procedure in Update TLS Settings, including the controlled pod replacements.

Check the server pods and gateway Services:

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

Verify that all intended caches are running in NCache Management Center. If a pod fails to start, inspect its events and logs:

kubectl describe pod "<pod-name>" --namespace default
kubectl logs "<pod-name>" --namespace default

Step 4: Configure and Verify Clients

Configure the client application to trust the server certificate. For mutual TLS, supply the client certificate through ConnectionOptions, following Configure TLS for Client Deployment.

If an out-of-process Client Cache is used, apply the corresponding standard or mutual TLS settings to that separate client deployment as well. The server manifest does not configure its TLS settings.

Connect to the intended cache, add an item, and retrieve it. For mutual TLS, confirm that the configured client certificate is accepted. Investigate certificate and connection errors before allowing application traffic.