Cloud-Native Development: 12-Factor Apps, Container Patterns, and Service Mesh

"Cloud-native" is one of those terms that gets applied to everything from a VPS running Docker to a globally distributed, zero-downtime Kubernetes deployment. What it actually means: designing applications for the cloud's native capabilities — horizontal scaling, self-healing, immutable infrastructure, and dynamic orchestration.

This guide covers the specific practices that make an application genuinely cloud-native, with working code and configurations.

---

The 12-Factor App Methodology

The 12-factor methodology (Heroku, 2011) remains the best framework for building cloud-native services. Each factor addresses a specific operational pain point.

---

Factor III: Configuration

All configuration should come from environment variables — not config files committed to the repository, not hardcoded values.

// config/index.ts — validated config with Zod
import { z } from 'zod';

const ConfigSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  // Feature flags via env (for simple cases)
  ENABLE_NEW_CHECKOUT: z.coerce.boolean().default(false),
});

// Validate at startup — fail fast if config is missing
function loadConfig() {
  const result = ConfigSchema.safeParse(process.env);
  if (!result.success) {
    console.error('Invalid configuration:');
    result.error.issues.forEach(issue => {
      console.error(`  ${issue.path.join('.')}: ${issue.message}`);
    });
    process.exit(1);
  }
  return result.data;
}

export const config = loadConfig();

Kubernetes ConfigMap and Secrets:

# k8s/configmap.yaml — non-sensitive config
apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
  namespace: production
data:
  NODE_ENV: "production"
  PORT: "3000"
  LOG_LEVEL: "info"
  REDIS_URL: "redis://redis-service:6379"

---
# k8s/secret.yaml — sensitive config (base64 encoded)
apiVersion: v1
kind: Secret
metadata:
  name: api-secrets
  namespace: production
type: Opaque
stringData:  # stringData handles encoding automatically
  DATABASE_URL: "postgresql://user:password@postgres:5432/myapp"
  JWT_SECRET: "your-very-long-random-secret"
  STRIPE_SECRET_KEY: "sk_live_..."

# k8s/deployment.yaml — inject config into containers
spec:
  containers:
    - name: api
      envFrom:
        - configMapRef:
            name: api-config
        - secretRef:
            name: api-secrets

---

Factor IX: Disposability — Graceful Shutdown

Cloud-native processes receive SIGTERM when being stopped (deployment update, scale-down, node drain). They must handle it cleanly — finish in-flight requests, drain job queues, close DB connections.

// lib/gracefulShutdown.ts
export class GracefulShutdown {
  private shutdownHandlers: Array<() => Promise<void>> = [];
  private isShuttingDown = false;

  register(name: string, handler: () => Promise<void>) {
    this.shutdownHandlers.push(async () => {
      console.info(`Shutting down: ${name}`);
      await handler();
      console.info(`Shutdown complete: ${name}`);
    });
  }

  async shutdown(signal: string) {
    if (this.isShuttingDown) return;
    this.isShuttingDown = true;
    console.info(`Received ${signal} — starting graceful shutdown`);

    const timeout = setTimeout(() => {
      console.error('Graceful shutdown timed out after 30s — force exiting');
      process.exit(1);
    }, 30_000);

    try {
      await Promise.all(this.shutdownHandlers.map(h => h()));
      clearTimeout(timeout);
      console.info('Graceful shutdown complete');
      process.exit(0);
    } catch (err) {
      console.error('Error during shutdown:', err);
      process.exit(1);
    }
  }

  listen() {
    process.on('SIGTERM', () => this.shutdown('SIGTERM'));
    process.on('SIGINT', () => this.shutdown('SIGINT'));
  }
}

// app.ts
import Fastify from 'fastify';
import { db } from './lib/db';
import { redis } from './lib/redis';
import { webhookQueue } from './lib/queue';

const app = Fastify({ logger: true });
const shutdown = new GracefulShutdown();

// Register shutdown handlers
shutdown.register('HTTP server', async () => {
  await app.close();  // Waits for in-flight requests
});
shutdown.register('Database', async () => {
  await db.$disconnect();
});
shutdown.register('Redis', async () => {
  await redis.quit();
});
shutdown.register('Job queue', async () => {
  await webhookQueue.close();  // Waits for current job to complete
});

shutdown.listen();

await app.listen({ port: config.PORT, host: '0.0.0.0' });

---

Health Checks: Liveness vs Readiness

Kubernetes uses two health check types with different meanings:

• Liveness: Is the process alive? (If not, kill and restart it)
• Readiness: Is the process ready to accept traffic? (If not, remove from load balancer but don't restart)

// routes/health.ts
import { FastifyInstance } from 'fastify';

export async function healthRoutes(app: FastifyInstance) {
  // Liveness — is the process alive and not deadlocked?
  app.get('/health/live', async (request, reply) => {
    return reply.code(200).send({ status: 'alive', timestamp: Date.now() });
  });

  // Readiness — can this instance serve traffic?
  app.get('/health/ready', async (request, reply) => {
    const checks: Record<string, 'ok' | 'error'> = {};
    let isReady = true;

    // Check database
    try {
      await db.$queryRaw`SELECT 1`;
      checks.database = 'ok';
    } catch {
      checks.database = 'error';
      isReady = false;
    }

    // Check Redis
    try {
      await redis.ping();
      checks.redis = 'ok';
    } catch {
      checks.redis = 'error';
      isReady = false;
    }

    const status = isReady ? 200 : 503;
    return reply.code(status).send({
      status: isReady ? 'ready' : 'not_ready',
      checks,
      timestamp: Date.now(),
    });
  });

  // Startup probe — used during initial container startup
  app.get('/health/startup', async (request, reply) => {
    // Same as readiness — Kubernetes uses this only during startup phase
    return reply.redirect('/health/ready');
  });
}

Kubernetes probe configuration:

spec:
  containers:
    - name: api
      livenessProbe:
        httpGet:
          path: /health/live
          port: 3000
        initialDelaySeconds: 10   # Wait 10s after start before checking
        periodSeconds: 15          # Check every 15s
        failureThreshold: 3        # Restart after 3 failures
        timeoutSeconds: 5

      readinessProbe:
        httpGet:
          path: /health/ready
          port: 3000
        initialDelaySeconds: 5
        periodSeconds: 10
        failureThreshold: 3
        timeoutSeconds: 5

      startupProbe:
        httpGet:
          path: /health/startup
          port: 3000
        failureThreshold: 30     # Allow 30 × 10s = 5 min for startup
        periodSeconds: 10

---

Factor XI: Logs as Event Streams

Cloud-native apps write to stdout/stderr in structured JSON. The platform (Kubernetes, ECS) collects and ships logs to your observability stack.

// lib/logger.ts
import pino from 'pino';

export const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  // JSON in production, pretty in dev
  transport: process.env.NODE_ENV === 'development'
    ? { target: 'pino-pretty' }
    : undefined,
  base: {
    service: process.env.SERVICE_NAME ?? 'api',
    version: process.env.APP_VERSION ?? 'unknown',
    env: process.env.NODE_ENV,
  },
  formatters: {
    level: (label) => ({ level: label }),
  },
});

// Request logger middleware adds trace context
app.addHook('onRequest', async (request) => {
  request.log = logger.child({
    requestId: request.id,
    method: request.method,
    url: request.url,
    traceId: request.headers['x-trace-id'],
  });
});

Never: console.log() in production, writing to files, structured data in log messages instead of as separate fields.

---

Service Mesh (Istio/Linkerd)

A service mesh handles service-to-service communication concerns — mTLS, retries, circuit breaking, distributed tracing — without application code changes.

When you need a service mesh:

• 10+ microservices communicating internally
• Zero-trust networking requirements (mTLS between every service)
• Fine-grained traffic control (A/B routing at the mesh level)
• Observability across all service-to-service calls

When you don't (yet):

• Fewer than 10 services
• Team lacks Kubernetes expertise to operate Istio
• Circuit breaking is already handled at the application level

Linkerd (simpler than Istio) install:

# Install Linkerd CLI
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh

# Validate cluster
linkerd check --pre

# Install on cluster
linkerd install --crds | kubectl apply -f -
linkerd install | kubectl apply -f -

# Enable mTLS for a namespace
kubectl annotate namespace production linkerd.io/inject=enabled

# Visualize service-to-service traffic
linkerd viz install | kubectl apply -f -
linkerd viz dashboard

Istio traffic management (canary deployment):

# Gradually shift traffic to new version without code changes
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: payment-service
spec:
  hosts:
    - payment-service
  http:
    - route:
        - destination:
            host: payment-service
            subset: v1
          weight: 90
        - destination:
            host: payment-service
            subset: v2
          weight: 10  # 10% of traffic to new version
---
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: payment-service
spec:
  host: payment-service
  subsets:
    - name: v1
      labels:
        version: v1
    - name: v2
      labels:
        version: v2

---

Cloud-Native Checklist

Before calling an application cloud-native:

• Config comes from environment variables (no hardcoded values)
• Logs to stdout in structured JSON
• Handles SIGTERM with graceful shutdown (< 30s)
• Liveness and readiness probes implemented
• Stateless (no local file storage, no in-memory sessions)
• Horizontal scaling works without configuration changes
• Health check doesn't require authentication
• DB migrations run as one-off jobs, not on startup
• No hardcoded hostnames — uses service discovery
• Resource requests and limits set in Kubernetes manifests

---

Working With Viprasol

We build cloud-native applications and migrate legacy systems to cloud-native patterns. Our work includes 12-factor refactoring, Kubernetes deployment setup, health check implementation, and observability integration.

→ Talk to our cloud team about cloud-native architecture.

---

See Also

• Kubernetes vs ECS — choosing your container orchestration platform
• Infrastructure as Code — Terraform for cloud-native infra
• DevOps Best Practices — CI/CD for cloud-native apps
• Observability and Monitoring — metrics and tracing in cloud-native systems
• Cloud Solutions — cloud infrastructure and DevOps services