PlasmaCloud

A modern, multi-tenant cloud infrastructure platform built in Rust

PlasmaCloud provides a complete cloud computing stack with strong tenant isolation, role-based access control (RBAC), and seamless integration between compute, networking, and storage services.

MVP-Beta Status: COMPLETE ✅

The MVP-Beta milestone validates end-to-end tenant isolation and core infrastructure provisioning:

• ✅ IAM: User authentication, RBAC, multi-tenant isolation
• ✅ NovaNET: VPC overlay networking with tenant boundaries
• ✅ PlasmaVMC: VM provisioning with network attachment
• ✅ Integration: E2E tests validate complete tenant path

Test Results: 8/8 integration tests passing

• IAM: 6/6 tenant path tests
• Network+VM: 2/2 integration tests

Quick Start

Get Started in 3 Steps

1. Deploy the Platform

   # Start IAM service
   cd iam && cargo run --bin iam-server -- --port 50080
   
   # Start NovaNET service
   cd novanet && cargo run --bin novanet-server -- --port 50081
   
   # Start PlasmaVMC service
   cd plasmavmc && cargo run --bin plasmavmc-server -- --port 50082
   

2. Onboard Your First Tenant

   # Create user, provision network, deploy VM
   # See detailed guide below
   

3. Verify End-to-End

   # Run integration tests
   cd iam && cargo test --test tenant_path_integration
   cd plasmavmc && cargo test --test novanet_integration -- --ignored
   

For detailed instructions: Tenant Onboarding Guide

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     User / API Client                        │
└─────────────────────────────────────────────────────────────┘
                            │
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  IAM (Identity & Access Management)                         │
│  • User authentication & JWT tokens                         │
│  • RBAC with hierarchical scopes (Org → Project)            │
│  • Cross-tenant access denial                               │
└─────────────────────────────────────────────────────────────┘
                            │
              ┌─────────────┴─────────────┐
              ↓                           ↓
┌──────────────────────┐     ┌──────────────────────┐
│      NovaNET         │     │      PlasmaVMC       │
│  • VPC overlay       │────▶│  • VM provisioning   │
│  • Subnets + DHCP    │     │  • Hypervisor mgmt   │
│  • Ports (IP/MAC)    │     │  • Network attach    │
│  • Security Groups   │     │  • KVM, Firecracker  │
└──────────────────────┘     └──────────────────────┘

Full Architecture: MVP-Beta Tenant Path Architecture

Core Components

IAM (Identity & Access Management)

Location: /iam

Multi-tenant identity and access management with comprehensive RBAC.

Features:

• User and service account management
• Hierarchical scopes: System → Organization → Project
• Custom role creation with fine-grained permissions
• Policy evaluation with conditional logic
• JWT token issuance with tenant claims

Services:

• IamAdminService: User, role, and policy management
• IamAuthzService: Authorization and permission checks
• IamTokenService: Token issuance and validation

Quick Start:

cd iam
cargo build --release
cargo run --bin iam-server -- --port 50080

NovaNET (Network Virtualization)

Location: /novanet

VPC-based overlay networking with tenant isolation.

Features:

• Virtual Private Cloud (VPC) provisioning
• Subnet management with CIDR allocation
• Port allocation with IP/MAC assignment
• DHCP server integration
• Security group enforcement
• OVN integration for production networking

Services:

• VpcService: VPC lifecycle management
• SubnetService: Subnet CRUD operations
• PortService: Port allocation and attachment
• SecurityGroupService: Firewall rule management

Quick Start:

cd novanet
export IAM_ENDPOINT=http://localhost:50080
cargo build --release
cargo run --bin novanet-server -- --port 50081

PlasmaVMC (VM Provisioning & Management)

Location: /plasmavmc

Virtual machine lifecycle management with hypervisor abstraction.

Features:

• VM provisioning with tenant scoping
• Hypervisor abstraction (KVM, Firecracker)
• Network attachment via NovaNET ports
• CPU, memory, and disk configuration
• VM metadata persistence (ChainFire)
• Live migration support (planned)

Services:

• VmService: VM lifecycle (create, start, stop, delete)

Quick Start:

cd plasmavmc
export NOVANET_ENDPOINT=http://localhost:50081
export IAM_ENDPOINT=http://localhost:50080
cargo build --release
cargo run --bin plasmavmc-server -- --port 50082

Future Components (Roadmap)

FlashDNS (DNS Service)

Status: Planned for next milestone

DNS resolution within tenant VPCs with automatic record creation.

