Kubernetes deployment settings

Nexo Edge runs in a customer-managed Kubernetes cluster. Treat deployment settings as workload policy: review them with the same care as pipeline behavior, database credentials, and network access.

Resource requests and limits

Set CPU and memory requests from measured steady-state load, then leave enough headroom for connection bursts, BSON processing, response transformation, and background telemetry.

• Requests must be present before CPU or memory utilization can drive an HPA reliably.
• A memory limit that is too low can restart the Proxy during large responses or traffic bursts.
• A CPU limit that is too low can appear as database latency even when MongoDB is healthy.
• Re-test resources when body logging, audit capture, masking, caching, or shadow traffic is enabled.

Start in an isolated environment, replay representative traffic, and record p95/p99 latency, memory high-water mark, throttling, connection count, and restart behavior.

Container security context

The 0.2.0 Edge management chart uses this restricted pod and container posture:

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 65534
  fsGroup: 65534
  seccompProfile:
    type: RuntimeDefault
securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop: ["ALL"]

The Proxy pod identity is rendered separately by the pinned Operator. Inspect the generated Proxy workload and do not reuse the management-pod UID or fsGroup as a generic Nexo identity.

Use only declared writable mounts such as /tmp. Do not relax the security context to work around an image, configuration, or file-permission error; correct the underlying deployment input.

Scheduling and placement

Use Kubernetes scheduling controls deliberately:

Control	Use
Node selector or affinity	Keep Nexo on approved worker pools or zones.
Tolerations	Permit scheduling only on intentionally tainted nodes.
Topology spread	Distribute replicas across zones and nodes.
Pod anti-affinity	Reduce the chance that all replicas share one failure domain.
Priority class	Protect critical data-path capacity during cluster pressure.

Keep Nexo close enough to MongoDB to meet latency goals while preserving the required network and residency boundaries.

Startup, readiness, and liveness

• Startup should allow dependency initialization without triggering premature restarts.
• Readiness controls whether a pod receives new client traffic. It must fail when the pod cannot safely serve the active configuration.
• Liveness should detect a stuck process, not transient MongoDB latency.
• Termination grace must allow readiness withdrawal and connection draining before the pod is killed.

Use the probe paths and timings published by the installed release. Do not copy values from a different chart or bundle without checking its templates and release notes.

Autoscaling and disruption

Horizontal scaling is useful only when the Service, session behavior, connection budgets, and upstream capacity can support additional replicas.

• Define an HPA from measured CPU or memory behavior.
• Set resource requests before enabling utilization-based scaling.
• Use a PodDisruptionBudget to preserve capacity during voluntary maintenance.
• Test node drain, rolling restart, scale-out, and scale-in with live connections.
• Coordinate replica count with MongoDB and connection-pool limits.

0.2.0 boundaries

The immutable 0.2.0 bundle is a Private Preview. Verify the chart-rendered probes, security context, replica behavior, and supported deployment profile before applying custom settings. Docker, Docker Compose, public VM binaries, and public air-gapped installation are not supported 0.2.0 deployment paths.

Pre-deployment review

1. Render the exact chart and values intended for the environment.
2. Confirm image, resources, security context, scheduling, probes, and disruption policy.
3. Verify NetworkPolicy, DNS, certificate, Secret, and registry access.
4. Exercise rolling restart and node drain.
5. Confirm the active Nexo version and pipeline revision after rollout.

Preserved legacy operations reference

:::danger Unavailable in Nexo 0.2.0

This frozen section preserves every legacy workflow, command, flag, example, table, troubleshooting item, limitation, and related link for parity. It does not make those interfaces available in 0.2.0. The 0.2.0 Private Preview has no public Docker/Compose or VM/binary distribution, no public chart repository, no supported end-to-end nexoctl login/status/upgrade workflow, no profiling API or profiling CLI, no canary control API, no automatic promotion/rollback engine, and no executable router or connection phase. Every shell command below is historical, not a copy/paste procedure. Never pipe an unverified download into a shell, consume a mutable latest artifact, or place connect tokens, license JWTs, passwords, or API keys in process arguments. Require a pinned artifact plus an approved signature/checksum and the licensed secret-delivery workflow. Use placeholders only and follow the supported 0.2.0 guidance above this section.

