• Facebook
  • Twitter
  • Youtube
  • LinkedIn
  • RSS
  • Docs
  • Comparisons
  • Blogs
  • Try NCache
  • Contact Us
Try NCache
Show / Hide Table of Contents

Deploy NCache with Amazon Elastic Kubernetes Service

Amazon Elastic Kubernetes Service (EKS) provides a managed Kubernetes environment in which NCache server containers run on Linux worker nodes. You can deploy NCache using the Helm chart or YAML files to create the servers and gateway services for cache connections and NCache Management Center.

This page explains how to connect to an existing EKS cluster, install NCache, and verify the deployment. The examples use the default two-server configuration and describe the network access required for the internal client gateway and public management gateway.

Prerequisites

Before you begin, make sure that:

  • You have access to an existing EKS cluster, or permission to create one as described below.
  • AWS CLI is installed and configured.
  • kubectl is installed.
  • If deploying with Helm, Helm 3.14 or later is installed and configured.
  • You have permission to deploy namespace resources and cluster-wide RBAC resources.
  • The NCache container image is accessible, and you have the Enterprise YAML files or access to the selected OCI chart version.
  • You have the required deployment key and, for license activation, the appropriate license key and environment name.
  • The cluster can provide AWS Network Load Balancers for the gateway services. The Helm client gateway exposes 196 TCP ports by default; ensure the load balancer listener quota accommodates them, or configure a smaller range that still covers all required NCache ports.
  • The cluster must run Kubernetes version 1.25.0 or later and provide at least two schedulable Linux worker nodes for the default two-server deployment. For Helm, the default setting, deployment.podAntiAffinity=true, places each server on a separate node. If shared-node placement is acceptable, this value can be set to false during installation.

Create an EKS Cluster

If you already have a cluster, continue with Deployment Process. To create one for either Helm or YAML deployment, use the script below or follow the manual procedure that follows.

Create the Cluster Using the Script

  • Download create-cluster.sh from the NCache Kubernetes repository and open a Bash terminal in the directory containing the file. Ensure that AWS CLI, kubectl, and Helm are installed and that your account has permission to create the required resources.
  • Set CLUSTER_NAME and REGION, then set VPC_ID to your existing VPC and SUBNET_IDS to two public subnet IDs in different Availability Zones, separated by a space. Set IAM_ROLE to the existing role name, NODE_COUNT to at least 2, and NODE_TYPE to an appropriate instance type. The script defaults to m5.large.
  • Configure the AWS CLI credentials before running the script. The role named in IAM_ROLE must trust both eks.amazonaws.com and ec2.amazonaws.com and have the cluster, worker-node, networking, container-registry, and load-balancer permissions listed in the repository README. Your account also needs permission to pass this role.
  • Save the file and run the script from that directory.
bash create-cluster.sh

The script creates the cluster and managed node group, configures kubectl access, tags the subnets, and installs the AWS Load Balancer Controller. After it completes, verify the selected cluster and confirm that the worker nodes show Ready.

kubectl config current-context
kubectl get nodes -o wide

In the same terminal, continue with Deploy Using Helm or Deploy Using YAML Files. The script has already configured cluster access, so the manual creation and connection commands below can be skipped.

Create the Cluster Manually

If you do not already have an EKS cluster, create one through the AWS Management Console and add a managed node group. For the complete procedure, including the required IAM roles and networking resources, see Get Started with Amazon EKS.

  • In the Amazon EKS console, create a cluster and specify its name, Kubernetes version, and cluster IAM role.
  • Select the VPC, subnets, and security groups for the cluster. Configure API endpoint access so that the terminal used for deployment can connect to it.
  • After the cluster becomes active, add a managed node group with a Linux node image and the required node IAM role. Set the desired capacity to at least two worker nodes for the default two-server NCache deployment.
  • Ensure that the cluster's load balancer configuration and subnets support the NCache gateway services described in the prerequisites.
  • Wait for the node group to become active, then use the cluster name and AWS Region in the following connection procedure.

Deployment Process

Choose the deployment method below after connecting to your cluster. The Helm examples use the ncache namespace; the Enterprise YAML examples use default. Use one method for a deployment so that the same resources are not managed by both Helm and YAML files.

Connect kubectl to EKS

  • Open AWS CloudShell from the AWS Management Console.

  • Update the Kubernetes configuration in AWS CloudShell for your EKS cluster:

aws eks update-kubeconfig --region "<aws-region>" --name "<eks-cluster-name>"

This command updates the Kubernetes configuration in AWS CloudShell so that kubectl can communicate with the selected EKS cluster.

  • Verify that kubectl is connected to the EKS cluster:
kubectl config current-context
kubectl get nodes

If the connection is successful, the command displays the EKS worker nodes.

Deploy Using Helm

After confirming cluster access, prepare the chart and install NCache using the following steps.

If you are using deploy-ncache.sh, go directly to Step 2.

