Kubernetes паттерны

Обзор паттернов

Kubernetes предоставляет примитивы (Pod, Container), из которых складываются архитектурные паттерны. Эти паттерны решают типовые задачи: логирование, мониторинг, проксирование, инициализация.

Init Container

Init Container выполняется перед запуском основного контейнера. Используется для подготовки среды.

# Init container: wait for database and run migrations
apiVersion: v1
kind: Pod
metadata:
  name: api-server
spec:
  initContainers:
    # Init 1: Wait for PostgreSQL to be ready
    - name: wait-for-db
      image: busybox:1.36
      command: ['sh', '-c']
      args:
        - |
          until nc -z postgres-service 5432; do
            echo "Waiting for PostgreSQL..."
            sleep 2
          done
          echo "PostgreSQL is ready!"

    # Init 2: Run database migrations
    - name: run-migrations
      image: myapp/api:v1.2.3
      command: ['php', 'bin/console', 'doctrine:migrations:migrate', '--no-interaction']
      env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: url

    # Init 3: Warm up cache
    - name: warmup-cache
      image: myapp/api:v1.2.3
      command: ['php', 'bin/console', 'cache:warmup']

  containers:
    - name: api
      image: myapp/api:v1.2.3
      ports:
        - containerPort: 8080

Типичные задачи для Init Container

Sidecar

Sidecar работает параллельно основному контейнеру в одном Pod, расширяя его функциональность.

# Sidecar: log collector + metrics exporter
apiVersion: v1
kind: Pod
metadata:
  name: api-with-sidecars
spec:
  containers:
    # Main container: PHP application
    - name: api
      image: myapp/api:v1.2.3
      ports:
        - containerPort: 8080
      volumeMounts:
        - name: logs
          mountPath: /var/log/app

    # Sidecar 1: Log shipping to centralized logging
    - name: log-shipper
      image: fluent/fluent-bit:2.1
      volumeMounts:
        - name: logs
          mountPath: /var/log/app
          readOnly: true
        - name: fluent-bit-config
          mountPath: /fluent-bit/etc
      resources:
        requests:
          cpu: "50m"
          memory: "64Mi"
        limits:
          cpu: "100m"
          memory: "128Mi"

    # Sidecar 2: Prometheus metrics exporter
    - name: php-fpm-exporter
      image: hipages/php-fpm_exporter:2.2
      ports:
        - containerPort: 9253
          name: metrics
      env:
        - name: PHP_FPM_SCRAPE_URI
          value: "tcp://127.0.0.1:9000/status"
      resources:
        requests:
          cpu: "10m"
          memory: "32Mi"

  volumes:
    - name: logs
      emptyDir: {}
    - name: fluent-bit-config
      configMap:
        name: fluent-bit-config

<?php

declare(strict_types=1);

/**
 * PHP application designed for sidecar pattern
 *
 * Writes structured logs to file (sidecar ships them)
 * Exposes FPM status for metrics sidecar
 */
final class SidecarAwareApplication
{
    /**
     * Write structured JSON logs to file
     * Sidecar (Fluent Bit) reads and ships to Elasticsearch
     */
    public function log(string $level, string $message, array $context = []): void
    {
        $entry = json_encode([
            'timestamp' => (new \DateTimeImmutable())->format('c'),
            'level' => $level,
            'message' => $message,
            'context' => $context,
            'request_id' => $_SERVER['HTTP_X_REQUEST_ID'] ?? uuid_create(),
            'service' => 'api',
        ]) . "\n";

        file_put_contents('/var/log/app/app.log', $entry, FILE_APPEND | LOCK_EX);
    }
}

package main

import (
	"encoding/json"
	"os"
	"sync"
	"time"

	"github.com/google/uuid"
)

// SidecarAwareApp writes structured JSON logs to a file.
// A sidecar (Fluent Bit) reads and ships them to Elasticsearch.
type SidecarAwareApp struct {
	mu      sync.Mutex
	logFile *os.File
}

// NewSidecarAwareApp opens the log file for writing.
func NewSidecarAwareApp(logPath string) (*SidecarAwareApp, error) {
	f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
		return nil, err
	}
	return &SidecarAwareApp{logFile: f}, nil
}

