Skip to content

Spike: Architecture Blueprint for Security Policies v2

Architecture Blueprint for Security Policies v2

Objective

Create a comprehensive architecture blueprint for API-first Security Policy management that will serve as the foundation for the PoC implementation.

Deliverables

Architecture Blueprint

Complete technical design document including:

  • Database schema for policies as first-class entities
  • API specification (OpenAPI/Swagger)
  • Policy reference system design
  • Optional Git synchronization architecture
  • Scope separation model
  • Performance optimization strategy for 100k+ projects

Task Breakdown

Task 1: Architecture Blueprint & Database Design (5 days)

Owner: @alan @mcavoj Deliverables:

  • Complete architecture document with diagrams
  • Database schema (migrations ready)
  • API specification (OpenAPI format)
  • Performance benchmarking plan
  • Policy reference system specification

PoC Component: Database schema implementation with sample data

Architecture Blueprint Requirements

Core Components

  1. Policy Entity Model

    - id (UUID)
- organization_id
- name
- description
- policy_type
- configuration (JSONB)
- version
- created_by
- created_at, updated_at
- status (active/draft/archived)

  2. Policy Application Model

    - id
- policy_id
- target_type (project/group)
- target_id
- applied_by
- applied_at
- status

  3. API Endpoints

    GET    /api/v4/organizations/:id/policies
POST   /api/v4/organizations/:id/policies
GET    /api/v4/organizations/:id/policies/:policy_id
PUT    /api/v4/organizations/:id/policies/:policy_id
DELETE /api/v4/organizations/:id/policies/:policy_id

POST   /api/v4/projects/:id/policy_applications
GET    /api/v4/projects/:id/policy_applications
DELETE /api/v4/projects/:id/policy_applications/:app_id

Performance Targets for PoC Validation

  • Organization policy list: <100ms for 5000 policies
  • Policy application query: <50ms for 100k projects
  • Policy reference resolution: <10ms

Success Criteria

  • Blueprint Completeness: Architecture supports all foundation phase requirements
  • Database Design: Schema ready for implementation with migrations
  • API Specification: Complete OpenAPI documentation
  • Performance Strategy: Clear optimization approach documented
  • Migration Path: Clear path from current SPP model to new architecture documented

Technical Validation Points

  1. Database Performance: Query optimization for organization-wide policy views
  2. API Design: RESTful patterns that scale to multiple policy types
  3. Reference System: Policy linking works like issue/MR references
  4. Scope Flexibility: Project owners can apply policies without modification rights
  5. Git Sync: Background synchronization doesn't impact API performance

Key Architectural Decisions to Document

Cells & Sharding Strategy

  • Use organization_id as sharding key for security_policies
  • Make security_policy_management_project_id nullable
  • Add dual sharding key on both columns
  • Make security_orchestration_policy_configuration_id nullable for org-level policies

PORO Refactor Dependency

  • Policy type-specific data access layer needed
  • Abstract away YAML-specific logic
  • Create type-specific PORO classes (e.g., Security::Policy::PipelineExecution)
  • Migrate code from direct YAML hash access to read model

Policy Configuration vs Enforcement

  • Part 1: Policy Configuration - Where and how policies are set up (focus of v2)
  • Part 2: Policy Enforcement - How policies are applied (separate track)

Related Issues

  • PoC Implementation: #[to be created]
  • PORO Refactor: #504305

Timeline

Estimated Duration: 5 days

References

Edited by Alan (Maciej) Paruszewski