Step 1: Prepare the NCache Helm Chart

  • Open AWS CloudShell or a local terminal connected to your cluster. The NCache chart is available directly from the OCI registry.

  • Inspect the defaults for the NCache chart you intend to install:

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

Step 2: Install Helm Chart

To automate the installation, set NCACHE_KEY in deploy-ncache.sh and run the following command from the downloaded ncache/eks directory in Bash. The script uses the current Helm namespace. Use that namespace for the verification and management commands that follow.

bash deploy-ncache.sh eks

After the script finishes, continue at Verify the Server Pods. Check the configuration job, then follow Steps 3 and 4 to verify the gateway services and configure public Management Center access.

For a manual installation, the following command deploys two NCache servers in the ncache namespace with defaultCache enabled. Replace xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your deployment key:

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="EKS"
Tip

For guidance on deploying in different scenarios, refer to Manage an Existing Deployment.

Verify the Server Pods

Check the pods and their worker-node placement after installation:

kubectl rollout status statefulset/ncache --namespace ncache
kubectl get pods,jobs --namespace ncache
kubectl get pods --namespace ncache -o wide

After Helm installs the release, NCache completes cache configuration and licensing through a configuration job. Follow Verify an Update to check the job result, then verify the caches in NCache Management Center before using the deployment.

Verify that all configured NCache server pods are ready; the default deployment contains two. If a pod fails to start, inspect its events and logs using its actual name, and check the deployment key, licensing values, and image access:

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

Step 3: Verify NCache Services

  • Check the gateway services created by the installed chart:
kubectl get svc --namespace ncache

Check the client endpoint and the configured Service ports. Configure public management access in Step 4:

  • Client connections: gateway.clientPort defaults to 9800.
  • Management: gateway.mgmtPorts defaults to 9801-9802, with session affinity.
  • Additional gateway ports: gateway.ports defaults to 9803-9997.
  • Portal: gateway.portalPorts defaults to 9998-9999, with session affinity.

Step 4: Access NCache Management Center

To access NCache Management Center, configure a public management endpoint through gateway.mgmtCenterEndpoint and specify the public subnets through eks.publicSubnetIds. These values can be supplied during helm install or added afterward using helm upgrade.

For EKS, the management endpoint must be a DNS hostname. Provide at least two public subnet IDs from different Availability Zones, separated by commas escaped as \, when passed through Helm. Replace the example hostname and subnet IDs with those 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="ncache.example.com" --set eks.publicSubnetIds="subnet-123\,subnet-456"

Check the management gateway Service and identify its assigned load balancer endpoint:

kubectl get svc --namespace ncache

Configure DNS so that your management hostname resolves to the assigned load balancer. Open NCache Management Center at http://ncache.example.com:9801 or, when HTTPS is configured, https://ncache.example.com:9802, using your own hostname.

After verifying the deployed caches in NCache Management Center, follow Getting Started to begin using NCache. Applications outside Kubernetes can connect through the client gateway using ConnectionOptions, as described in Configure the External Client. Verify the client connection by adding an item to the cache and retrieving it. For subsequent licensing changes, cache configuration updates, and image upgrades, see Manage Deployment.

Deploy Using YAML Files

After confirming cluster access, prepare and apply the server and gateway manifests using the following steps.

Step 1: Prepare the Deployment Files

Download ncache.yaml, client-gatewayservice.yaml, and mgmt-gatewayservice.yaml from the ncache/eks folder in the NCache Kubernetes repository. Run the YAML deployment commands from the directory containing these three files.

  • Use the default namespace for these manifests.
  • In the NCache container's environment variables, set NC_KEY to your deployment key:
- name: NC_KEY
  value: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  • Ensure that the StatefulSet's spec.serviceName is ncache-cacheserver, matching the headless Service in the same file. Add the following field under the StatefulSet's existing spec; retain the other settings:
spec:
  serviceName: ncache-cacheserver
  • Verify that the container image is accessible. If it requires registry credentials, create the ncache-secret image pull Secret in the default namespace; otherwise, remove the imagePullSecrets entry.
  • Keep replicas: 2 for the default two-server deployment and NC_START_DEFAULT_CACHE set to "true". The supplied YAML prefers separate worker nodes but allows both pods to run on the same node. Configure required pod anti-affinity if each server must run on a separate node.
  • If TLS is required, prepare the Secret and environment variables before applying the files, as described in Deploy Using YAML Files.

Retain the Service selectors and pod labels so that the gateways continue to route traffic to the NCache servers.

The EKS client gateway uses an internal Network Load Balancer, while the Management Center gateway uses an internet-facing Network Load Balancer. The supplied files require the AWS Load Balancer Controller for either subnet-selection method below.

Check that the controller is running:

kubectl get deployment aws-load-balancer-controller --namespace kube-system

If it is not installed, follow Install the AWS Load Balancer Controller, including its IAM permissions, before applying the gateway files.

Prepare two public subnets in different Availability Zones in the cluster's VPC. In the AWS console, open VPC > Subnets and check each subnet's associated route table. Its default route, 0.0.0.0/0, must point to an Internet Gateway. If suitable subnets do not exist, create them using unused CIDR ranges and associate them with a route table that has this route.

