Kubernetes & Cloud Infrastructure
Relevant source files
The following files were used as context for generating this wiki page:
The Kubernetes and Cloud Infrastructure for the X3 Chain project provides a resilient, scalable environment for blockchain nodes, indexers, and supporting services. It leverages Kubernetes (k8s) for container orchestration, ensuring high availability (HA) for the indexer and stateful management for validators and databases. The infrastructure is designed to support mainnet operations through automated deployment scripts, health monitoring, and persistent storage management.
Sources: scripts/k8s-deploy.sh:1-122, plans/PHASE_5_IMPLEMENTATION_PLAN.md:14-20
Infrastructure Components and Architecture
The X3 Chain infrastructure is composed of several critical layers, ranging from the core blockchain nodes to the monitoring and indexing services. The deployment is partitioned into a dedicated x3-chain namespace to isolate resources and simplify management.
Component Overview
| Component | Resource Type | Purpose |
|---|---|---|
| Validators | StatefulSet | Core blockchain nodes responsible for consensus and block production. |
| Indexer | Deployment (HA) | Off-chain data processing and GraphQL API provisioning. |
| Database | StatefulSet | Persistent storage for indexed data using PostgreSQL. |
| Relayer | Service | Cross-chain message passing and proof submission. |
| Monitoring | Prometheus/Grafana | Real-time metrics collection and visualization. |
Sources: scripts/k8s-deploy.sh:111-120, crates/x3-relayer/PHASE_13F_MASTER_INDEX.md:104-114, plans/Off-Chain-Assets-Audit-Blockchain-Integration-Epic-Plan.md:12-18
Deployment Logic Flow
The deployment process follows a strict order of operations to satisfy service dependencies, particularly ensuring storage and configurations are available before booting stateful applications.
The flow diagram above illustrates the sequential application of Kubernetes manifests as defined in the deployment script.
Sources: scripts/k8s-deploy.sh:45-66
Kubernetes Deployment Management
The primary interface for managing the infrastructure is the k8s-deploy.sh script. This utility handles the lifecycle of the cluster resources, including application, deletion, and status reporting.
Key Deployment Features
- Namespace Isolation: All resources are contained within the
x3-chainnamespace. - Stateful Management: Validators and PostgreSQL utilize StatefulSets to ensure persistent identity and stable storage via PVCs.
- High Availability: The Indexer is deployed with multiple replicas to ensure API availability.
- Health Verification: The deployment script includes wait loops that timeout after 5 minutes for validators and 2 minutes for indexers to ensure services reach a "Running" state.
Sources: scripts/k8s-deploy.sh:11-15, scripts/k8s-deploy.sh:68-80, scripts/k8s-deploy.sh:120-125
Networking and Access Points
Internal and external communication is managed through Kubernetes Services, providing stable DNS names for internal service discovery and LoadBalancers for external access.
| Service | Internal DNS | External Access | Port |
|---|---|---|---|
| Validator P2P | x3-validators.x3-chain | Headless (Internal) | N/A |
| Validator RPC | x3-validator-rpc.x3-chain | LoadBalancer | 9933 |
| Indexer API | x3-indexer-internal.x3-chain | LoadBalancer (GraphQL) | 4000 |
| PostgreSQL | postgres.x3-chain | ClusterIP (Internal) | 5432 |
Sources: scripts/k8s-deploy.sh:128-135
Monitoring and Operational Readiness
Infrastructure health is monitored through an integrated stack of Prometheus and Grafana, which tracks performance baselines and triggers alerts for critical incidents.
Performance Baselines
The infrastructure is tuned to maintain specific performance targets for mainnet operations:
- EVM Block Polling: 4-5 blocks per minute.
- SVM Slot Polling: 8-10 slots per minute.
- Proof Submission: 2-4 proofs per minute.
- Resource Limits: CPU utilization should target <70%, and memory should remain <500MB (for relayers) or as defined by the specific node type.
Sources: crates/x3-relayer/PHASE_13F_MASTER_INDEX.md:160-170, crates/x3-relayer/PHASE_13F_CROSS_REFERENCE_GUIDE.md:120-130
Incident Response Flow
When failures occur within the Kubernetes environment, the operations team follows a cross-referenced escalation path.
The sequence diagram shows the interaction between monitoring tools, human operators, and the Kubernetes orchestration layer during an infrastructure incident.
Sources: crates/x3-relayer/PHASE_13F_MASTER_INDEX.md:214-240, scripts/k8s-deploy.sh:82-110
Infrastructure Security and Hardening
The mainnet launch requires a finalized security posture for the cloud environment.
Hardening Checklist
- Secret Management: No private keys or secrets are stored in version control; they are applied via Kubernetes Secrets.
- RBAC: Access is controlled via
kubectland namespace-level permissions. - Genesis Security: For mainnet, dev-seed accounts (e.g., Alice, Bob) are removed from the chain spec, and the sudo key is either disabled or moved to a multi-signature authority.
- Audit Gates: Infrastructure must pass a 90-item validation checklist before mainnet genesis, covering build reproducibility and disaster recovery.
Sources: MAINNET_LAUNCH_CHECKLIST.md:15-20, MAINNET_LAUNCH_CHECKLIST.md:150-165, crates/x3-relayer/PHASE_13F_COMPLETION_DECLARATION.md:25-35
Conclusion
The X3 Chain Kubernetes and Cloud Infrastructure serves as the backbone for the project's decentralized operations. By utilizing automated orchestration, stateful management for critical data, and a robust monitoring framework, the system ensures that validators and indexers can maintain high uptime and performance consistent with mainnet requirements. Continuous validation through "war game" exercises and infrastructure checklists ensures the environment remains resilient against both hardware failures and network anomalies.