Systems

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

Navigate to your workspace
Click “Create System”
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:

Team Boundaries

System: Platform Team Services
System: Product Team Services

Security Boundaries

System: Public Services
System: Internal Services
System: PCI Compliant Services

Deployment Independence

System: Core Platform
System: Analytics Platform
System: ML Platform

Different Policies

System: Experimental Features (auto-deploy)
System: Production Services (requires approval)

When to Use One System

Keep things in one system when:

Tightly Coupled Services
- Microservices that must deploy together
- Services with shared dependencies
Shared Deployment Pipeline
- Same approval requirements
- Same environment progression
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

Resources - Define deployment targets
Environments - Create deployment stages
Deployments - Set up your first deployment

Introduction

Deployment

Infrastructure

Workspace

Concepts

What is a System?

When to Create a System

System Structure

Creating a System

Via Web UI

Via CLI

Full System Configuration

System Properties

Name

Slug

Description

Workspace ID

Organizing with Multiple Systems

When to Use Multiple Systems

When to Use One System

System-Level Operations

Viewing System Status

Listing All Entities

Deleting a System

Best Practices

Naming Conventions

Start Simple

Documentation

Consistent Structure

Common Patterns

Microservices System

Multi-Region System

Monorepo with Multiple Apps

Troubleshooting

System not appearing in UI

Cannot create deployment in system

System deletion fails

Next Steps

​What is a System?

​When to Create a System

​System Structure

​Creating a System

​Via Web UI

​Via CLI

​Full System Configuration

​System Properties

​Name

​Slug

​Description

​Workspace ID

​Organizing with Multiple Systems

​When to Use Multiple Systems

​When to Use One System

​System-Level Operations

​Viewing System Status

​Listing All Entities

​Deleting a System

​Best Practices

​Naming Conventions

​Start Simple

​Documentation

​Consistent Structure

​Common Patterns

​Microservices System

​Multi-Region System

​Monorepo with Multiple Apps

​Troubleshooting

​System not appearing in UI

​Cannot create deployment in system

​System deletion fails

​Next Steps

What is a System?

When to Create a System

System Structure

Creating a System

Via Web UI

Via CLI

Full System Configuration

System Properties

Name

Slug

Description

Workspace ID

Organizing with Multiple Systems

When to Use Multiple Systems

When to Use One System

System-Level Operations

Viewing System Status

Listing All Entities

Deleting a System

Best Practices

Naming Conventions

Start Simple

Documentation

Consistent Structure

Common Patterns

Microservices System

Multi-Region System

Monorepo with Multiple Apps

Troubleshooting

System not appearing in UI

Cannot create deployment in system

System deletion fails

Next Steps