// Log writes a structured JSON log entry to the file.
func (a *SidecarAwareApp) Log(level, message string, context map[string]any, requestID string) error {
	if requestID == "" {
		requestID = uuid.New().String()
	}

	entry := map[string]any{
		"timestamp":  time.Now().Format(time.RFC3339),
		"level":      level,
		"message":    message,
		"context":    context,
		"request_id": requestID,
		"service":    "api",
	}

	data, err := json.Marshal(entry)
	if err != nil {
		return err
	}
	data = append(data, '\n')

	a.mu.Lock()
	defer a.mu.Unlock()

	_, err = a.logFile.Write(data)
	return err
}

// Close releases the log file.
func (a *SidecarAwareApp) Close() error {
	return a.logFile.Close()
}

using System.Text.Json;
using System.Text.Json.Serialization;

// LogEntry is one structured line consumed by the logging sidecar.
public sealed record LogEntry(
    [property: JsonPropertyName("timestamp")] DateTimeOffset Timestamp,
    [property: JsonPropertyName("level")] string Level,
    [property: JsonPropertyName("message")] string Message,
    [property: JsonPropertyName("context")] IReadOnlyDictionary<string, object?> Context,
    [property: JsonPropertyName("request_id")] string RequestId,
    [property: JsonPropertyName("service")] string Service);

/// <summary>
/// Application designed for the sidecar pattern: writes structured JSON logs
/// to a file that a sidecar (Fluent Bit) tails and ships to Elasticsearch.
/// </summary>
public sealed class SidecarAwareApp : IAsyncDisposable
{
    private readonly StreamWriter _writer;
    private readonly SemaphoreSlim _lock = new(1, 1);
    private readonly string _service;

    public SidecarAwareApp(string logPath, string service = "api")
    {
        var stream = new FileStream(
            logPath, FileMode.Append, FileAccess.Write, FileShare.ReadWrite);
        _writer = new StreamWriter(stream) { AutoFlush = true };
        _service = service;
    }

    public async Task LogAsync(
        string level,
        string message,
        IReadOnlyDictionary<string, object?>? context = null,
        string? requestId = null,
        CancellationToken ct = default)
    {
        var entry = new LogEntry(
            DateTimeOffset.UtcNow,
            level,
            message,
            context ?? new Dictionary<string, object?>(),
            requestId ?? Guid.NewGuid().ToString(),
            _service);

        var line = JsonSerializer.Serialize(entry);

        // One JSON object per line — the sidecar parses the file line by line
        await _lock.WaitAsync(ct);
        try
        {
            await _writer.WriteLineAsync(line.AsMemory(), ct);
        }
        finally
        {
            _lock.Release();
        }
    }

    public async ValueTask DisposeAsync()
    {
        await _writer.DisposeAsync();
        _lock.Dispose();
    }
}

import asyncio
import json
import uuid
from dataclasses import asdict, dataclass
from datetime import UTC, datetime
from types import TracebackType
from typing import Any, Self

import aiofiles
from aiofiles.threadpool.text import AsyncTextIOWrapper

@dataclass(frozen=True, slots=True)
class LogEntry:
    """One structured line consumed by the logging sidecar."""

    timestamp: str
    level: str
    message: str
    context: dict[str, Any]
    request_id: str
    service: str

class SidecarAwareApp:
    """Application designed for the sidecar pattern.

    Writes structured JSON logs to a file; a sidecar (Fluent Bit) tails it
    and ships the entries to Elasticsearch.
    """

    def __init__(self, log_path: str, service: str = "api") -> None:
        self._log_path = log_path
        self._service = service
        self._lock = asyncio.Lock()
        self._file: AsyncTextIOWrapper | None = None

    async def __aenter__(self) -> Self:
        self._file = await aiofiles.open(self._log_path, mode="a", encoding="utf-8")
        return self

    async def __aexit__(
        self,
        exc_type: type[BaseException] | None,
        exc: BaseException | None,
        tb: TracebackType | None,
    ) -> None:
        if self._file is not None:
            await self._file.close()
            self._file = None

    async def log(
        self,
        level: str,
        message: str,
        context: dict[str, Any] | None = None,
        request_id: str | None = None,
    ) -> None:
        if self._file is None:
            raise RuntimeError(
                "log file is not open: use 'async with SidecarAwareApp(...)'"
            )

        entry = LogEntry(
            timestamp=datetime.now(UTC).isoformat(),
            level=level,
            message=message,
            context=context or {},
            request_id=request_id or str(uuid.uuid4()),
            service=self._service,
        )

        # One JSON object per line — the sidecar parses the file line by line
        async with self._lock:
            await self._file.write(json.dumps(asdict(entry)) + "\n")
            await self._file.flush()

