Kubernetes Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The Kubernetes strategy for the LiveCanvas backend focuses on a modular monolith deployment model where the entire Phoenix application is packaged as a single Elixir release. This approach ensures that every pod in the cluster is identical and capable of handling any type of incoming request, from GraphQL API calls to complex WebRTC media orchestration.
The strategy emphasizes high availability and horizontal scalability by utilizing Elixir's native distribution capabilities (OTP, PubSub, and Presence) within the Kubernetes environment to coordinate state across distributed pods.
Sources: ARCHITECTURE.md:86-93, ARCHITECTURE.md:105-108
Deployment Model
LiveCanvas is deployed as a single Phoenix/Absinthe application. Within the Kubernetes cluster, each pod runs the same container image. This "one deployable per pod" rule simplifies CI/CD pipelines and ensures consistency across the environment.
Pod Capabilities
Every pod in the deployment is configured to serve all application functions:
- GraphQL API: Handling primary client requests and mutations.
- REST Endpoints: Managing webhooks and external callbacks.
- WebSockets: Powering Phoenix Channels for chat, presence, and live session updates.
- Background Jobs: Processing asynchronous tasks.
- Media Orchestration: Running Membrane-based WebRTC flows for live streaming.
Sources: ARCHITECTURE.md:46-46, ARCHITECTURE.md:86-93, ARCHITECTURE.md:213-217
Scaling and Specialization
While the v1 architecture uses homogenous pods, the strategy allows for future specialization. If media stream fanout or latency requires it, the cluster can be expanded with dedicated Selective Forwarding Unit (SFU) or media-specific pods without altering the core domain boundaries of the application.
Sources: ARCHITECTURE.md:98-101, ARCHITECTURE.md:275-278
Cluster Architecture and Coordination
The following diagram illustrates how incoming traffic is distributed across identical pods and how those pods coordinate using Elixir's distributed features.
The diagram shows the Load Balancer distributing traffic to multiple pods, which coordinate ephemeral state via PubSub and Presence while persisting durable data to PostgreSQL.
Sources: ARCHITECTURE.md:46-51, ARCHITECTURE.md:86-93
State Management Strategy
The strategy explicitly differentiates between durable facts that must be persisted and transient state that lives only within the cluster's memory.
| State Category | Storage Mechanism | Examples |
|---|---|---|
| Durable | PostgreSQL | Users, Follows, Posts, Live Session Records, Chat History |
| Ephemeral | OTP / Presence / PubSub | Active participant counts, Countdown timers, Typing indicators |
| Media Binaries | Object Storage | Uploaded images, Video files, Live replays |
Sources: ARCHITECTURE.md:47-50, ARCHITECTURE.md:105-108, ARCHITECTURE.md:183-195
Operational Requirements
Health and Lifecycle
The Kubernetes deployment utilizes standard probes to monitor the health of the Erlang Virtual Machine (BEAM) and its dependencies:
- Liveness Probes: Monitor the internal health of the BEAM.
- Readiness Probes: Ensure the pod has established a connection to PostgreSQL before receiving traffic.
Sources: ARCHITECTURE.md:218-220
Security and Networking
- Realtime Transport: Phoenix Channels (WebSockets) serve as the primary transport for live state and chat.
- Secret Handling: Kubernetes secrets are expected to manage sensitive data, while the application ensures that raw secrets (like token values) are never persisted in the database, only their SHA3-based hashes.
Sources: AGENTS.md:12-12, ARCHITECTURE.md:167-170, ARCHITECTURE.md:203-205
Data Consistency in Distributed Environments
Because multiple pods might attempt to modify data or coordinate live sessions simultaneously, the backend follows a strict "Coordinator" pattern for write paths.
This sequence ensures that side effects (Database and PubSub) are handled by a coordinator to maintain consistency across the cluster.
Sources: ARCHITECTURE.md:73-77, mobile/schema.graphql:59-61
Future Evolution
The Kubernetes strategy is designed to evolve in phases. While V1 focuses on a modular monolith, the underlying infrastructure is prepared for:
- Dedicated Media Pods: Offloading WebRTC processing from API pods.
- Contact Matching Workers: Scaling background job processing for address book imports.
- Observability Scaling: Implementing advanced Telemetry instrumentation for cluster-wide performance monitoring.
Sources: ARCHITECTURE.md:223-230, ARCHITECTURE.md:275-280
The Kubernetes strategy provides a robust foundation for LiveCanvas by leveraging Elixir's inherent strengths in distributed systems while maintaining a simple, manageable deployment profile through the use of identical, multifunctional pods.