Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ctrlplane.dev/llms.txt

Use this file to discover all available pages before exploring further.

A System is the top-level organizational unit in Ctrlplane. It represents a logical grouping of related deployments, environments, and resources.

​
What is a System?

Think of a system as a workspace for a product, platform, or major component of your infrastructure. It contains everything related to deploying that product:
  • Deployments - The services/applications you deploy
  • Environments - Where you deploy (dev, staging, prod)
  • Resources - The infrastructure targets
  • Policies - Rules governing deployments
  • Variables - Configuration values

​
When to Create a System

Create a system when you have: ✅ A product or platform - E.g., “E-commerce Platform”, “Data Pipeline”
✅ Multiple related services - Microservices that work together
✅ Shared deployment policies - Common approval/progression rules
✅ Logical separation - Different teams, security boundaries

​
System Structure

System: E-commerce Platform
├── Deployments
│   ├── API Service
│   ├── Frontend App
│   ├── Payment Service
│   └── Notification Service
├── Environments
│   ├── Development
│   ├── Staging
│   └── Production
├── Resources
│   ├── dev-cluster-1
│   ├── staging-cluster-1
│   ├── prod-cluster-us-east
│   └── prod-cluster-us-west
└── Policies
    ├── Production Approval Required
    └── Environment Progression (Staging → Production)

​
Creating a System

​
Via Web UI

  1. Navigate to your workspace
  2. Click “Create System”
  3. Fill in the form:
    • Name: Display name (e.g., “E-commerce Platform”)
    • Slug: URL-friendly identifier (e.g., “ecommerce-platform”)
    • Description: What this system encompasses

​
Via CLI

# system.yaml
type: System
name: E-commerce Platform
slug: ecommerce-platform
description: Complete e-commerce system including API, frontend, and backend services

ctrlc apply -f system.yaml

​
Full System Configuration

Create a system with deployments and environments in one file: 
# ecommerce-system.yaml
---
type: System
name: E-commerce Platform
slug: ecommerce-platform
description: Complete e-commerce system
---
type: Deployment
name: API Service
slug: api-service
description: Backend API
jobAgent:
  ref: github-actions
---
type: Deployment
name: Frontend App
slug: frontend-app
description: Customer-facing web application
jobAgent:
  ref: github-actions
---
type: Environment
name: Development
description: Development environment
resourceSelector: resource.metadata["environment"] == "development"
---
type: Environment
name: Production
description: Production environment
resourceSelector: resource.metadata["environment"] == "production"

ctrlc apply -f ecommerce-system.yaml

​
System Properties

​
Name

  • Display name shown in the UI
  • Can contain spaces and special characters
  • Can be changed without affecting existing deployments

​
Slug

  • URL-friendly identifier
  • Must be unique within workspace
  • Used in API paths and CLI commands
  • Cannot be changed after creation
  • Format: lowercase letters, numbers, hyphens

​
Description

  • Optional text describing the system’s purpose
  • Supports markdown formatting
  • Displayed in the UI

​
Workspace ID

  • The parent workspace this system belongs to
  • Automatically set when creating a system
  • Cannot be changed

​
Organizing with Multiple Systems

​
When to Use Multiple Systems

Use separate systems when:
  1. Team Boundaries 
    System: Platform Team Services
System: Product Team Services
  2. Security Boundaries 
    System: Public Services
System: Internal Services
System: PCI Compliant Services
  3. Deployment Independence 
    System: Core Platform
System: Analytics Platform
System: ML Platform
  4. Different Policies 
    System: Experimental Features (auto-deploy)
System: Production Services (requires approval)

​
When to Use One System

Keep things in one system when:
  1. Tightly Coupled Services
    • Microservices that must deploy together
    • Services with shared dependencies
  2. Shared Deployment Pipeline
    • Same approval requirements
    • Same environment progression
  3. Single Team/Product
    • One team owns all services
    • Deployed as a unit

​
System-Level Operations

​
Viewing System Status

Get an overview of all deployments in a system: 
ctrlc api get system {systemId} --status
Response: 
systemId: sys_abc123
name: E-commerce Platform
deployments: 4
environments: 3
resources: 8
activeReleases: 12
pendingApprovals: 2
failedJobs: 1

