Nala Athomic: Cloud-Native & Service Mesh Mode
Executive Summary
Starting from the current version, the Nala framework officially supports Mesh Mode (Cloud-Native). This feature transforms the application from a "Smart Client" (which manages its own resilience, discovery, and networking logic) into a "Dumb Client" (which delegates these responsibilities to the infrastructure layer, such as Istio, Linkerd, or AWS App Mesh).
How to Enable
Activation is controlled via a single environment variable or configuration setting in settings.toml.
Environment Variable: ```bash NALA_DEPLOYMENT_MODE="mesh" ```
settings.toml: ```toml [default] deployment_mode = "mesh" ```
Architectural Changes (Bimodal Operation)
When DEPLOYMENT_MODE="mesh", the framework automatically adjusts the behavior of the following components:
| Component | Standalone Mode (Default) | Mesh Mode (New) | Rationale |
|---|---|---|---|
| Service Discovery | Actively queries Consul to resolve IP/Port. | Uses Native K8s DNS (svc.cluster.local). |
The Envoy Proxy intercepts DNS and handles load balancing. Avoids unnecessary dependency on Consul. |
| Resilience (Retry) | Applies Retry policies (Backoff, Jitter) within the app. | Disabled (No-Op). Executes only once. | Prevents "Retry Storms" (App tries 3x * Mesh tries 3x = 9 requests). The Mesh handles retries. |
| Circuit Breaker | Manages circuit state (Open/Closed) in Memory/Redis. | Disabled (Pass-through). | The Mesh handles upstream failure detection (Outlier Detection) and ejects unhealthy pods. |
| Security (mTLS) | Can manage client certificates and strict SSL validation. | Offload. Ignores verify=True and client certs. |
The Sidecar (Envoy) manages the encrypted mTLS tunnel between services transparently. |
| Observability | Propagates proprietary headers (x-request-id). |
Injects W3C headers (traceparent) via OpenTelemetry. |
Ensures Distributed Tracing (Istio/Jaeger) can stitch application spans with network spans. |
Kubernetes Migration Guide (Istio)
When deploying Nala services into a cluster with Sidecar Injection enabled, follow these steps:
1. Clean Application Configuration
Remove manual networking configurations from your settings.toml. Do not define static IPs or complex failover logic in the application code.
2. Update Deployment.yaml
Inject the mode switch into your Pod definition:
```yaml env: - name: NALA_DEPLOYMENT_MODE value: "mesh" # Optional: Pass the namespace for the K8s DNS Provider - name: KUBERNETES_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace ```
3. Configure VirtualService (Istio)
Move the retry logic that previously resided in the Python code to the Istio manifest:
```yaml apiVersion: networking.istio.io/v1alpha3 kind: VirtualService metadata: name: payment-service-route spec: hosts: - payment-service http: - route: - destination: host: payment-service retries: attempts: 3 perTryTimeout: 2s retryOn: gateway-error,connect-failure,refused-stream ```
Troubleshooting
Symptom: Broken Tracing Graphs
Observation: Application spans appear disconnected from the Envoy/Mesh spans in Jaeger/Zipkin.
Cause: Failure to propagate W3C headers.
Fix: In Mesh Mode, Nala automatically calls propagate.inject to add traceparent. Ensure you are not manually clearing headers in custom middleware.
Symptom: SSL/Certificate Errors
Observation: Logs show errors like SSLCertVerificationError when calling upstream services.
Cause: The application is trying to validate the Sidecar's self-signed certificate or the upstream certificate.
Fix: Ensure DEPLOYMENT_MODE="mesh" is set. This forces the HttpClientFactory to set verify=False and trust the local Proxy connection.