> ## 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.

# Systems

> Logical groupings of related deployments and environments

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

```txt theme={null}
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

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

```bash theme={null}
ctrlc apply -f system.yaml
```

### Full System Configuration

Create a system with deployments and environments in one file:

```yaml theme={null}
# 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"
```

```bash theme={null}
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**

   ```txt theme={null}
   System: Platform Team Services
   System: Product Team Services
   ```

2. **Security Boundaries**

   ```txt theme={null}
   System: Public Services
   System: Internal Services
   System: PCI Compliant Services
   ```

3. **Deployment Independence**

   ```txt theme={null}
   System: Core Platform
   System: Analytics Platform
   System: ML Platform
   ```

4. **Different Policies**

   ```txt theme={null}
   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:

```bash theme={null}
ctrlc api get system {systemId} --status
```

**Response**:

```yaml theme={null}
systemId: sys_abc123
name: E-commerce Platform
deployments: 4
environments: 3
resources: 8
activeReleases: 12
pendingApprovals: 2
failedJobs: 1
```

### Listing All Entities

**List Deployments**:

```bash theme={null}
ctrlc api get deployments --system {systemId}
```

**List Environments**:

```bash theme={null}
ctrlc api get environments --system {systemId}
```

**List Policies**:

```bash theme={null}
ctrlc api get policies --system {systemId}
```

### Deleting a System

⚠️ **Warning**: Deleting a system removes all associated deployments, releases, and jobs. This cannot be undone.

```bash theme={null}
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

```yaml theme={null}
# 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"
```

```bash theme={null}
ctrlc apply -f microservices-system.yaml
```

### Multi-Region System

```yaml theme={null}
# 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"
```

```bash theme={null}
ctrlc apply -f global-system.yaml
```

### Monorepo with Multiple Apps

```yaml theme={null}
# 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"
```

```bash theme={null}
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](./resources) - Define deployment targets
* [Environments](./environments) - Create deployment stages
* [Deployments](./deployments) - Set up your first deployment