Ambassador -- прокси-контейнер для управления исходящими соединениями. Основной контейнер общается с Ambassador через localhost.

# Ambassador: connection pooling proxy for PostgreSQL
apiVersion: v1
kind: Pod
metadata:
  name: api-with-pgbouncer
spec:
  containers:
    # Main: PHP application connects to localhost:5432
    - name: api
      image: myapp/api:v1.2.3
      env:
        - name: DATABASE_URL
          value: "pgsql://app:password@localhost:5432/myapp"

    # Ambassador: PgBouncer connection pooler
    - name: pgbouncer
      image: bitnami/pgbouncer:1.21
      ports:
        - containerPort: 5432
      env:
        - name: POSTGRESQL_HOST
          value: "postgres-primary.default.svc.cluster.local"
        - name: POSTGRESQL_PORT
          value: "5432"
        - name: PGBOUNCER_POOL_MODE
          value: "transaction"
        - name: PGBOUNCER_MAX_CLIENT_CONN
          value: "200"
        - name: PGBOUNCER_DEFAULT_POOL_SIZE
          value: "20"
      resources:
        requests:
          cpu: "50m"
          memory: "64Mi"

Типичные Ambassador-прокси

Adapter

Adapter преобразует данные или интерфейс основного контейнера для совместимости с внешними системами.

# Adapter: convert PHP logs format to Prometheus metrics
apiVersion: v1
kind: Pod
metadata:
  name: api-with-adapter
spec:
  containers:
    - name: api
      image: myapp/api:v1.2.3
      volumeMounts:
        - name: metrics
          mountPath: /tmp/metrics

    # Adapter: reads custom metrics file, exposes as Prometheus
    - name: metrics-adapter
      image: prom/statsd-exporter:v0.26
      ports:
        - containerPort: 9102
          name: metrics
      args:
        - "--statsd.mapping-config=/config/mapping.yml"
      volumeMounts:
        - name: adapter-config
          mountPath: /config

  volumes:
    - name: metrics
      emptyDir: {}
    - name: adapter-config
      configMap:
        name: metrics-adapter-config

Operator

Operator -- расширение Kubernetes, которое автоматизирует управление сложными приложениями. Operator следит за Custom Resources и выполняет действия.

                    ┌─────────────────┐
                    │  Custom Resource │
                    │  (CRD)          │
                    │                 │
                    │ spec:           │
                    │   replicas: 3   │
                    │   version: 16   │
                    └────────┬────────┘
                             │ watches
                    ┌────────┴────────┐
                    │    Operator     │
                    │    Controller   │
                    │                 │
                    │ Reconcile loop: │
                    │ observe → diff  │
                    │ → act           │
                    └────────┬────────┘
                             │ manages
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ Pod: PG  │  │ Pod: PG  │  │ Pod: PG  │
        │ Primary  │  │ Replica  │  │ Replica  │
        └──────────┘  └──────────┘  └──────────┘

Популярные операторы

# Using CloudNativePG Operator
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: app-database
spec:
  instances: 3

  postgresql:
    parameters:
      max_connections: "200"
      shared_buffers: "256MB"
      work_mem: "8MB"

  storage:
    size: 50Gi
    storageClass: fast-ssd

  backup:
    barmanObjectStore:
      destinationPath: s3://my-backups/pgdata
      s3Credentials:
        accessKeyId:
          name: s3-creds
          key: ACCESS_KEY_ID
        secretAccessKey:
          name: s3-creds
          key: SECRET_ACCESS_KEY
    retentionPolicy: "30d"

  monitoring:
    enablePodMonitor: true

Когда какой паттерн

Итоги

• Init Container решает задачи подготовки: ожидание зависимостей, миграции, прогрев кэша
• Sidecar расширяет функциональность основного контейнера без изменения его кода
• Ambassador проксирует исходящие соединения (PgBouncer, Envoy)
• Adapter преобразует форматы данных для совместимости с внешними системами
• Operator автоматизирует управление сложными приложениями через CRD и reconciliation loop