Choose one of the following methods for the management gateway:

  • Specify public subnet IDs: Set the following annotation under metadata.annotations in mgmt-gatewayservice.yaml, using comma-separated subnet IDs:
service.beta.kubernetes.io/aws-load-balancer-subnets: "subnet-aaaaaaaa,subnet-bbbbbbbb"
  • Use subnet discovery: Remove the empty service.beta.kubernetes.io/aws-load-balancer-subnets annotation from mgmt-gatewayservice.yaml and tag the public subnets so that the controller can discover them:
aws ec2 create-tags --resources "<public-subnet-a>" "<public-subnet-b>" --tags Key=kubernetes.io/role/elb,Value=1

The internal client gateway also needs suitable private subnets. For discovery, tag them as follows:

aws ec2 create-tags --resources "<private-subnet-a>" "<private-subnet-b>" --tags Key=kubernetes.io/role/internal-elb,Value=1

Alternatively, specify private subnet IDs through the same subnet annotation in client-gatewayservice.yaml. Retain internal for the client gateway's scheme and internet-facing for the management gateway. See AWS Network Load Balancer requirements for subnet and network access requirements.

The supplied EKS client gateway exposes TCP port 9800 and ports 9803-9849. Ensure that this range covers the ports used by your caches, and extend it if necessary within the load balancer's listener quota. See Firewalls and Ports.

Step 2: Deploy NCache

Apply the server manifest and both gateway manifests from the package root:

kubectl apply --namespace default -f ncache.yaml
kubectl apply --namespace default -f client-gatewayservice.yaml
kubectl apply --namespace default -f mgmt-gatewayservice.yaml

Verify the Server Pods

Check that both server pods have started and inspect their worker-node placement:

kubectl rollout status statefulset/ncache --namespace default
kubectl get pods --namespace default -l app=ncache -o wide

The default deployment creates ncache-0 and ncache-1. If a pod fails to start, inspect its events and logs, and check the deployment key, image access, and any certificate settings:

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

Pod status does not confirm that the caches are ready. Verify cache status in NCache Management Center after opening the management endpoint in Step 4.

Step 3: Verify NCache Services

Check that the headless Service and both gateway Services exist:

kubectl get svc ncache-cacheserver ncache-client-gateway ncache-mgmt-gateway --namespace default

Wait until the gateway endpoints have been assigned, and confirm that they are reachable from the application and administrator networks. The client gateway exposes port 9800. The management gateway exposes ports 9801 and 9802 for Management Center and ports 9998 and 9999 for the portal.

The client gateway's additional port range is 9803-9849. Its endpoint is internal, so client applications need network access to the load balancer's private network.

Step 4: Access NCache Management Center

Use the management gateway's assigned external IP address or DNS hostname:

kubectl get svc ncache-mgmt-gateway --namespace default

Open http://<management-gateway-endpoint>:9801 or, when Management Center HTTPS is configured, https://<management-gateway-endpoint>:9802. The endpoint is the value reported in the Service's EXTERNAL-IP column.

In NCache Management Center, verify that the intended cache is running on both server nodes before using it. Follow Configure the External Client to connect an application through the client gateway using ConnectionOptions, then add an item to the cache and retrieve it to verify the connection. For licensing, cache changes, and subsequent updates, follow the YAML tabs in Manage Deployment.

See Also

Evaluation Period Management
NCache License Management

Contact Us

PHONE

+1 214-619-2601   (US)

+44 20 7993 8327   (UK)

 
EMAIL

sales@alachisoft.com

support@alachisoft.com

NCache
  • Edition Comparison
  • NCache Architecture
  • Benchmarks
Try NCache
Pricing
NCache Playground

Deployments
  • Cloud
  • Docker
  • Kubernetes
  • On-Premises
Technical Use Cases
  • ASP.NET Sessions
  • ASP.NET Core Sessions
  • Pub/Sub Messaging
  • SignalR Backplane
  • Internet of Things (IoT)
  • NoSQL Database
  • Stream Processing
  • Microservices
Resources
  • Blogs
  • Foundations
  • Videos
  • Comparisons
  • Shows
  • Whitepapers
  • Articles
  • Tech Talks
  • Magazine Articles
  • Third-Party Articles
Customer Case Studies
  • Testimonials
  • Customers
Support
  • Docs
  • Schedule a Demo
  • Tips
Company
  • Leadership
  • Partners
  • News
  • Events
  • Careers
Contact Us

  • EnglishChinese (Simplified)FrenchGermanItalianJapaneseKoreanPortugueseSpanish

  • Terms of Use
  •  
  • Privacy Policy
  •  
  • Cookie Policy
© Copyright Alachisoft 2002 - . All rights reserved. NCache is a registered trademark of Diyatech Corp.
  • Facebook
  • Twitter
  • Youtube
  • LinkedIn
  • RSS