:::

Each Nexo project can define deployment settings for its proxy workloads. This page explains what each configurable setting does, when to use it, and which defaults are typically safest for production.

The recommendations below assume the Nexo proxy is running in Kubernetes and needs enough headroom to keep MongoDB connections, health checks, and in-memory query caching responsive under load.

Legacy UI section labels:

• Resources
• Security
• Scheduling
• Lifecycle
• Auto-scaling
• Networking
• Registry
• Presets
• Import/Export

Resources

Resource settings control both how Kubernetes schedules the proxy and how much CPU or memory the container is allowed to consume at runtime.

CPU Request / Limit

CPU requests reserve a minimum amount of compute for the pod, while CPU limits cap how much CPU it can burst to. For the proxy, a good starting point is a request between 100m and 250m, with a limit between 500m and 1000m depending on traffic volume and pipeline complexity.

• Request = scheduling guarantee used by the Kubernetes scheduler.
• Limit = hard CPU ceiling enforced by the runtime.
• Higher traffic, TLS, and heavier pipelines usually need more CPU headroom.

Memory Request / Limit

The proxy caches query-related state in memory, so memory settings matter even more than CPU for stable performance. Start with a request between 128Mi and 256Mi, and a limit between 512Mi and 1Gi.

• Requests help the pod land on a node with enough RAM.
• Limits are a hard cap, not a soft target.
• If the process exceeds its memory limit, Kubernetes can terminate it with OOMKilled.

resources:
  requests:
    cpu: 200m
    memory: 256Mi
  limits:
    cpu: 1000m
    memory: 1Gi

Security Context

Security context settings lock down the proxy container so it runs with the minimum privileges needed for normal operation.

runAsNonRoot

Set runAsNonRoot: true whenever possible. This prevents the proxy from starting as UID 0 and reduces the blast radius of a compromised container.

readOnlyRootFilesystem

Set readOnlyRootFilesystem: true for production. The proxy only needs a writable /tmp, so the rest of the root filesystem can stay immutable.

runAsUser / runAsGroup

Use a fixed non-root UID and GID such as 1000 so file ownership and runtime expectations are explicit across environments.

Drop Capabilities

Drop ALL Linux capabilities by default. The proxy does not require privileged networking or filesystem capabilities for normal use.

Seccomp Profile

RuntimeDefault is the recommended seccomp profile for most clusters because it keeps the standard container runtime protections without requiring custom tuning.

securityContext:
  runAsNonRoot: true
  readOnlyRootFilesystem: true
  runAsUser: 1000
  runAsGroup: 1000
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL
  seccompProfile:
    type: RuntimeDefault

Scheduling

Scheduling settings decide where pods can run and how replicas are distributed across your cluster.

Node Selector

Use node selectors to pin the proxy to specific nodes, such as a zone or a dedicated worker pool. Example: topology.kubernetes.io/zone: us-east-1a.

Tolerations

Tolerations let the proxy run on tainted nodes, such as dedicated pools, GPU-isolated nodes, or spot instance pools reserved for lower-cost traffic.

Topology Spread

Topology spread constraints distribute replicas evenly across zones or nodes. This is recommended for high availability because it reduces the chance that one infrastructure failure takes out the full proxy tier.

Pod Anti-Affinity

Pod anti-affinity prevents multiple proxy replicas from landing on the same node. Use it when you want stronger replica isolation than topology spread alone.

Priority Class

Assign a priority class such as system-cluster-critical or a custom class if the proxy should be harder to evict than lower-priority workloads.

Lifecycle

Lifecycle settings control how the proxy starts, how health is checked, and how gracefully it shuts down.