Features (Planned):

• Tenant-scoped DNS zones
• Automatic hostname assignment for VMs
• DNS record lifecycle tied to resources
• Integration with NovaNET for VPC resolution

FiberLB (Load Balancing)

Status: Planned for next milestone

Layer 4/7 load balancing with tenant isolation.

Features (Planned):

• Load balancer provisioning within VPCs
• Backend pool management (VM targets)
• VIP allocation from tenant subnets
• Health checks and failover

LightningStor (Block Storage)

Status: Planned for next milestone

Distributed block storage with snapshot support.

Features (Planned):

• Volume creation and attachment to VMs
• Snapshot lifecycle management
• Replication and high availability
• Integration with ChainFire for immutable logs

Testing

Integration Test Suite

PlasmaCloud includes comprehensive integration tests validating the complete E2E tenant path.

IAM Tests (6 tests, 778 LOC):

cd iam
cargo test --test tenant_path_integration

# Tests:
# ✅ test_tenant_setup_flow
# ✅ test_cross_tenant_denial
# ✅ test_rbac_project_scope
# ✅ test_hierarchical_scope_inheritance
# ✅ test_custom_role_fine_grained_permissions
# ✅ test_multiple_role_bindings

Network + VM Tests (2 tests, 570 LOC):

cd plasmavmc
cargo test --test novanet_integration -- --ignored

# Tests:
# ✅ novanet_port_attachment_lifecycle
# ✅ test_network_tenant_isolation

Coverage: 8/8 tests passing (100% success rate)

See E2E Test Documentation for detailed test descriptions.

Documentation

Getting Started

• Tenant Onboarding Guide: Complete walkthrough of deploying your first tenant

Architecture

• MVP-Beta Tenant Path: Complete system architecture with diagrams
• Component Integration: How services communicate

Testing & Validation

• E2E Test Documentation: Comprehensive test suite description
• T023 Summary: MVP-Beta deliverables and test results

Component Specifications

• IAM Specification
• NovaNET Specification
• PlasmaVMC Specification

Tenant Isolation Model

PlasmaCloud enforces tenant isolation at three layers:

Layer 1: IAM Policy Enforcement

Every API call is validated against the user's JWT token:

• Token includes org_id and project_id claims
• Resources are scoped as: org/{org_id}/project/{project_id}/{resource_type}/{id}
• RBAC policies enforce: resource.org_id == token.org_id
• Cross-tenant access results in 403 Forbidden

Layer 2: Network VPC Isolation

Each VPC provides a logical network boundary:

• VPC scoped to an org_id
• OVN overlay ensures traffic isolation between VPCs
• Different tenants can use the same CIDR without collision
• Security groups provide intra-VPC firewall rules

Layer 3: VM Scoping

Virtual machines are scoped to tenant organizations:

• VM metadata includes org_id and project_id
• VMs can only attach to ports in their tenant's VPC
• VM operations filter by token scope
• Hypervisor isolation ensures compute boundary

Validation: All three layers tested in cross-tenant denial tests.

Example Workflow

Create a Tenant with Network and VM

# 1. Authenticate and get token
grpcurl -plaintext -d '{
  "principal_id": "alice",
  "org_id": "acme-corp",
  "project_id": "project-alpha"
}' localhost:50080 iam.v1.IamTokenService/IssueToken

export TOKEN="<your-token>"

# 2. Create VPC
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" -d '{
  "org_id": "acme-corp",
  "project_id": "project-alpha",
  "name": "main-vpc",
  "cidr": "10.0.0.0/16"
}' localhost:50081 novanet.v1.VpcService/CreateVpc

export VPC_ID="<vpc-id>"

# 3. Create Subnet
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" -d '{
  "org_id": "acme-corp",
  "project_id": "project-alpha",
  "vpc_id": "'$VPC_ID'",
  "name": "web-subnet",
  "cidr": "10.0.1.0/24",
  "gateway": "10.0.1.1",
  "dhcp_enabled": true
}' localhost:50081 novanet.v1.SubnetService/CreateSubnet

export SUBNET_ID="<subnet-id>"

# 4. Create Port
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" -d '{
  "org_id": "acme-corp",
  "project_id": "project-alpha",
  "subnet_id": "'$SUBNET_ID'",
  "name": "vm-port",
  "ip_address": "10.0.1.10"
}' localhost:50081 novanet.v1.PortService/CreatePort

export PORT_ID="<port-id>"

