Connecting the Client to NCache Cloud

NCache Cloud deploys cache cluster nodes on Linux virtual machines managed by an Azure Virtual Machine Scale Set (VMSS). Each host VM runs an isolated NCache Docker container within your private Virtual Network (VNet).

Since the cluster nodes reside in a private subnet, administrative tools and test utilities must be executed from a jumpbox or test virtual machine deployed inside the same VNet (or a peered VNet) with network connectivity to ncache-subnet.

Follow these step-by-step instructions to connect to your jumpbox, import the NCache PowerShell module, run the stress test tool, and monitor the cluster statistics.

Step 1: Access the Private Environment

Because your NCache Cloud cluster nodes reside in a private subnet without public IP addresses, you must execute administrative commands and test tools from an internal network location. Choose one of the following connection methods:

Option A: Connect Directly via Browser (Recommended)

Azure Bastion provides secure, seamless connectivity directly through the Azure Portal over TLS (port 443) using the lightweight Developer SKU without requiring public IPs:

In the Azure Portal, navigate to your Virtual Machine Scale Set (VMSS) instances, select your target node, and click Bastion in the left menu.
Provide your authentication credentials (such as your VM password, SSH private key, or Microsoft Entra ID credentials) and click Connect.
Once connected to the host Linux VM shell, you can elevate privileges and access the running NCache container if needed:

sudo -i
docker exec -it ncache-instance pwsh

Connect Directly via Browser - Azure Bastion

Option B: Connect via an Internal Jumpbox / Test VM

If you prefer using a dedicated client machine, connect via RDP/SSH to a Windows or Linux jumpbox deployed within the same VNet.

Before running tests from your jumpbox, ensure the following are configured:

NCache Client Tools: The NCache client or remote management tools must be installed on the jumpbox machine so the PowerShell module (NCachePS) is available.
DNS Resolution: The jumpbox must be configured to resolve the VNet's private DNS zone (e.g., <environment>.ncache), allowing it to map the endpoint name to the private cache node IPs.

Steps to Connect via an Internal Jumpbox / Test VM

Ensure your private SSH key (.pem) has restricted read permissions:
```
chmod 400 <keyname>.pem
```
Establish the SSH session using the instance's private IP address:
```
ssh -i /path/to/<keyname>.pem azureuser@<INSTANCE_PRIVATE_IP>
```

Step 2: Open PowerShell and Import the NCache Module

Open a PowerShell console on your jumpbox and import the NCache PowerShell module to access administrative caching cmdlets.

Import-Module 'C:\Program Files\NCache\bin\tools\ncacheps\ncacheps.dll'

Step 3: Locate Your Private Endpoint

Before running tests or connecting applications, you need your unique private endpoint:

In the Azure Portal, open your deployed Managed Application and select Parameters and Outputs under Settings in the left menu.
Locate the privateEndpoint value (e.g., demo-app.ncache).

Private Endpoint - Azure

Step 4: Execute the Test-Stress

Run Test-Stress from your PowerShell console, pointing it explicitly to your private client endpoint and port (9800), along with your cache name:

Test-Stress -Server demo-app.ncache:9800 -CacheName defaultCache -ItemsCount 100

Test Stress Azure

Important

You can only use the Test-Stress and Add-TestData commands. Standard management tools from outside your private network cannot be used.

Step 5: View Real-Time Statistics in the NCache Cloud Portal

Open the NCache Cloud Portal or Management Center via your public management endpoint in a web browser to view real-time statistics and throughput metrics as generated by the test workload.

Statistics - Azure

Step 6: Connecting Client Applications (.NET, Java, Node.js, Python)

To connect your production client applications to NCache Cloud, ensure your project has the appropriate NCache client package installed (such as the Alachisoft.NCache.Client NuGet package for .NET). Then, specify your cache name and bind to the private client endpoint (port 9800) using connection options or properties.

.NET

To initialize and connect to your cache from a .NET application, instantiate a CacheConnectionOptions object, add your private client endpoint server and port, and retrieve the cache instance using the CacheManager.

// Specify cache name and private client endpoint
string cacheName = "defaultCache";
CacheConnectionOptions options = new CacheConnectionOptions();
options.AddServer("demo-app.ncache", 9800); // Private client endpoint

// Initialize cache
ICache cache = CacheManager.GetCache(cacheName, options);

Java

To connect from a Java application, configure the CacheConnectionOptions with the server information object pointing to your private client endpoint and initialize the cache.

String cacheName = "defaultCache";
CacheConnectionOptions options = new CacheConnectionOptions();
options.servers.add(new ServerInfo("demo-app.ncache", 9800));

Cache cache = NCache.initializeCache(cacheName, options);

Python

To connect from a Python application, instantiate the connection options, add your private client endpoint server details, and fetch the cache instance.

cache_name = "defaultCache"
options = ncache.CacheConnectionOptions()
options.add_server("demo-app.ncache", 9800)

cache = ncache.CacheManager.get_cache(cache_name, options)

Node.js

To connect from a Node.js application, pass an options object containing your server IP and port configuration into the client manager method.

var cacheName = "defaultCache";
var options = {
    servers: [{ ip: "demo-app.ncache", port: 9800 }]
};

ncache.CacheManager.getCache(cacheName, options, function(err, cache) {
    if(err) throw err;
    // Perform operations
});

Understanding Endpoints and Management Boundaries

Your NCache deployment exposes two primary management endpoints and a dedicated client data channel:

Private Client Endpoint (port 9800): The internal data channel (e.g., <environment>.ncache:9800) used by client applications and testing utilities to perform cache read/write operations.
Private Management Endpoint (port 9801): Used for internal cluster management commands and monitoring probes.
Public Management Endpoint: The secure Azure Front Door HTTPS address used exclusively to access the NCache Cloud Portal and Management Center from authorized external networks.