​
Listing All Entities

List Deployments: 
ctrlc api get deployments --system {systemId}
List Environments: 
ctrlc api get environments --system {systemId}
List Policies: 
ctrlc api get policies --system {systemId}

​
Deleting a System

⚠️ Warning: Deleting a system removes all associated deployments, releases, and jobs. This cannot be undone. 
ctrlc api delete system {systemId}

​
Best Practices

​
Naming Conventions

Good Names:
  • ✅ “E-commerce Platform”
  • ✅ “Analytics Pipeline”
  • ✅ “Customer Portal”
Good Slugs:
  • ✅ ecommerce-platform
  • ✅ analytics-pipeline
  • ✅ customer-portal
Avoid:
  • ❌ “System 1”, “Test”, “Prod” (too generic)
  • ❌ My_System, PROD-SYSTEM (inconsistent formatting)

​
Start Simple

Begin with one system for your product: 
System: My Application
  ├── API Deployment
  ├── Frontend Deployment
  ├── Dev Environment
  └── Prod Environment
Split into multiple systems as you grow: 
System: Customer-Facing Services
  ├── API Deployment
  └── Frontend Deployment

System: Internal Services
  ├── Admin API Deployment
  └── Analytics Deployment

​
Documentation

Use the description field to document:
  • Purpose of the system
  • Ownership/team responsible
  • Key dependencies
  • Links to external documentation
Example: 
E-commerce platform for online sales.

Owner: Platform Team
Slack: #platform-team
Docs: https://wiki.company.com/ecommerce

​
Consistent Structure

Maintain consistent structure across systems:
  • Standard environment names (dev, staging, prod)
  • Similar deployment naming patterns
  • Common policy approaches

​
Common Patterns

​
Microservices System

# microservices-system.yaml
---
type: System
name: Microservices Platform
slug: microservices-platform
---
type: Deployment
name: User Service
slug: user-service
jobAgent:
  ref: kubernetes-agent
---
type: Deployment
name: Order Service
slug: order-service
jobAgent:
  ref: kubernetes-agent
---
type: Deployment
name: Payment Service
slug: payment-service
jobAgent:
  ref: kubernetes-agent
---
type: Environment
name: Development
resourceSelector: resource.metadata["environment"] == "development"
---
type: Environment
name: Staging
resourceSelector: resource.metadata["environment"] == "staging"
---
type: Environment
name: Production
resourceSelector: resource.metadata["environment"] == "production"

ctrlc apply -f microservices-system.yaml

​
Multi-Region System

# global-system.yaml
---
type: System
name: Global Application
slug: global-application
---
type: Deployment
name: API Service
slug: api-service
jobAgent:
  ref: kubernetes-agent
---
type: Environment
name: Production US East
resourceSelector: >-
  resource.metadata["environment"] == "production" &&
  resource.metadata["region"] == "us-east-1"
---
type: Environment
name: Production EU West
resourceSelector: >-
  resource.metadata["environment"] == "production" &&
  resource.metadata["region"] == "eu-west-1"

ctrlc apply -f global-system.yaml

​
Monorepo with Multiple Apps

# monorepo-system.yaml
---
type: System
name: Monorepo Applications
slug: monorepo-applications
---
type: Deployment
name: Web App
slug: web-app
jobAgent:
  ref: github-actions
---
type: Deployment
name: Mobile API
slug: mobile-api
jobAgent:
  ref: github-actions
---
type: Deployment
name: Admin Dashboard
slug: admin-dashboard
jobAgent:
  ref: github-actions
---
type: Environment
name: Staging
resourceSelector: resource.metadata["environment"] == "staging"
---
type: Environment
name: Production
resourceSelector: resource.metadata["environment"] == "production"

ctrlc apply -f monorepo-system.yaml

​
Troubleshooting

​
System not appearing in UI

  • Verify system was created successfully
  • Check you’re in the correct workspace
  • Refresh the page

​
Cannot create deployment in system

  • Verify you have permissions for the system
  • Check system ID is correct
  • Ensure deployment slug is unique within system

​
System deletion fails

  • Active releases may prevent deletion
  • Cancel or complete all active releases first
  • Or force delete via API with force=true parameter

​
Next Steps