# 5. Create VM with Network
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" -d '{
  "name": "web-server-1",
  "org_id": "acme-corp",
  "project_id": "project-alpha",
  "spec": {
    "network": [{
      "id": "eth0",
      "port_id": "'$PORT_ID'"
    }]
  }
}' localhost:50082 plasmavmc.v1.VmService/CreateVm

Full walkthrough: See Tenant Onboarding Guide

Development

Prerequisites

• Rust 1.70+ with Cargo
• Protocol Buffers compiler (protoc)
• Optional: KVM for real VM execution
• Optional: OVN for production networking

Build from Source

# Clone repository
git clone https://github.com/your-org/plasmacloud.git
cd cloud

# Initialize submodules
git submodule update --init --recursive

# Build all components
cd iam && cargo build --release
cd ../novanet && cargo build --release
cd ../plasmavmc && cargo build --release

Run Tests

# IAM tests
cd iam && cargo test --test tenant_path_integration

# Network + VM tests
cd plasmavmc && cargo test --test novanet_integration -- --ignored

# Unit tests (all components)
cargo test

Project Structure

cloud/
├── iam/                    # Identity & Access Management
│   ├── crates/
│   │   ├── iam-api/       # gRPC services
│   │   ├── iam-authz/     # Authorization engine
│   │   ├── iam-store/     # Data persistence
│   │   └── iam-types/     # Core types
│   └── tests/
│       └── tenant_path_integration.rs  # E2E tests
│
├── novanet/               # Network Virtualization
│   ├── crates/
│   │   ├── novanet-server/    # gRPC services
│   │   ├── novanet-api/       # Protocol buffers
│   │   ├── novanet-metadata/  # Metadata store
│   │   └── novanet-ovn/       # OVN integration
│   └── proto/
│
├── plasmavmc/             # VM Provisioning
│   ├── crates/
│   │   ├── plasmavmc-server/      # VM service
│   │   ├── plasmavmc-api/         # Protocol buffers
│   │   ├── plasmavmc-hypervisor/  # Hypervisor abstraction
│   │   ├── plasmavmc-kvm/         # KVM backend
│   │   └── plasmavmc-firecracker/ # Firecracker backend
│   └── tests/
│       └── novanet_integration.rs  # E2E tests
│
├── flashdns/              # DNS Service (planned)
├── fiberlb/               # Load Balancing (planned)
├── lightningstor/         # Block Storage (planned)
│
├── chainfire/             # Immutable event log (submodule)
├── flaredb/               # Distributed metadata store (submodule)
│
├── docs/
│   ├── architecture/      # Architecture docs
│   ├── getting-started/   # Onboarding guides
│   └── por/               # Plan of Record (POR) docs
│       └── T023-e2e-tenant-path/  # MVP-Beta deliverables
│
├── specifications/        # Component specifications
└── README.md             # This file

Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository and create a feature branch
2. Write tests for new functionality
3. Update documentation as needed
4. Run tests before submitting PR: cargo test
5. Follow Rust style: Use cargo fmt and cargo clippy

Code Review Process

1. All PRs require at least one approval
2. CI must pass (tests, formatting, lints)
3. Documentation must be updated for user-facing changes
4. Integration tests required for new features

License

PlasmaCloud is licensed under the Apache License 2.0. See LICENSE for details.

Support & Community

• GitHub Issues: Report bugs or request features
• Documentation: See docs/ for detailed guides
• Architecture: Review architecture docs for design decisions

Roadmap

Completed (MVP-Beta) ✅

• IAM with RBAC and tenant scoping
• NovaNET VPC overlay networking
• PlasmaVMC VM provisioning
• End-to-end integration tests
• Comprehensive documentation

In Progress

• FlashDNS integration (S3)
• FiberLB integration (S4)
• LightningStor integration (S5)

Planned

• FlareDB persistence for production
• ChainFire integration for VM metadata
• OVN production deployment
• Kubernetes integration
• Terraform provider
• Web UI / Dashboard

Acknowledgments

PlasmaCloud builds upon:

• ChainFire: Immutable event log for audit trails
• FlareDB: Distributed metadata store
• OVN (Open Virtual Network): Production-grade overlay networking
• gRPC: High-performance RPC framework
• Rust: Safe, concurrent systems programming

---

Status: MVP-Beta Complete ✅ Last Updated: 2025-12-09 Next Milestone: FlashDNS, FiberLB, LightningStor integration

For detailed information, see:

• Tenant Onboarding Guide
• Architecture Documentation
• Test Documentation