SocketX on Azure AKS

Introduction

SocketX Server is a WebSocket proxy that terminates SocketX/MTE-protected connections from SocketX clients, decodes client payloads inside the proxy, and forwards WebSocket frames to an upstream WebSocket service. The upstream leg is plaintext when the configured upstream uses ws:// and TLS-protected when it uses wss://.

The Azure package in this repository deploys SocketX Server as an AKS cluster extension using the Helm chart under aks-extension/charts.

---

Prerequisites

• An Azure subscription with permissions to deploy AKS resources and Kubernetes extensions.
• An existing AKS cluster or permission to create one through the Azure deployment flow.
• A backend WebSocket service reachable from the AKS cluster.
• A valid DOMAIN_MAP value.

---

Deployment Model

The Azure Marketplace/AKS extension assets include:

• aks-extension/manifest.yaml - extension package metadata.
• aks-extension/arm-template.json - Azure deployment template.
• aks-extension/createUiDefinition.json - Azure portal configuration UI.
• aks-extension/charts - Helm chart used by the extension.

The extension deploys:

• A SocketX Server Deployment.
• A Kubernetes Service.
• A ConfigMap containing the decoded DOMAIN_MAP.

---

Azure Portal Configuration

The Azure UI definition supports these deployment choices:

Setting	Description
AKS Cluster	Use an existing AKS cluster or create a new one.
Auto-upgrade Minor Version	Enables extension minor-version auto-upgrade.
Domain Map	JSON string mapping hostnames to upstream WebSocket targets and allowed origins.
Replica Count	Number of SocketX Server replicas, from 1 to 10.
Log Level	error, info, or debug in the current Azure UI.
Service Type	ClusterIP, LoadBalancer, or NodePort.
Service Port	Port exposed by the Kubernetes service. Default 8080.

---

Helm Values

The chart defaults in aks-extension/charts/values.yaml configure Azure request-based billing:

domainMap: '{"*": {"upstream": "ws://your-upstream-service", "allowedOrigins": ["*"]}}'
domainMapBase64: ""
billingStrategy: "request_based"
billingProvider: "azure"
billingProduct: "socketx"
billingReportInterval: "15m"
logLevel: "info"
service:
  type: ClusterIP
  port: 8080

When deployed through the ARM template, domainMap is base64-encoded into the domainMapBase64 setting:

{
  "domainMapBase64": "[base64(parameters('domainMap'))]",
  "replicaCount": "[string(parameters('replicaCount'))]",
  "logLevel": "[parameters('logLevel')]",
  "service.type": "[parameters('serviceType')]",
  "service.port": "[parameters('servicePort')]"
}

The Helm chart decodes domainMapBase64 before writing the DOMAIN_MAP environment value to the SocketX pod.

---

DOMAIN_MAP Format

DOMAIN_MAP must be a JSON object. Each value must include upstream and allowedOrigins.

{
  "api.example.com": {
    "upstream": "wss://backend.example.com/socket",
    "allowedOrigins": ["https://app.example.com"]
  },
  "*.staging.example.com": {
    "upstream": "ws://staging-backend:8080",
    "allowedOrigins": ["https://*.staging.example.com"]
  },
  "*": {
    "upstream": "ws://default-backend:8080",
    "allowedOrigins": ["*"]
  }
}

Matching order is exact host, subdomain wildcard such as *.example.com, then global wildcard *. The incoming Host header may include a port, so include that port in the key or use a wildcard mapping when required.

allowedOrigins is required in practice. Empty or missing origin lists reject connections. Exact origins include the scheme, for example https://app.example.com. Origin wildcard entries must begin with *., for example https://*.example.com.

---

Server Configuration

The Azure extension sets these environment variables in the SocketX container:

Variable	Value Source
DOMAIN_MAP	Decoded from domainMapBase64, or from domainMap when no base64 value is provided.
BILLING_STRATEGY	Helm value billingStrategy; default request_based.
BILLING_PROVIDER	Helm value billingProvider; default azure.
BILLING_PRODUCT	Helm value billingProduct; default socketx.
BILLING_REPORT_INTERVAL	Helm value billingReportInterval; default 15m.
LOG_LEVEL	Helm value logLevel; default info.

SocketX Server also supports these optional variables if you customize the chart:

Variable	Default	Description
LISTEN_HOST	0.0.0.0	Address the server binds to.
LISTEN_PORT	8080	Port the server listens on.
MTE_COMPANY_NAME	Built in	MTE license company name.
MTE_LICENSE_KEY	Built in	MTE license key.
MTE_KYBER_STRENGTH	512	0, 512, 768, or 1024.
MTE_DECODER_WINDOW_SIZE	1000	MTE decoder re-sequencing window.
WS_READ_BUFFER_SIZE	1024	WebSocket read buffer size in bytes.
WS_WRITE_BUFFER_SIZE	1024	WebSocket write buffer size in bytes.
CLIENT_PONG_TIMEOUT	60	Seconds allowed to receive client pong.
CLIENT_PING_INTERVAL	54	Seconds between proxy-to-client pings.
UPSTREAM_PONG_TIMEOUT	60	Seconds allowed to receive upstream pong.
UPSTREAM_PING_INTERVAL	54	Seconds between proxy-to-upstream pings.
WRITE_TIMEOUT	10	Seconds allowed for WebSocket writes.
USE_CONSOLE_LOGS	false	Set to true for human-readable logs.

---

Azure Marketplace Billing

The Azure extension defaults to request-based Marketplace metering:

BILLING_STRATEGY=request_based
BILLING_PROVIDER=azure
BILLING_PRODUCT=socketx
BILLING_REPORT_INTERVAL=15m

The server counts successful ProxyData encode/decode operations only. Handshake messages are not counted.

For Azure request-based billing, the server:

• Uses DefaultAzureCredential, which supports managed identity in Azure.
• Uses AZURE_RESOURCE_ID when set.
• Otherwise attempts to detect the managed application resource ID through Azure Instance Metadata Service.
• Reports the encodedMessages and decodedMessages dimensions to the Azure Marketplace API.

---

Service Exposure

The Azure deployment supports these Kubernetes service types:

Service Type	Use Case
ClusterIP	Internal-only service inside the cluster.
LoadBalancer	Azure load balancer for direct external access.
NodePort	Expose the service on each node at a static port.

Choose the service type that matches your network and ingress architecture.

---

Testing & Health Checks

The chart configures TCP liveness and readiness probes against the SocketX service port.

You can also test the HTTP echo endpoint:

curl http://<SOCKETX_HOST_OR_IP>:<PORT>/api/socketx-echo?msg=test

Expected response:

{
  "message": "test",
  "timestamp": "<RFC3339 timestamp>"
}

Monitor container logs for the startup message: Starting server.

---

Observability

Startup logs include a redacted config object with fields such as listen_addr, log_level, socketx_version, mte_version, mte_kyber_strength, timeout values, buffer sizes, and billing settings.

MTE encryption and decryption event logs include:

• connection_id
• event_type
• duration_ms
• payload_size_bytes
• payload_sha256
• eeid
• host
• origin
• upstream_server

Connection close logs include an audit object with connection timing, message counts, byte counts, total encode/decode time, and WebSocket close information.

payload_sha256 is a hash of plaintext payload bytes at the proxy for correlation and audit workflows. It is not a standalone compliance certification or tamper-evidence guarantee.

---

Troubleshooting

1. Invalid configuration
   • Verify DOMAIN_MAP is valid JSON and each entry has upstream and allowedOrigins.
   • If using domainMapBase64, confirm it decodes to the expected JSON string.
2. SocketX unreachable
   • Check Kubernetes service type, port, ingress, firewall, and load balancer configuration.
3. Origin rejected
   • Confirm the browser Origin value matches the selected host mapping's allowedOrigins list.
4. Billing events fail
   • Confirm the pod has access to a managed identity or another supported Azure credential path.
   • Set AZURE_RESOURCE_ID explicitly if IMDS resource detection is not correct for the deployment.

---

Security Notes

• The server does not persist WebSocket payloads.
• Runtime environment variables may contain license, billing, or deployment configuration values and should be protected accordingly.
• Use wss:// upstream URLs when the proxy-to-upstream leg must be TLS-protected.

---

Costs

Marketplace charges depend on the selected Azure listing and plan. Azure infrastructure costs, such as AKS nodes, load balancers, networking, logging, and monitoring, also apply.

---

Support

For assistance, contact Eclypses Support:

customer_support@eclypses.com

Monday-Friday, 8:00 AM-5:00 PM MST, excluding holidays.