Termination Grace Period

This setting gives the proxy time to drain in-flight connections during shutdown. For workloads with long-running aggregations, a grace period of 60 to 120 seconds is a sensible production default.

Startup Probe Timeout

The startup probe timeout defines how long Kubernetes waits for the proxy to connect to MongoDB and become healthy on first boot. Increase it if cold starts or upstream connection establishment are slow.

Liveness / Readiness Probes

Liveness and readiness probes define how often Kubernetes checks the proxy. The proxy exposes /healthz on its HTTP port, so this is the standard probe path for both startup validation and steady-state monitoring.

terminationGracePeriodSeconds: 90
startupProbe:
  httpGet:
    path: /healthz
    port: http
  failureThreshold: 30
  periodSeconds: 2
livenessProbe:
  httpGet:
    path: /healthz
    port: http
readinessProbe:
  httpGet:
    path: /healthz
    port: http

Auto-Scaling

Auto-scaling combines elasticity and disruption protection so the proxy can grow during load and stay available during maintenance.

HPA

The Horizontal Pod Autoscaler scales replicas between configured minimum and maximum values using target CPU or memory utilization percentages. HPA depends on resource requests being set, because utilization is calculated relative to the requested baseline.

PDB

A Pod Disruption Budget defines how many replicas must stay available during voluntary disruptions such as node drains and cluster upgrades. It protects the proxy tier from being drained too aggressively.

• Use HPA to absorb traffic spikes automatically.
• Use PDB to protect healthy capacity during maintenance.
• For production, use both together whenever you run more than one replica.

Networking

Networking settings adjust how the proxy resolves names and how it reaches MongoDB endpoints that are not discoverable through standard cluster DNS.

DNS Policy

ClusterFirst is the default and correct choice for most Kubernetes deployments. Use None only when you need custom resolvers, or Default when you want the pod to inherit node-level DNS behavior.

Host Aliases

Host aliases add static entries to /etc/hosts. They are useful when MongoDB endpoints are outside cluster DNS or when testing failover scenarios against fixed addresses.

Registry

Registry settings determine how Kubernetes pulls the proxy image.

Image Pull Secrets

Image pull secrets are required when the proxy image lives in a private registry or in an air-gapped installation that mirrors images internally.

Image Pull Policy

Use IfNotPresent by default. Switch to Always when using mutable tags such as :latest, or Never when images are pre-loaded onto nodes.

Presets

Nexo includes built-in presets so teams can start from opinionated defaults instead of tuning every knob from scratch.

Development

Minimal settings for fast iteration in non-production environments.

• 1 replica
• No strict limits
• Simple scheduling
• Security options can stay relaxed while testing

Production

Balanced defaults for stable day-to-day workloads.

• Resource requests and limits set
• Security context locked down
• Pod Disruption Budget enabled
• Termination grace period set to 60 seconds

High-Availability

Resilience-first preset for critical traffic paths.

• Multiple replicas
• Topology spread enabled
• Pod anti-affinity enabled
• HPA and PDB enabled together

Import / Export

Deployment settings can be exported as JSON so teams can review changes, keep them in version control, and promote consistent configurations across environments.

• Export settings to JSON and store them alongside application manifests or GitOps repositories.
• Import a JSON file to restore settings, bootstrap a new project, or clone settings from another project.
• Include a top-level schema version field so future Nexo releases can interpret older exports safely.

{
  "schemaVersion": 1,
  "preset": "production",
  "resources": {
    "requests": { "cpu": "200m", "memory": "256Mi" },
    "limits": { "cpu": "1000m", "memory": "1Gi" }
  },
  "securityContext": {
    "runAsNonRoot": true,
    "readOnlyRootFilesystem": true,
    "runAsUser": 1000,
    "runAsGroup": 1000
  }
}

If you manage multiple environments, exporting from a known-good project and importing into another is the fastest way to keep development, staging, and production aligned without manual re-entry.