Quick start guide and introduction to Blazing Core Compose

Getting Started


**Blazing Core** is our multi-cloud, policy-driven orchestration service that enables you to describe compute workloads once and deploy them transparently across multiple cloud providers.

## What is Core Compose?

**Core Compose** is the YAML configuration format used by Blazing Core. It merges the simplicity of Docker Compose with the power of declarative cloud infrastructure. Write your infrastructure once in a `compose.yaml` file, and Blazing Core handles provider selection, placement, networking, security, and compliance automatically.

### Supported Providers

- **GCP GKE** - Google Kubernetes Engine
- **Akash Network** - Decentralized compute network
- **Digital Frontier Cloud (DFC)** - Managed cloud infrastructure

#### Coming Soon

- **AWS EKS** - Amazon Elastic Kubernetes Service
- **Azure AKS** - Azure Kubernetes Service

## Key Features

### Declarative Configuration

Define your entire infrastructure in a single `compose.yaml` file:

```yaml filename="compose.yaml"
version: "0.2"

services:
  api:
    image: myapp:latest
    cpu: 2
    memory: "4Gi"
    replicas: 3
    network:
      ingress:
        expose:
          - port: 443
            tls:
              auto: true
```

### Intelligent Provider Selection

Blazing Core automatically selects the best provider based on your requirements:

- **Cost optimization** - Lowest price for your workload
- **Performance** - Best latency and throughput
- **Compliance** - Data residency and regulatory requirements
- **Availability** - High availability with automatic failover

### Policy-Driven Governance

Enforce compliance and security policies across all deployments:

```yaml
services:
  api:
    image: myapp:latest
    controls: [PCI-DSS-4.0, DATA-RESIDENCY-EU]
    placement:
      residency:
        require_countries: ["PT", "FR", "ES"]
```

### Automatic Scaling

Built-in autoscaling with CPU, memory, and custom metrics:

```yaml
services:
  api:
    autoscaling:
      enabled: true
      min_replicas: 2
      max_replicas: 20
      target_cpu_percent: 70
```

### GPU Support

First-class GPU support with topology awareness:

```yaml
services:
  trainer:
    gpu:
      count: 4
      model: "H100"
      sharing:
        mode: mig
        mig_profile: "3g.40gb"
```

### Secrets Management

Secure secrets injection with automatic rotation:

```yaml
services:
  api:
    secrets:
      - secret_ref: db-credentials
        mode: env
        keys:
          username: DB_USER
          password: DB_PASSWORD
```

## Core Concepts

### Services

The smallest deployable unit - a container with compute resources, networking, and policies.

### Profiles

Reusable configuration templates that can be applied to multiple services:

```yaml
profiles:
  production:
    replicas: 3
    autoscaling:
      enabled: true
    observability:
      metrics:
        enabled: true

services:
  api:
    profiles: [production]
```

### Sovereignty

Define organization-wide sovereignty policies that control where and how your workloads run:

```yaml
policy:
  placement:
    residency:
      require_countries: ["PT", "FR", "ES", "DE"]
  security:
    confidential_compute: preferred
```

### Governance & Compliance

Blazing Core includes feature registry and compliance controls that validate deployments:

- **Feature Registry** - Tracks available capabilities per provider
- **Control Registry** - Maps compliance requirements to technical controls

## How It Works

### 1. Write Your Configuration

Create a `compose.yaml` file describing your infrastructure.

### 2. Validate

Run `core validate` to check syntax and compliance locally:

```bash
core validate compose.yaml
```

### 3. Plan

Preview what will be deployed:

```bash
core plan compose.yaml
```

Blazing Core shows:
- Selected provider and fallback chain
- Estimated cost
- Compliance status
- Resource allocation

### 4. Apply

Deploy your infrastructure:

```bash
core apply compose.yaml
```

The Control Plane API:
- Runs placement algorithms
- Provisions resources atomically
- Returns deployment status and audit trail

## Architecture

### Client-Side (CLI)

- **Validation** - Fast local syntax and schema checking
- **Display** - Shows deployment intent and results

### Server-Side (Control Plane API)

- **Placement** - Intelligent provider and region selection
- **Provisioning** - Atomic resource creation
- **Orchestration** - Handles async operations
- **Auditing** - Complete deployment history

This **server-side intelligence** architecture ensures:
- Consistent placement across all interfaces (CLI, Web UI, mobile)
- Real-time provider availability and pricing
- Atomic operations (all resources created or none)
- Crash recovery (server continues if client disconnects)

## Use Cases

### Multi-Cloud Deployment

Deploy the same workload across multiple clouds for redundancy:

```yaml
placement:
  strategy:
    mode: high_availability
    providers: [GCP, Akash, DFC]
```

### Data Residency Compliance

Ensure data stays within specific countries:

```yaml
placement:
  residency:
    require_countries: ["PT", "FR"]
network:
  egress:
    lock_country: true
```

### Cost Optimization

Automatically select the cheapest provider:

```yaml
placement:
  strategy:
    mode: cost_optimized
    max_cost_per_month: 500
```

### GPU Workloads

Run ML training with GPU slicing:

```yaml
services:
  trainer:
    gpu:
      count: 1
      model: "A100"
      sharing:
        mode: mig
        mig_profile: "2g.20gb"
```

## Getting Started

Ready to deploy your first workload? Check out the [Quick Start](/docs/quick-start) guide.

## Learn More

- [Architecture](/docs/architecture) - Understand how Blazing Core works
- [Service Configuration](/docs/service-basics) - Configure your services and workloads
- [Provider Capabilities](/docs/overview) - Compare provider features
- [Governance & Compliance](/docs/features-and-controls) - Features and controls


Multi-cloud orchestration with policy-driven deployment

Blazing Core Introduction


## Prerequisites

- A Digital Frontier account
- Core CLI installed

## Installation

### macOS

```bash
brew install blazing-cli
```

### Linux

```bash
curl -fsSL https://get.digitalfrontier.so/core | sh
```

### Verify Installation

```bash
core --version
```

## Initialize Your Project

Create a new project directory:

```bash
mkdir my-app && cd my-app
core init
```

This creates a basic `compose.yaml` file.

## Your First Service

Edit `compose.yaml` to define a simple web service:

```yaml
version: "0.2"

services:
  web:
    image: nginx:latest
    cpu: 1
    memory: "2Gi"
    replicas: 2

    network:
      ingress:
        expose:
          - port: 80
            protocol: http
```

## Validate Your Configuration

Check for errors:

```bash
core validate
```

You should see:

```
✓ Schema validation passed
✓ Feature validation passed
✓ No compliance issues
```

## Preview the Deployment

See what will be deployed:

```bash
core plan
```

Output:

```
⚙ Running core plan...

Provider Selection:
  Primary: GCP (cost-optimized)
  Fallback: [Akash, DFC]

Resources:
  ✓ Service: web (2 replicas)
  ✓ Load Balancer: HTTP (port 80)
  ✓ Auto-scaling: disabled

Estimated Cost: $12/month ± 10%

✓ Plan successful
```

## Deploy

Apply your configuration:

```bash
core apply
```

Output:

```
⚙ Deploying...
  ✓ Creating service: web
  ✓ Provisioning load balancer
  ✓ Starting replicas (2/2)

✅ Deployment successful

Service URL: http://web-a3d5.df.app
Status: https://console.digitalfrontier.so/deployments/df-20251203-00123
```

## Check Status

View your deployment:

```bash
core status
```

## Update Your Service

Let's add HTTPS and autoscaling. Edit `compose.yaml`:

```yaml
version: "0.2"

services:
  web:
    image: nginx:latest
    cpu: 1
    memory: "2Gi"

    # Add autoscaling
    autoscaling:
      enabled: true
      min_replicas: 2
      max_replicas: 10
      target_cpu_percent: 70

    network:
      ingress:
        expose:
          - port: 443
            protocol: https
            tls:
              auto: true  # Automatic TLS certificates
```

Apply the changes:

```bash
core apply
```

Blazing Core will:
1. Provision TLS certificates automatically
2. Update the load balancer to HTTPS
3. Enable autoscaling (2-10 replicas)

## Add a Database

Let's add a PostgreSQL database. Update `compose.yaml`:

```yaml
version: "0.2"

services:
  web:
    image: nginx:latest
    cpu: 1
    memory: "2Gi"
    autoscaling:
      enabled: true
      min_replicas: 2
      max_replicas: 10
      target_cpu_percent: 70
    network:
      ingress:
        expose:
          - port: 443
            protocol: https
            tls:
              auto: true
    # Reference database credentials
    secrets:
      - secret_ref: db-credentials
        mode: env
        keys:
          host: DB_HOST
          username: DB_USER
          password: DB_PASSWORD

  db:
    image: postgres:15
    cpu: 2
    memory: "4Gi"
    replicas: 1
    storage:
      - mount_path: /var/lib/postgresql/data
        size: "50Gi"
        persistent: true
    network:
      ingress:
        expose:
          - port: 5432
            protocol: tcp
            internal_only: true  # Not exposed to internet
```

Create the database secret:

```bash
core secrets create db-credentials \
  --type db-credentials \
  --data host=db.internal \
  --data username=appuser \
  --data password=your-secure-password
```

Apply:

```bash
core apply
```

## Clean Up

Remove all resources:

```bash
core destroy
```

Confirm when prompted.

## Next Steps

### Learn Core Concepts

- [Services](/docs/service-basics) - Understanding service configuration
- [Architecture](/docs/architecture) - Core platform architecture
- [Organizational Hierarchy](/docs/organizational-hierarchy) - Teams and projects

### Advanced Features

- [Autoscaling](/docs/autoscaling) - Scale based on metrics
- [Multi-Cloud](/docs/overview) - Deploy across clouds
- [Deployment Lifecycle](/docs/deployment-lifecycle) - Manage deployments

### Providers

- [GCP Provider](/docs/gcp-provider) - Deploy to Google Cloud
- [DFC Provider](/docs/dfc-provider) - Digital Frontier Cloud
- [Akash Provider](/docs/akash-provider) - Decentralized compute

## Common Commands

| Command | Description |
|---------|-------------|
| `core init` | Initialize a new project |
| `core validate` | Validate configuration locally |
| `core plan` | Preview deployment changes |
| `core apply` | Deploy infrastructure |
| `core status` | Check deployment status |
| `core logs` | View service logs |
| `core destroy` | Delete all resources |

## Getting Help

- [Documentation](/docs) - Complete reference
- [Discord Community](https://discord.gg/blazing) - Get support
- [Email Support](mailto:admin@blazing.work) - Contact us

## Example Projects

Browse complete examples:

- **Simple Web App** - Basic HTTP service
- **API with Database** - REST API + PostgreSQL
- **ML Training** - GPU workload with autoscaling
- **Microservices** - Multi-service application
- **Multi-Cloud HA** - High-availability deployment

Find examples at [github.com/digitalfrontier/core-compose-examples](https://github.com/digitalfrontier/core-compose-examples)


Deploy your first Blazing Core workload in 5 minutes

Blazing Core Quick Start


Blazing Core Compose follows semantic versioning for both the API and documentation. This guide explains how to navigate different versions and maintain compatibility.

## Current Version

**Latest Stable**: v0.2.0 (December 2025)

This documentation reflects **v0.2.0** of the Core Compose specification.

## Version Format

Blazing uses semantic versioning (semver):

```
v{MAJOR}.{MINOR}.{PATCH}

Example: v0.2.0
  ├─ 0 = Major version (breaking changes)
  ├─ 2 = Minor version (new features, backward compatible)
  └─ 0 = Patch version (bug fixes)
```

## YAML Version Declaration

Every `compose.yaml` file must declare its version:

```yaml
version: "v0.2"  # Major.Minor only

services:
  api:
    image: myapp:latest
    # ...
```

**Important**: Only specify `major.minor` in YAML (e.g., `v0.2`, not `v0.2.0`). Patch versions are backward compatible within the same minor version.

## Version Compatibility

### API Compatibility Matrix

| YAML Version | API Versions | Status | Notes |
|--------------|--------------|--------|-------|
| v0.2 | v0.2.0, v0.2.1, v0.2.2 | **Current** | Active development |
| v0.1 | v0.1.0 - v0.1.9 | Deprecated | Supported until Q2 2026 |
| v0.0 | v0.0.x | Unsupported | Migrate to v0.2 |

### Backward Compatibility

**Minor version updates** (e.g., v0.1 → v0.2) may include:
- ✅ New optional fields
- ✅ New provider support
- ✅ Enhanced features
- ❌ No breaking changes to existing configurations

**Major version updates** (e.g., v1.0 → v2.0) may include:
- ⚠️  Breaking changes
- ⚠️  Field renames or removals
- ⚠️  Changed defaults
- ✅  Migration guides provided

## Viewing Specific Versions

### Documentation Versions

Access documentation for specific versions:

- **Latest (v0.2.0)**: [https://blazing.work/docs](https://blazing.work/docs)
- **v0.1**: [https://blazing.work/docs/v0.1](https://blazing.work/docs/v0.1)
- **All Versions**: [https://blazing.work/docs/versions](https://blazing.work/docs/versions)

### CLI Version Management

Check your CLI version:

```bash
core --version
```

Install a specific version:

```bash
# Install latest
brew install blazing-cli

# Install specific version
brew install blazing-cli@0.2.0

# Pin to version
brew pin blazing-cli@0.2.0
```

## Schema Validation

### Version-Specific Schemas

Each version has a JSON schema for validation:

```yaml
# Schema URL format
schema: https://docs.blazing.work/core/v0.2.0/schema
```

The CLI automatically fetches the correct schema based on your `version` field.

### Validate Against Specific Version

```bash
# Validate with current CLI version
core validate

# Validate with specific schema version
core validate --schema v0.2.0
```

## Migration Between Versions

### Checking for Updates

```bash
# See if newer version available
core check-updates

# View changelog
core changelog v0.2.0
```

### Migration Tools

Automated migration between versions:

```bash
# Migrate from v0.1 to v0.2
core migrate --from v0.1 --to v0.2 compose.yaml

# Preview changes without applying
core migrate --from v0.1 --to v0.2 --dry-run compose.yaml
```

Sample migration output:

```
Migrating compose.yaml from v0.1 to v0.2

Changes:
  ✓ Updated version: v0.1 → v0.2
  ✓ Renamed: placement.regions → regions.geographic_scope
  ✓ Added required field: project_id
  ⚠️  Deprecated field removed: legacy_mode

Migration successful. Review changes before deploying.
```

## Version-Specific Features

### Feature Availability by Version

Use the feature registry to check availability:

```bash
# Check if feature available in version
core features list --version v0.2.0

# Check specific feature
core features check GPU-MIG --version v0.2.0
```

### Changelog

View detailed changes between versions:

```bash
core changelog --from v0.1.0 --to v0.2.0
```

## Deprecation Policy

### Deprecation Timeline

1. **Announcement** (Version N): Feature marked as deprecated
2. **Warning Period** (6 months): Warnings in CLI/docs
3. **Removal** (Version N+2): Feature removed

Example timeline:

```
v0.1.0 (Jan 2025)  - Feature X introduced
v0.2.0 (Dec 2025)  - Feature X deprecated (warnings)
v0.3.0 (Jun 2026)  - Feature X still works (warnings)
v1.0.0 (Jan 2027)  - Feature X removed
```

### Deprecated Features

Current deprecations in v0.2.0:

| Feature | Deprecated In | Removed In | Replacement |
|---------|---------------|------------|-------------|
| `legacy_mode` | v0.2.0 | v1.0.0 | Use standard mode |
| `placement.regions` | v0.2.0 | v1.0.0 | Use `regions.geographic_scope` |

## Staying Up to Date

### Release Notifications

Subscribe to release notifications:

```bash
core subscribe releases
```

Or follow:
- [GitHub Releases](https://github.com/blazing/core-compose/releases)
- [Changelog](https://blazing.work/changelog)
- [Twitter @blazingcloud](https://twitter.com/blazingcloud)

### Version Pinning

Pin your deployment to a specific version:

```yaml
version: "v0.2"  # Pin to v0.2.x

# Optionally lock CLI version
cli_version_min: "0.2.0"
cli_version_max: "0.2.99"
```

## API Version Negotiation

The CLI and API negotiate versions automatically:

```
1. CLI reads compose.yaml version: v0.2
2. CLI connects to API: GET /v0.2/validate
3. API checks compatibility:
   - If supported: ✓ Proceed
   - If unsupported: ❌ Error with migration guide
```

## Need Help?

- [Migration Guide](/docs/versioning)
- [Breaking Changes](/docs/versioning)
- [Support](mailto:admin@blazing.work)


Understanding documentation versions and API compatibility

Documentation Versioning

Understand the foundational concepts of Blazing Core Compose

Core Concepts


Blazing Core Compose uses a **thin client, smart server** architecture that separates validation from orchestration for maximum reliability and consistency.

## Design Principles

### Server-Side Intelligence

The Core Compose compiler uses **server-side intelligence** for infrastructure decisions. This design choice provides several critical benefits:

1. **Crash Resilience**: CLI survives crashes while server continues orchestration
2. **Consistency**: Same placement algorithm for all clients (CLI, Web UI, mobile)
3. **Real-Time Data**: Server has current availability, pricing, and quota information
4. **Atomic Operations**: All resources created or none (no partial deployments)

## Architecture Layers

### Client Layer (Thin CLI)

The CLI is responsible for:

```yaml
responsibilities:
  - Fast local validation (50-200ms)
  - Schema compliance checks
  - Feature and control validation
  - Intent submission to API
  - Display results and feedback
```

**What the CLI Does NOT Do:**
- Make infrastructure placement decisions
- Track provider availability
- Handle resource provisioning
- Manage state

### Server Layer (Control Plane API)

The Control Plane API orchestrates all infrastructure:

```yaml
responsibilities:
  - Real-time provider scoring
  - Intelligent placement algorithms
  - Resource provisioning
  - State management
  - Audit logging
  - Cost estimation
```

### Provider Layer

Provider compilers translate Core Compose specifications into native formats:

- **DFC Compiler**: Generates Akash SDL + Gateway configs
- **AWS Compiler**: CloudFormation/Terraform for EKS
- **GCP Compiler**: GKE manifests + Cloud resources
- **Azure Compiler**: AKS + ARM templates

## Deployment Flow

### Phase 1: Local Validation (Client)

```bash
core validate compose.yaml
```

The CLI performs fast local checks:

1. **Schema Validation**: YAML structure and types
2. **Feature Checks**: Verify requested features are available
3. **Control Checks**: Ensure compliance requirements can be met
4. **Policy Validation**: Org-level policy conformance

**Time**: 50-200ms
**Result**: Immediate feedback on configuration issues

### Phase 2: Plan Intent (Client)

```bash
core plan compose.yaml
```

The CLI shows deployment **intent** (what will happen):

- Services to be deployed
- Resource requirements
- Provider preferences
- Compliance controls
- Estimated cost range

**Important**: Actual region selection happens server-side during `apply`.

### Phase 3: Orchestration (Server)

```bash
core apply compose.yaml
```

The server executes the deployment:

#### 3.1 Placement Algorithm

```python
def score_provider(provider, requirements):
    score = 0

    # Region availability
    if provider.has_capacity(requirements.cpu, requirements.memory):
        score += 40

    # Cost efficiency
    cost_score = calculate_cost_efficiency(provider, requirements)
    score += cost_score * requirements.strategy.cost / 100

    # Latency optimization
    if provider.region in requirements.preferred_regions:
        score += requirements.strategy.latency

    # Compliance match
    if provider.meets_compliance(requirements.controls):
        score += requirements.strategy.compliance

    # Feature availability
    if all_features_available(provider, requirements.features):
        score += 20
    else:
        score -= 30  # Penalize missing features

    return score
```

#### 3.2 Resource Provisioning

1. **Virtual Allocation**: Reserve IPs, GPUs, storage
2. **Infrastructure Creation**: Provision compute nodes
3. **Network Setup**: Configure ingress/egress
4. **Service Deployment**: Deploy containers
5. **Verification**: Health checks and readiness

All operations are **atomic**: if any step fails, entire deployment rolls back.

#### 3.3 Response

Server returns:

```json
{
  "deployment_id": "df-2025-12-03-00123",
  "regions_created": [
    {"provider": "GCP", "region": "us-central1", "nodes": 3},
    {"provider": "DFC", "region": "chicago", "nodes": 2}
  ],
  "placement_rationale": [
    "GCP selected for reliability (score: 91)",
    "DFC selected for cost efficiency (60% savings)"
  ],
  "cost_estimate": {
    "monthly": 191,
    "variance": 15
  },
  "endpoints": {
    "web": "https://web-my-cluster.blazing.app"
  }
}
```

## State Management

### State Registries

| Registry | Purpose | Backend |
|----------|---------|---------|
| IPLease | Tracks leased IPs and timers | etcd / Consul |
| CertRegistry | TLS certificates & rotation | Vault |
| FeatureRegistry | features.yaml snapshot | Git |
| ControlRegistry | controls.yaml snapshot | Git |
| PlanCache | Last effective plan | Redis |

### Audit Trail

Every deployment creates an **immutable audit record**:

```json
{
  "deployment_id": "df-2025-12-03-00123",
  "action": "apply",
  "actor": "user@example.com",
  "hash": "sha256:8f9d...",
  "timestamp": "2025-12-03T22:00:00Z",
  "features_used": {
    "GPU-SHARING": "available",
    "EGR-LOCK-COUNTRY": "available"
  },
  "controls_evaluated": {
    "PCI-DSS-4.0": "passed",
    "DATA-RESIDENCY-EU": "passed"
  },
  "providers": ["GCP", "DFC"],
  "cost_actual": 187.43
}
```

## Component Interaction

```
┌──────────────┐
│   CLI        │  Local validation (fast)
│   (Thin)     │  Submit intent to API
└──────┬───────┘
       │
       │ HTTPS (declarative request)
       │
       ▼
┌──────────────────────────┐
│  Control Plane API       │
│  (Smart Orchestrator)    │
│                          │
│  • Placement Algorithm   │
│  • Provider Scoring      │
│  • Resource Provisioning │
│  • State Management      │
│  • Audit Logging         │
└────────┬─────────────────┘
         │
         │ Provider-specific API calls
         │
    ┌────┴────┬──────┬──────┬──────┐
    ▼         ▼      ▼      ▼      ▼
┌──────┐ ┌──────┐ ┌────┐ ┌────┐ ┌──────┐
│ GCP  │ │ DFC  │ │AWS │ │Azure│ │Akash│
│ GKE  │ │ SDL  │ │EKS │ │ AKS │ │ Net │
└──────┘ └──────┘ └────┘ └────┘ └──────┘
```

## Benefits of This Architecture

### 1. Reliability
- CLI crashes don't affect deployments
- Server continues orchestration independently
- Retries and error handling server-side

### 2. Consistency
- Same placement algorithm for all clients
- No version skew between CLI and logic
- Centralized decision-making

### 3. Real-Time Optimization
- Server sees current provider pricing
- Live capacity and availability data
- Dynamic cost optimization

### 4. Security
- Credentials never leave server
- Audit trail for all operations
- Centralized access control

## Next Steps

- Learn about [Provider Configuration](/docs/overview)
- Understand [Deployment Lifecycle](/docs/deployment-lifecycle)
- Explore [Governance Layer](/docs/features-and-controls)


Understand the Blazing Core Compose architecture and design principles

Architecture Overview


Blazing Core Compose uses a hierarchical organizational model to manage infrastructure at scale:

```
Organization
  └── Project
      └── Cluster
          └── RegionSet
              └── Services
```

## Overview

### Organization

The top-level entity representing your company or team.

```yaml
# Determined by API authentication
organization_id: <derived from API key>
```

**Characteristics:**
- One organization per company/team
- Contains multiple projects
- Shared billing and access control
- Organization-wide policies

**Use Cases:**
- Company: "Acme Corp"
- Team: "Platform Engineering"
- Department: "Data Science"

### Project

Logical grouping of related clusters within an organization.

```yaml
# Declared in compose.yaml
project_id: production
```

**Characteristics:**
- Groups related infrastructure
- Separate billing tracking
- Project-level policies
- Resource quotas per project

**Use Cases:**
- Environment: "production", "staging", "development"
- Product: "mobile-api", "web-backend", "ml-pipeline"
- Customer: "customer-acme", "customer-beta"

### Cluster

A deployment unit with its own regional infrastructure and services.

```yaml
# Declared in compose.yaml
cluster_id: api-cluster-v2

cluster:
  name: Production API Cluster v2
```

**Characteristics:**
- Contains multiple services
- Deployed across multiple regions
- Isolated network and security
- Independent scaling and updates

**Use Cases:**
- Service cluster: "api-backend", "data-processing"
- Application: "mobile-app", "admin-portal"
- Version: "api-v1", "api-v2"

### RegionSet

Geographic distribution of your cluster infrastructure.

```yaml
regions:
  geographic_scope: NA
  count: 5
  strategy:
    cost: 60
    latency: 30
    compliance: 10
```

**Characteristics:**
- Automatic region selection by server
- Provider-specific distribution
- Geographic constraints
- High availability zones

### Services

Individual application components running within a cluster.

```yaml
services:
  api:
    image: myapp:latest
    cpu: 2
    memory: 4Gi

  worker:
    image: myworker:latest
    cpu: 4
    memory: 8Gi
```

**Characteristics:**
- Docker container-based
- Independent scaling
- Service-level configuration
- Inter-service networking

## Complete Example

Here's how all levels work together:

```yaml
version: "v0.2"

# Organization: Determined by API authentication
# └─ organization_id: acme-corp (from API key)

# Project: Logical grouping
project_id: production

# Cluster: Deployment unit
cluster_id: api-backend-cluster

cluster:
  name: Production API Backend

# Provider configuration (cluster-level)
providers:
  gcp:
    status: prefer
    network_tier: Standard

  dfc:
    status: prefer

  akash:
    status: fallback

# Regional distribution (cluster-level)
regions:
  geographic_scope: NA
  count: 3
  strategy:
    cost: 50
    latency: 40
    compliance: 10

# Services (cluster-level)
services:
  # Service 1
  api:
    image: acme/api:v2.1.0
    cpu: 2
    memory: 4Gi
    autoscaling:
      enabled: true
      min_replicas: 3
      max_replicas: 20
    network:
      ingress:
        expose:
          - port: 443
            tls:
              auto: true

  # Service 2
  worker:
    image: acme/worker:v2.1.0
    cpu: 4
    memory: 8Gi
    autoscaling:
      enabled: true
      min_replicas: 2
      max_replicas: 50
    gpu:
      count: 1
      model: nvidia-a100
```

## Resource Hierarchy

### API Paths

Resources are accessed via hierarchical API paths:

```
/organizations/{org_id}
  /projects/{project_id}
    /clusters/{cluster_id}
      /regions
      /services/{service_name}
```

Example API calls:

```bash
# List all projects
GET /v0.2/organizations/acme-corp/projects

# Get specific cluster
GET /v0.2/organizations/acme-corp/projects/production/clusters/api-backend-cluster

# List services in cluster
GET /v0.2/organizations/acme-corp/projects/production/clusters/api-backend-cluster/services
```

### CLI Commands

The CLI respects this hierarchy:

```bash
# Set organization context (from login)
core login

# List projects
core projects list

# Set project context
core project use production

# List clusters in project
core clusters list

# Deploy a cluster
core apply compose.yaml

# List services in cluster
core services list --cluster api-backend-cluster
```

## Access Control

### Organization-Level Permissions

| Role | Permissions |
|------|-------------|
| **Owner** | Full access to all resources |
| **Admin** | Manage projects and clusters |
| **Developer** | Deploy and manage clusters |
| **Viewer** | Read-only access |

### Project-Level Permissions

Permissions can be scoped to specific projects:

```yaml
# Grant developer access to production project only
access:
  - user: alice@acme.com
    role: developer
    scope: project:production
```

### Cluster-Level Isolation

Each cluster has:
- Isolated network (separate VPCs/VNets)
- Separate service accounts
- Independent secrets management
- Per-cluster encryption keys

## Billing and Quotas

### Billing Hierarchy

```
Organization Billing Account
  ├── Project: production ($1,250/month)
  │   ├── Cluster: api-backend ($800/month)
  │   └── Cluster: worker-pool ($450/month)
  │
  └── Project: staging ($320/month)
      └── Cluster: staging-env ($320/month)
```

### Resource Quotas

Set limits at organization and project levels:

```yaml
# Organization-level quotas
organization:
  quotas:
    max_projects: 10
    max_clusters_per_project: 20
    total_cpu: 1000
    total_memory: 2000Gi
    total_gpu: 50

# Project-level quotas
project:
  quotas:
    max_clusters: 5
    cpu_per_cluster: 100
    memory_per_cluster: 500Gi
```

## Multi-Tenant Patterns

### Pattern 1: Project Per Customer

Isolate customers at the project level:

```
Organization: Acme SaaS
  ├── Project: customer-apple
  │   └── Cluster: app-cluster
  ├── Project: customer-google
  │   └── Cluster: app-cluster
  └── Project: customer-meta
      └── Cluster: app-cluster
```

Benefits:
- Strong isolation
- Per-customer billing
- Customer-specific policies
- Easy offboarding

### Pattern 2: Cluster Per Environment

Separate environments within projects:

```
Organization: Acme Corp
  └── Project: mobile-app
      ├── Cluster: production
      ├── Cluster: staging
      └── Cluster: development
```

Benefits:
- Environment isolation
- Shared project policies
- Unified billing per product
- Progressive deployment

### Pattern 3: Cluster Per Service

Microservices architecture:

```
Organization: Acme Corp
  └── Project: production
      ├── Cluster: api-gateway
      ├── Cluster: auth-service
      ├── Cluster: payment-service
      └── Cluster: notification-service
```

Benefits:
- Service isolation
- Independent scaling
- Service-specific configuration
- Team autonomy

## Best Practices

### Naming Conventions

Use consistent naming:

```yaml
# project_id format
project_id: <environment>-<product>
# Examples: prod-api, staging-web, dev-ml

# cluster_id format
cluster_id: <service>-<version>-<purpose>
# Examples: api-v2-backend, worker-v1-batch, db-v3-primary
```

### Organization Structure

For small teams (1-10 people):
```
1 Organization
  2-3 Projects (prod, staging, dev)
    1-5 Clusters per project
```

For medium teams (10-50 people):
```
1 Organization
  5-10 Projects (by product/service)
    3-10 Clusters per project
```

For large teams (50+ people):
```
1 Organization
  10-50 Projects (by team/product)
    5-20 Clusters per project
```

### Migration Strategy

Start simple and grow:

1. **Phase 1**: Single project, single cluster
2. **Phase 2**: Add staging project
3. **Phase 3**: Split into multiple clusters
4. **Phase 4**: Organize by product/team

## Next Steps

- Learn about [Provider Configuration](/docs/overview)
- Understand [Access Control](/docs/organizational-hierarchy)
- Explore [Multi-Tenancy Patterns](/docs/organizational-hierarchy)


Understanding organizations, projects, and clusters in Blazing

Organizational Hierarchy

Configure cloud providers and infrastructure preferences

Provider Configuration


Blazing Core supports multiple cloud providers, giving you flexibility, cost optimization, and vendor independence.

## Supported Providers

### GCP (Google Cloud Platform)
Enterprise-grade reliability with cost-effective Standard tier networking.

**Best For:**
- Production control planes
- Low-latency applications
- Compliance-sensitive workloads

**Key Features:**
- GKE Standard (spot instances for 60-90% savings)
- 17x cheaper egress ($0.005/GB vs $0.085/GB Premium)
- Global network infrastructure
- Managed certificates and load balancing

### DFC (Digital Frontier Cloud)
Curated, cost-effective infrastructure on Akash Network.

**Best For:**
- Burst workers
- Cost-optimized workloads
- Stateless services with replication

**Key Features:**
- Zero egress fees
- ~60% cheaper than GCP
- Curated high-reliability providers
- Same Kubernetes interface

### Akash Network
Global decentralized compute marketplace.

**Best For:**
- Emergency overflow capacity
- Geographic diversity
- Cost-sensitive batch jobs

**Key Features:**
- Zero egress fees
- 70-80% cheaper than hyperscale clouds
- Providers in 50+ countries
- No long-term contracts

### Coming Soon

- **AWS EKS**: Amazon Elastic Kubernetes Service
- **Azure AKS**: Azure Kubernetes Service
- **Hybrid On-Prem**: Your own data centers

## Provider Status

Define your relationship with each provider using the `status` field:

```yaml
providers:
  gcp:
    status: prefer     # 1st choice
  dfc:
    status: allow      # 2nd choice
  akash:
    status: fallback   # Last resort
```

### Status Semantics

| Status | Priority | When Used | Use Case |
|--------|----------|-----------|----------|
| **prefer** | 1st | Always attempted first | Primary infrastructure |
| **allow** | 2nd | Used when preferred unavailable | Acceptable alternatives |
| **fallback** | 3rd | Emergency only | Burst overflow capacity |

## Selection Algorithm

The server scores providers based on multiple factors:

```python
def score_provider(provider, requirements):
    score = 0

    # Capacity availability (40 points)
    if provider.has_capacity(requirements):
        score += 40

    # Cost efficiency (weighted by strategy)
    cost_score = (100 - provider.relative_cost) * 0.6
    score += cost_score * (requirements.strategy.cost / 100)

    # Latency optimization (weighted by strategy)
    if provider.region in requirements.preferred_regions:
        score += requirements.strategy.latency

    # Compliance match (weighted by strategy)
    if provider.meets_compliance(requirements.controls):
        score += requirements.strategy.compliance

    # Feature availability (20 points or -30 penalty)
    if all_features_available(provider, requirements):
        score += 20
    else:
        score -= 30

    return score
```

## Cost Comparison

Based on typical 2 CPU, 4GB RAM workload:

| Provider | Compute | Egress | Monthly (estimate) |
|----------|---------|--------|---------------------|
| **GCP Standard** | $40 | $5 (1TB) | **$45/month** |
| **GCP Premium** | $40 | $85 (1TB) | $125/month |
| **DFC** | $24 | $0 | **$24/month** (47% savings) |
| **Akash** | $12 | $0 | **$12/month** (73% savings) |

### Cost Optimization Strategy

**Best Practice**: Use multiple providers strategically:

```yaml
providers:
  gcp:
    status: prefer          # Reliable baseline (3 replicas)
    node_pools:
      baseline: standard    # min_replicas on on-demand
      burst: spot           # Burst on spot (60-90% savings)

  dfc:
    status: prefer          # Cost-effective burst (7+ replicas)

  akash:
    status: fallback        # Emergency overflow
```

**Result**:
- Baseline (3 replicas): GCP on-demand ($40/month)
- Burst (7 replicas): GCP spot + DFC ($35/month)
- Total: **$75/month** vs $150/month all-GCP-standard (50% savings)

## Geographic Distribution

Providers have different regional coverage:

### GCP Regions (35+)
```
North America: us-central1, us-east1, us-west1, us-west2, etc.
Europe: europe-west1, europe-west2, europe-north1, etc.
Asia: asia-east1, asia-southeast1, etc.
```

### DFC Locations (Growing)
```
North America: Chicago, Ashburn, Los Angeles
Europe: Sofia, Frankfurt, London
Asia: Singapore, Tokyo
```

### Akash Network (Global)
```
50+ countries with community providers
Varies by availability and demand
```

## Network Tiers

### GCP Network Tiers

```yaml
providers:
  gcp:
    network_tier: Standard | Premium
```

| Tier | Egress Cost | IPv6 | Latency | Use Case |
|------|-------------|------|---------|----------|
| **Standard** | $0.005/GB | ❌ No | Regional | Cost-optimized (default) |
| **Premium** | $0.085/GB | ✅ Yes | Global | Low-latency worldwide |

**Important**: Standard tier = **17x cheaper egress**. Use Premium only for truly global, latency-sensitive applications.

## Public Gateway

Only **one provider** should have the public gateway enabled:

```yaml
providers:
  gcp:
    status: prefer
    public_gateway:
      enabled: true         # External traffic enters here
      static_ip: auto

      http:
        enabled: true
        port: 443

      gateway:
        replicas: 1
        resources:
          cpu: 500m
          memory: 1Gi

  dfc:
    status: prefer
    public_gateway:
      enabled: false        # Workers only, no gateway
```

**Pricing**: $49/month (includes static IP, certs, HTTP/HTTPS ingress)

**Recommendation**: Enable on GCP for maximum reliability.

## Provider Capabilities Matrix

### Compute & Autoscaling

| Feature | GCP | DFC | Akash |
|---------|-----|-----|-------|
| CPU Autoscaling | ✅ HPA | ✅ Native | ✅ Manual |
| GPU Autoscaling | ✅ Full | ✅ Full | ⚠️ Limited |
| Spot Instances | ✅ 60-90% savings | ✅ N/A | ✅ Bid-based |
| Custom Metrics | ✅ Stackdriver | ✅ Prometheus | ⚠️ Optional |

### Networking

| Feature | GCP | DFC | Akash |
|---------|-----|-----|-------|
| Static IPs | ✅ Auto | ✅ Via gateway | ⚠️ Community |
| TLS Auto | ✅ Managed Certs | ✅ Let's Encrypt | ⚠️ Manual |
| Load Balancing | ✅ Global | ✅ Gateway | ⚠️ Provider-dependent |
| IPv6 | ✅ Premium only | ❌ | ⚠️ Varies |

### Storage & Data

| Feature | GCP | DFC | Akash |
|---------|-----|-----|-------|
| Encrypted Volumes | ✅ PD CMEK | ✅ Provider | ⚠️ Optional |
| Persistent Storage | ✅ Full | ✅ Full | ⚠️ Provider-dependent |
| Data Residency | ✅ Org Policy | ✅ Geofencing | ⚠️ Manual |

### Security & Compliance

| Feature | GCP | DFC | Akash |
|---------|-----|-----|-------|
| Confidential Compute | ✅ Planned | ⚠️ Planned | ❌ |
| VPC Isolation | ✅ Full | ✅ Full | ⚠️ Provider-dependent |
| Compliance (GDPR) | ✅ Full | ✅ Full | ⚠️ Community |
| WAF | ✅ Cloud Armor | ⚠️ Optional | ❌ |

## Example Configurations

### Production Setup (High Reliability)

```yaml
providers:
  gcp:
    status: prefer
    network_tier: Standard
    ip_version: IPV4
    node_pools:
      baseline: standard
      burst: spot
    public_gateway:
      enabled: true
      static_ip: auto
      http:
        enabled: true
        port: 443

  dfc:
    status: allow

  akash:
    status: fallback
```

### Cost-Optimized Setup

```yaml
providers:
  dfc:
    status: prefer        # Primary for cost
    public_gateway:
      enabled: true

  gcp:
    status: allow         # Secondary for reliability
    network_tier: Standard
    node_pools:
      burst: spot

  akash:
    status: fallback      # Emergency only
```

### Compliance-First Setup (EU Only)

```yaml
providers:
  gcp:
    status: prefer
    public_gateway:
      enabled: true

  dfc:
    status: fallback      # Only EU-based providers

regions:
  geographic_scope: EU    # Restrict to Europe
  count: 3

placement:
  residency:
    require_countries: ["PT", "ES", "FR", "DE", "NL"]
```

## Next Steps

- [GCP Configuration](/docs/gcp-provider)
- [DFC Configuration](/docs/dfc-provider)
- [Akash Configuration](/docs/akash-provider)
- [Provider Selection](/docs/overview)


Understanding cloud providers and infrastructure preferences in Blazing Core

Provider Overview


Google Cloud Platform (GCP) is a primary provider offering enterprise-grade reliability, global infrastructure, and cost-effective networking options.

## Basic Configuration

```yaml
providers:
  gcp:
    status: prefer
    network_tier: Standard
    ip_version: IPV4
    cert_issuer: letsencrypt-prod
```

## Configuration Reference

### Status Field

```yaml
gcp:
  status: prefer | allow | fallback
```

Define GCP's priority in provider selection:

- **prefer**: Primary provider (use first)
- **allow**: Acceptable provider (use if preferred unavailable)
- **fallback**: Emergency provider (use only when others fail)

### Network Tier

```yaml
gcp:
  network_tier: Standard | Premium
```

GCP offers two network tiers with significant cost differences:

| Tier | Egress Cost | IPv6 | Routing | Best For |
|------|-------------|------|---------|----------|
| **Standard** | **$0.005/GB** | ❌ No | Regional | Cost-optimized (default) |
| **Premium** | $0.085/GB | ✅ Yes | Global | Low-latency worldwide |

**Cost Impact**: Standard tier is **17x cheaper** for egress.

**Example Calculation** (1TB monthly egress):
- Standard: $5/month
- Premium: $85/month
- **Savings: $80/month** (1600% cost reduction)

**When to use Premium**:
- Global user base requiring low latency
- IPv6 requirement
- Real-time applications (gaming, video streaming)

**When to use Standard** (recommended):
- Regional deployments
- Cost-sensitive applications
- Most web/API services

### IP Version

```yaml
gcp:
  ip_version: IPV4 | IPV6
```

**Important**: Standard tier only supports IPv4.

| Combination | Valid | Notes |
|-------------|-------|-------|
| Standard + IPv4 | ✅ | Recommended default |
| Standard + IPv6 | ❌ | Not supported |
| Premium + IPv4 | ✅ | Works but expensive |
| Premium + IPv6 | ✅ | Required for IPv6 |

### Certificate Issuer

```yaml
gcp:
  cert_issuer: letsencrypt-prod | letsencrypt-staging | custom
```

Specify the certificate issuer for TLS:

- **letsencrypt-prod**: Production Let's Encrypt (default)
- **letsencrypt-staging**: Testing (higher rate limits)
- **custom**: Your own certificate authority

## Node Pool Configuration

GKE Standard mode with spot instance support for cost optimization.

```yaml
gcp:
  node_pools:
    baseline: standard      # Always on-demand (read-only)
    burst: spot | standard  # Burst replicas (configurable)
```

### Baseline vs Burst Replicas

**Baseline replicas** (`min_replicas`):
- Always run on **standard (on-demand)** nodes
- Guaranteed availability
- No interruption risk
- Higher cost but reliable

**Burst replicas** (above `min_replicas`):
- Can run on **spot** nodes (if configured)
- 60-90% cost savings
- May be preempted (24h max lifetime)
- Ideal for stateless workloads

### Cost Example

Service with `min_replicas: 3, max_replicas: 10`:

```yaml
services:
  api:
    autoscaling:
      min_replicas: 3    # Baseline (always standard)
      max_replicas: 10   # Up to 7 burst replicas
```

With `node_pools.burst: spot`:

| Scenario | Standard Nodes | Spot Nodes | Cost |
|----------|----------------|------------|------|
| **Baseline (3 replicas)** | 3 | 0 | $0.10/hour |
| **Peak (10 replicas)** | 3 | 7 | $0.17/hour |
| **All standard** | 10 | 0 | $0.33/hour |

**Monthly savings**: ~$350/month (48% reduction)

### Node Pool Configuration

```yaml
gcp:
  node_pools:
    baseline: standard       # Read-only, always standard
    burst: spot             # 60-90% savings on burst
```

Available burst options:

- **spot**: Use spot instances for burst (recommended)
- **standard**: Use on-demand for burst (higher cost, no preemption)

## Public Gateway Configuration

The public gateway provides external connectivity to your services.

```yaml
gcp:
  public_gateway:
    enabled: true
    static_ip: auto | <ip-address>

    # Protocol configuration
    sql:
      enabled: true
      port: 26257

    http:
      enabled: true
      port: 443
      path_prefix: /admin

    # Gateway infrastructure
    gateway:
      replicas: 1
      resources:
        cpu: 500m
        memory: 1Gi
```

### Gateway Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | false | Deploy public gateway |
| `static_ip` | string | auto | IP allocation (auto or specific) |
| `sql.enabled` | boolean | false | PostgreSQL wire protocol support |
| `sql.port` | number | 5432 | SQL port (e.g., 26257 for CockroachDB) |
| `http.enabled` | boolean | false | HTTP/HTTPS ingress |
| `http.port` | number | 8080 | HTTP port |
| `http.path_prefix` | string | / | Optional path prefix |
| `gateway.replicas` | number | 1 | Gateway replica count |
| `gateway.resources.cpu` | string | 500m | CPU allocation |
| `gateway.resources.memory` | string | 1Gi | Memory allocation |

### SQL Gateway Example

Expose CockroachDB with both SQL and HTTP admin:

```yaml
gcp:
  public_gateway:
    enabled: true
    static_ip: auto

    sql:
      enabled: true
      port: 26257          # CockroachDB SQL port

    http:
      enabled: true
      port: 8080
      path_prefix: /admin  # Admin UI at /admin

    gateway:
      replicas: 1
      resources:
        cpu: 500m
        memory: 1Gi
```

Access:
- SQL: `postgresql://gateway-ip:26257/db`
- Admin UI: `https://gateway-ip/admin`

### HTTP Only Example

Standard web application:

```yaml
gcp:
  public_gateway:
    enabled: true
    static_ip: auto

    http:
      enabled: true
      port: 443

    gateway:
      replicas: 1
      resources:
        cpu: 500m
        memory: 1Gi
```

**Pricing**: $49/month (includes static IP, certificates, load balancing)

## Complete Examples

### Production Configuration

High reliability with cost optimization:

```yaml
providers:
  gcp:
    status: prefer
    network_tier: Standard       # 17x cheaper egress
    ip_version: IPV4             # Required for Standard tier
    cert_issuer: letsencrypt-prod

    node_pools:
      baseline: standard         # Reliable baseline
      burst: spot                # Cost-effective burst

    public_gateway:
      enabled: true
      static_ip: auto

      http:
        enabled: true
        port: 443

      gateway:
        replicas: 1
        resources:
          cpu: 500m
          memory: 1Gi
```

### Cost-Optimized Configuration

Maximum cost savings:

```yaml
providers:
  gcp:
    status: allow              # Secondary to DFC
    network_tier: Standard     # Cheapest egress
    ip_version: IPV4

    node_pools:
      baseline: standard
      burst: spot              # Max savings on burst

    public_gateway:
      enabled: false           # Use DFC gateway instead
```

### High-Performance Configuration

Global low-latency:

```yaml
providers:
  gcp:
    status: prefer
    network_tier: Premium      # Global routing
    ip_version: IPV6           # Modern networks
    cert_issuer: letsencrypt-prod

    node_pools:
      baseline: standard
      burst: standard          # No preemption for consistency

    public_gateway:
      enabled: true
      static_ip: auto

      http:
        enabled: true
        port: 443

      gateway:
        replicas: 3            # High availability
        resources:
          cpu: 1000m
          memory: 2Gi
```

### Database Gateway Configuration

PostgreSQL-compatible database:

```yaml
providers:
  gcp:
    status: prefer
    network_tier: Standard
    ip_version: IPV4

    node_pools:
      baseline: standard       # Databases always on-demand
      burst: standard

    public_gateway:
      enabled: true
      static_ip: auto

      sql:
        enabled: true
        port: 5432           # Standard PostgreSQL port

      http:
        enabled: true
        port: 8080
        path_prefix: /pgadmin

      gateway:
        replicas: 2          # HA for database access
        resources:
          cpu: 1000m
          memory: 2Gi
```

## GCP-Specific Features

### Regions Available

GCP has 35+ regions worldwide:

**North America**:
- `us-central1` (Iowa)
- `us-east1` (South Carolina)
- `us-west1` (Oregon)
- `us-west2` (Los Angeles)

**Europe**:
- `europe-west1` (Belgium)
- `europe-west2` (London)
- `europe-north1` (Finland)
- `europe-west4` (Netherlands)

**Asia**:
- `asia-east1` (Taiwan)
- `asia-southeast1` (Singapore)
- `asia-northeast1` (Tokyo)

### GKE Features

- **Autopilot**: Not used for org workloads (Standard mode only)
- **Spot Instances**: 60-90% savings for burst workloads
- **Node Auto-repair**: Automatic node health checks
- **Workload Identity**: Secure service account binding
- **Binary Authorization**: Image signing and verification

### Integration with GCP Services

Core Compose integrates with:

- **Cloud Monitoring**: Metrics and alerting
- **Cloud Logging**: Centralized log aggregation
- **Cloud Load Balancing**: Global/regional load balancers
- **Cloud Armor**: WAF and DDoS protection
- **Certificate Manager**: Automated TLS certificates

## Best Practices

### 1. Use Standard Tier by Default

```yaml
network_tier: Standard  # 17x cheaper egress
```

Only upgrade to Premium if you need:
- IPv6 support
- Global routing with minimal latency
- Real-time gaming or video streaming

### 2. Enable Spot for Burst Workloads

```yaml
node_pools:
  baseline: standard    # Reliable baseline
  burst: spot           # Cost-effective burst
```

This provides:
- Reliability for baseline traffic
- Cost savings for peak traffic
- Automatic fallback to on-demand if spot unavailable

### 3. Single Gateway per Deployment

Enable gateway on only one provider:

```yaml
gcp:
  public_gateway:
    enabled: true       # Main gateway

dfc:
  public_gateway:
    enabled: false      # Workers only
```

Avoid multiple gateways to minimize costs.

### 4. Right-Size Gateway Resources

For typical workloads:

```yaml
gateway:
  replicas: 1
  resources:
    cpu: 500m
    memory: 1Gi
```

Scale up for high-traffic scenarios:

```yaml
gateway:
  replicas: 3
  resources:
    cpu: 1000m
    memory: 2Gi
```

## Troubleshooting

### "IPv6 not supported with Standard tier"

**Error**:
```
ERROR: IPv6 LoadBalancer requires Premium tier
```

**Solution**:
```yaml
gcp:
  network_tier: Standard
  ip_version: IPV4        # Must use IPv4 with Standard
```

### "Node pool exhausted"

**Error**:
```
ERROR: Cannot schedule pod, no nodes available
```

**Solution**: Increase cluster size or reduce replicas:

```yaml
services:
  api:
    autoscaling:
      max_replicas: 20   # Reduce if hitting limits
```

### "Gateway timeout"

**Error**:
```
ERROR: Gateway health check failed
```

**Solution**: Increase gateway resources:

```yaml
gateway:
  replicas: 2            # Add redundancy
  resources:
    cpu: 1000m           # Increase CPU
    memory: 2Gi
```

## Next Steps

- [DFC Provider Configuration](/docs/dfc-provider)
- [Provider Configuration](/docs/overview)
- [Service Autoscaling](/docs/autoscaling)
- 


Configure Google Cloud Platform for Blazing Core Compose deployments

GCP Provider Configuration


Digital Frontier Cloud (DFC) provides curated, cost-effective infrastructure on the Akash Network with zero egress fees and ~60% cost savings compared to GCP.

## What is DFC?

DFC runs on the Akash Network but with **curated, high-reliability providers** vetted by Digital Frontier. This gives you:

- **Zero egress fees**: No data transfer costs
- **60% cheaper compute**: Compared to equivalent GCP resources
- **Reliability**: Vetted providers with proven uptime
- **Same interface**: Standard Kubernetes deployment

## Basic Configuration

```yaml
providers:
  dfc:
    status: prefer
    public_gateway:
      enabled: false
```

## Configuration Reference

### Status Field

```yaml
dfc:
  status: prefer | allow | fallback
```

Define DFC's priority in provider selection:

- **prefer**: Primary provider (use first)
- **allow**: Acceptable provider (use if preferred unavailable)
- **fallback**: Emergency provider (use only when others fail)

### Akash Provider Whitelist

Optionally restrict to specific Akash providers:

```yaml
dfc:
  akash_provider_whitelist:
    - "akash1aaul837r7en7hpk9wv2svg8u78fdq0t2j2e82z"  # DFC Sofia, Bulgaria
    - "akash1xmz9es9ay9ln9x2m3q5dlu0hkpqyg37h4gqd3l"  # DFC Frankfurt, Germany
```

**When to use whitelist**:
- Compliance requirements (specific countries)
- Performance optimization (specific regions)
- Cost predictability (known providers)

**When to omit whitelist**:
- Maximum flexibility
- Geographic diversity
- Automatic failover to any DFC provider

### Public Gateway Configuration

```yaml
dfc:
  public_gateway:
    enabled: true | false
```

**Important**: Only enable gateway on **one provider** per deployment.

**Recommendation**: Use GCP gateway for maximum reliability:

```yaml
gcp:
  public_gateway:
    enabled: true          # Main gateway

dfc:
  public_gateway:
    enabled: false         # Workers only
```

## Complete Examples

### Cost-Optimized Setup

DFC as primary, GCP as backup:

```yaml
providers:
  dfc:
    status: prefer         # Primary for cost savings
    public_gateway:
      enabled: true        # DFC gateway (saves $49/month)

  gcp:
    status: allow          # Backup for reliability
    network_tier: Standard
    node_pools:
      burst: spot
    public_gateway:
      enabled: false
```

**Result**: Maximum cost savings with GCP fallback.

### Reliability-First Setup

GCP primary, DFC for burst:

```yaml
providers:
  gcp:
    status: prefer         # Primary for reliability
    network_tier: Standard
    node_pools:
      baseline: standard
      burst: spot
    public_gateway:
      enabled: true        # Reliable gateway

  dfc:
    status: prefer         # Also primary for burst capacity
    public_gateway:
      enabled: false       # Workers only
```

**Result**: Reliable baseline with cost-effective burst.

### Geographic Restriction

EU-only deployment:

```yaml
providers:
  dfc:
    status: prefer
    akash_provider_whitelist:
      - "akash1aaul837r7en7hpk9wv2svg8u78fdq0t2j2e82z"  # Sofia, Bulgaria
      - "akash1xmz9es9ay9ln9x2m3q5dlu0hkpqyg37h4gqd3l"  # Frankfurt, Germany
    public_gateway:
      enabled: true

regions:
  geographic_scope: EU
  count: 3
```

**Result**: Compliant EU deployment on DFC.

## DFC Locations

Current DFC provider locations (growing):

### North America
- **Chicago, IL**: `akash1...chicago`
- **Ashburn, VA**: `akash1...ashburn`
- **Los Angeles, CA**: `akash1...la`

### Europe
- **Sofia, Bulgaria**: `akash1aaul837r7en7hpk9wv2svg8u78fdq0t2j2e82z`
- **Frankfurt, Germany**: `akash1xmz9es9ay9ln9x2m3q5dlu0hkpqyg37h4gqd3l`
- **London, UK**: `akash1...london`

### Asia-Pacific
- **Singapore**: `akash1...singapore`
- **Tokyo, Japan**: `akash1...tokyo`

## Cost Comparison

### Compute Costs

Based on 2 CPU, 4GB RAM workload:

| Provider | Compute | Egress (1TB) | Total/Month | Savings |
|----------|---------|--------------|-------------|---------|
| **GCP Standard** | $40 | $5 | **$45** | Baseline |
| **DFC** | $24 | $0 | **$24** | **47%** |
| **Akash** | $12 | $0 | **$12** | **73%** |

### Example: 10 Replica Service

With `min_replicas: 3, max_replicas: 10`:

#### All GCP Standard

```yaml
providers:
  gcp:
    status: prefer
    node_pools:
      burst: standard
```

**Cost**: ~$450/month (10 replicas × $45)

#### GCP Baseline + DFC Burst

```yaml
providers:
  gcp:
    status: prefer         # 3 baseline replicas
    node_pools:
      baseline: standard
      burst: spot

  dfc:
    status: prefer         # 7+ burst replicas
```

**Cost**: ~$303/month
- GCP baseline (3): $135
- DFC burst (7): $168

**Savings**: $147/month (33%)

#### DFC Primary + GCP Fallback

```yaml
providers:
  dfc:
    status: prefer         # 10 replicas on DFC

  gcp:
    status: fallback       # Rarely used
```

**Cost**: ~$240/month (10 replicas × $24)

**Savings**: $210/month (47%)

## DFC Features

### Compute
- ✅ CPU: Any size
- ✅ Memory: Any size
- ✅ GPU: NVIDIA GPUs available
- ✅ Autoscaling: Full HPA support
- ✅ Spot pricing: Built-in with Akash bidding

### Networking
- ✅ Zero egress fees
- ✅ Public IPs: Via gateway
- ✅ TLS: Let's Encrypt automation
- ✅ Load balancing: Gateway-based
- ⚠️ IPv6: Provider-dependent

### Storage
- ✅ Persistent volumes: Provider-dependent
- ✅ Ephemeral storage: Full support
- ✅ Encrypted volumes: Provider-dependent
- ⚠️ Managed databases: Use external services

### Security
- ✅ VPC isolation: Provider-dependent
- ✅ Network policies: Full Kubernetes support
- ⚠️ Confidential compute: Roadmap
- ⚠️ Compliance certs: GDPR self-certification

## Best Practices

### 1. Use DFC for Stateless Workloads

**Good**: API servers, workers, batch jobs

```yaml
services:
  api:
    image: myapp:latest
    autoscaling:
      min_replicas: 3
      max_replicas: 20

  worker:
    image: myworker:latest
    autoscaling:
      min_replicas: 2
      max_replicas: 50
```

**Avoid**: Databases without replication, single-instance services

### 2. Combine with GCP for Reliability

```yaml
providers:
  gcp:
    status: prefer         # Baseline (3 replicas)

  dfc:
    status: prefer         # Burst (7+ replicas)
```

This provides:
- Reliable baseline on GCP
- Cost-effective burst on DFC
- Automatic failover

### 3. Use GCP Gateway

```yaml
gcp:
  public_gateway:
    enabled: true          # More reliable

dfc:
  public_gateway:
    enabled: false         # Workers only
```

GCP gateway provides:
- Global load balancing
- Better uptime SLA
- Integrated monitoring

### 4. Monitor Provider Performance

Track DFC provider metrics:

```yaml
observability:
  metrics:
    endpoint: /metrics
    format: prometheus
    custom_labels:
      provider: dfc
```

Watch for:
- High latency providers
- Frequent restarts
- Low availability

## Limitations

### Current Limitations

1. **No managed databases**: Use external DB services or GCP
2. **Variable provider performance**: Some providers better than others
3. **No automatic provider scoring**: Manual whitelist for consistency
4. **Limited compliance certifications**: GDPR via self-certification only

### Workarounds

**Database Workloads**:
```yaml
providers:
  gcp:
    status: prefer         # Databases on GCP

  dfc:
    status: prefer         # App servers on DFC
```

**Consistent Performance**:
```yaml
dfc:
  akash_provider_whitelist:
    - "akash1aaul837r7en7hpk9wv2svg8u78fdq0t2j2e82z"  # Proven uptime
```

**Compliance Requirements**:
```yaml
providers:
  gcp:
    status: prefer         # Compliance workloads

  dfc:
    status: allow          # Non-sensitive workloads
```

## Provider Selection Algorithm

DFC providers are scored based on:

```python
def score_dfc_provider(provider):
    score = 0

    # Capacity (40 points)
    if provider.has_capacity():
        score += 40

    # Uptime history (30 points)
    uptime_pct = provider.uptime_last_30d
    score += (uptime_pct / 100) * 30

    # Cost (20 points)
    cost_score = 100 - (provider.cost_relative * 100)
    score += (cost_score / 100) * 20

    # Whitelist bonus (10 points)
    if provider in whitelist:
        score += 10

    return score
```

## Troubleshooting

### "Provider capacity exceeded"

**Error**:
```
ERROR: DFC provider cannot provision requested resources
```

**Solution 1**: Remove whitelist for more options:
```yaml
dfc:
  # Remove akash_provider_whitelist
```

**Solution 2**: Add GCP fallback:
```yaml
gcp:
  status: fallback
```

### "High latency from DFC"

**Issue**: DFC provider in distant region

**Solution**: Use geographic scope:
```yaml
regions:
  geographic_scope: NA    # Restrict to North America
```

### "Gateway unreachable"

**Error**:
```
ERROR: Cannot reach DFC gateway
```

**Solution**: Switch to GCP gateway:
```yaml
gcp:
  public_gateway:
    enabled: true

dfc:
  public_gateway:
    enabled: false
```

## Migration Path

### From All-GCP to GCP+DFC

**Phase 1**: Add DFC as fallback

```yaml
providers:
  gcp:
    status: prefer

  dfc:
    status: fallback       # Test with minimal traffic
```

**Phase 2**: Promote DFC to allow

```yaml
providers:
  gcp:
    status: prefer

  dfc:
    status: allow          # Handle burst traffic
```

**Phase 3**: DFC as primary for burst

```yaml
providers:
  gcp:
    status: prefer         # Baseline only

  dfc:
    status: prefer         # Burst capacity
```

Monitor costs at each phase and adjust based on performance.

## DFC Roadmap

### Coming Soon
- **Confidential compute**: TEE support on select providers
- **Managed databases**: PostgreSQL, MySQL via DFC
- **Enhanced monitoring**: Provider performance dashboard
- **Auto-whitelist**: AI-driven provider selection

### Future Plans
- **Geographic guarantees**: Certified provider locations
- **Compliance certifications**: SOC2, ISO27001
- **Multi-region replication**: Automated data sync

## Next Steps

- [Akash Provider Configuration](/docs/akash-provider)
- [Provider Configuration](/docs/overview)
- 
- [Service Configuration](/docs/service-basics)


Configure Digital Frontier Cloud for cost-effective Akash-based deployments

DFC Provider Configuration


Akash Network is a decentralized compute marketplace with global capacity, offering the lowest costs and maximum geographic diversity as an emergency fallback provider.

## What is Akash Network?

Akash is a **peer-to-peer cloud compute marketplace** where:

- Anyone can offer compute capacity
- Users bid on available resources
- Providers compete on price and performance
- No central authority controls the network

## When to Use Akash

### Recommended Use Cases

✅ **Emergency overflow capacity** (fallback status)
```yaml
akash:
  status: fallback         # Use when GCP/DFC exhausted
```

✅ **Cost-sensitive batch workloads**
```yaml
services:
  batch-processor:
    image: processor:latest
```

✅ **Geographic diversity** (50+ countries)
```yaml
regions:
  geographic_scope: GLOBAL
  count: 10
```

### Not Recommended For

❌ **Production databases** (variable uptime)
❌ **Compliance-sensitive workloads** (no guarantees)
❌ **Real-time applications** (latency variability)
❌ **Baseline capacity** (use prefer status)

## Basic Configuration

```yaml
providers:
  akash:
    status: fallback       # Emergency only
    public_gateway:
      enabled: false       # Use GCP/DFC gateway
```

## Configuration Reference

### Status Field

```yaml
akash:
  status: prefer | allow | fallback
```

**Strong Recommendation**: Use `fallback` status only.

| Status | Recommended | Reason |
|--------|-------------|--------|
| fallback | ✅ **Yes** | Safe overflow capacity |
| allow | ⚠️ Sometimes | Testing or very cost-sensitive |
| prefer | ❌ No | Too variable for primary |

### Public Gateway Configuration

```yaml
akash:
  public_gateway:
    enabled: true | false
```

**Recommendation**: Disable Akash gateway, use GCP instead:

```yaml
gcp:
  public_gateway:
    enabled: true          # Reliable gateway

akash:
  public_gateway:
    enabled: false         # Workers only
```

Akash gateways are:
- Provider-dependent (variable reliability)
- Not load-balanced
- Limited monitoring

## Complete Examples

### Safe Fallback Configuration

Primary: GCP + DFC, Fallback: Akash

```yaml
providers:
  gcp:
    status: prefer         # Primary baseline
    network_tier: Standard
    node_pools:
      baseline: standard
      burst: spot
    public_gateway:
      enabled: true

  dfc:
    status: prefer         # Primary burst
    public_gateway:
      enabled: false

  akash:
    status: fallback       # Emergency only
    public_gateway:
      enabled: false
```

**Result**:
- GCP handles baseline (reliable)
- DFC handles burst (cost-effective)
- Akash handles extreme overflow (rare)

### Cost-Optimized Testing

Aggressive cost savings for dev/test:

```yaml
providers:
  akash:
    status: prefer         # Primary (testing only!)
    public_gateway:
      enabled: true

  dfc:
    status: allow          # Backup

  gcp:
    status: fallback       # Emergency
```

**Warning**: Only for non-production environments.

### Batch Processing Configuration

Long-running batch jobs:

```yaml
providers:
  akash:
    status: prefer         # Cheapest for batch

  dfc:
    status: allow

services:
  batch-processor:
    image: processor:latest
    cpu: 8
    memory: 16Gi

    autoscaling:
      enabled: true
      min_replicas: 0      # Scale to zero
      max_replicas: 100    # Massive scale
```

**Use Case**: Video encoding, data processing, simulations

## Akash Network Characteristics

### Costs

Lowest in the industry:

| Resource | Akash | DFC | GCP |
|----------|-------|-----|-----|
| **2 CPU, 4GB RAM** | $12/mo | $24/mo | $45/mo |
| **4 CPU, 8GB RAM** | $24/mo | $48/mo | $90/mo |
| **8 CPU, 16GB RAM** | $48/mo | $96/mo | $180/mo |
| **Egress (1TB)** | $0 | $0 | $5/mo |

**Savings**: 70-80% vs GCP, 50% vs DFC

### Global Coverage

Akash providers in 50+ countries:

**North America**: USA, Canada, Mexico
**South America**: Brazil, Argentina, Chile
**Europe**: 30+ countries (UK, Germany, France, etc.)
**Asia**: India, Singapore, Japan, South Korea
**Africa**: South Africa, Kenya, Nigeria
**Oceania**: Australia, New Zealand

### Provider Characteristics

| Aspect | Typical Range | Notes |
|--------|---------------|-------|
| **Uptime** | 85-99.5% | Highly variable |
| **Performance** | Variable | No SLA |
| **Latency** | Regional | Depends on location |
| **Support** | Community | No enterprise support |

## Akash Bidding System

### How Bidding Works

1. **You specify requirements**:
   ```yaml
   services:
     app:
       cpu: 2
       memory: 4Gi
   ```

2. **Providers bid**:
   ```
   Provider A: $10/month (US-East)
   Provider B: $8/month (EU-West)
   Provider C: $12/month (Asia-SE)
   ```

3. **Server selects winner**:
   - Lowest price (if prefer/allow)
   - Available capacity (if fallback)
   - Geographic constraints

### Price Volatility

Akash pricing fluctuates based on:
- Network demand
- Provider supply
- Geographic region
- Resource type (CPU vs GPU)

**Example**: Same workload over 30 days:
- Low: $8/month
- High: $15/month
- Average: $12/month

**Mitigation**: Use `fallback` status for predictable baseline costs.

## Akash Features

### Compute
- ✅ CPU: Any size
- ✅ Memory: Any size
- ✅ GPU: NVIDIA, AMD (provider-dependent)
- ⚠️ Autoscaling: Supported but slower
- ✅ Spot pricing: Built-in (all is "spot")

### Networking
- ✅ Zero egress fees
- ⚠️ Public IPs: Provider-dependent
- ⚠️ TLS: Manual or gateway-based
- ⚠️ Load balancing: Limited
- ⚠️ IPv6: Provider-dependent

### Storage
- ⚠️ Persistent volumes: Provider-dependent (risky)
- ✅ Ephemeral storage: Yes
- ⚠️ Encrypted volumes: Provider-dependent
- ❌ Managed databases: Not recommended

### Security & Compliance
- ⚠️ VPC isolation: Provider-dependent
- ⚠️ Network policies: Basic K8s
- ❌ Confidential compute: Not available
- ❌ Compliance certifications: None

## Best Practices

### 1. Use as Fallback Only

```yaml
akash:
  status: fallback         # Not prefer or allow
```

This ensures:
- Predictable costs (Akash rarely used)
- Reliable baseline (GCP/DFC handle normal load)
- Emergency capacity (Akash available for spikes)

### 2. Disable Public Gateway

```yaml
gcp:
  public_gateway:
    enabled: true

akash:
  public_gateway:
    enabled: false         # Use GCP gateway
```

Akash gateways are unreliable for production traffic.

### 3. Stateless Workloads Only

**Good**: API servers, workers, batch jobs

```yaml
services:
  api:
    image: myapp:latest
    autoscaling:
      min_replicas: 0      # Can tolerate restarts
      max_replicas: 100
```

**Bad**: Databases, caches, stateful apps

### 4. Set Realistic Expectations

Akash is:
- ✅ Cheap
- ✅ Globally distributed
- ❌ Not reliable
- ❌ Not compliant
- ❌ Not for production baseline

### 5. Monitor Closely

```yaml
observability:
  metrics:
    endpoint: /metrics
    custom_labels:
      provider: akash

  alerts:
    - name: akash_high_restart_rate
      query: rate(akash_restarts[5m]) > 0.1
      action: page
```

Watch for:
- Frequent pod restarts
- High latency
- Provider unavailability

## Limitations

### Hard Limitations

1. **No SLA**: Providers can go offline anytime
2. **No compliance**: No GDPR, SOC2, PCI-DSS guarantees
3. **Variable performance**: CPU/network speeds vary
4. **Community support**: No enterprise helpdesk
5. **Limited observability**: Provider-dependent monitoring

### Practical Limitations

1. **Deployment time**: Slower than GCP/DFC (bidding process)
2. **Provider churn**: May need to migrate between providers
3. **Network isolation**: Limited inter-service networking
4. **Storage reliability**: Persistent volumes risky
5. **Debugging**: Limited access to underlying infrastructure

## Troubleshooting

### "No bids received"

**Issue**: No Akash providers bidding on your deployment

**Causes**:
- Resources too large (e.g., 64 CPU)
- GPU requirements (limited availability)
- Price ceiling too low

**Solutions**:

1. Reduce resources:
   ```yaml
   services:
     app:
       cpu: 4              # Instead of 16
       memory: 8Gi         # Instead of 32Gi
   ```

2. Remove GPU requirement temporarily:
   ```yaml
   services:
     app:
       # gpu:              # Comment out
       #   count: 1
   ```

3. Add DFC as fallback:
   ```yaml
   dfc:
     status: allow         # Backup for Akash
   ```

### "Pod keeps restarting on Akash"

**Issue**: Akash provider unstable

**Solution**: Exclude problematic providers (future feature):
```yaml
akash:
  provider_blacklist:      # Roadmap
    - "akash1bad..."
```

**Temporary fix**: Promote DFC/GCP:
```yaml
dfc:
  status: prefer           # Use DFC instead

akash:
  status: fallback         # Demote Akash
```

### "High latency from Akash"

**Issue**: Provider in distant geographic region

**Solution**: Use geographic scope:
```yaml
regions:
  geographic_scope: NA     # North America only
  count: 3
```

Akash will only bid from North American providers.

### "Akash costs higher than expected"

**Issue**: Bidding prices increased due to demand

**Solution**: Set maximum budget in org policy:
```yaml
policy:
  budget:
    max_monthly: 500       # Cap at $500/month
    alerts:
      - threshold: 80%     # Alert at $400
```

## Akash vs DFC vs GCP

### Quick Comparison

| Factor | GCP | DFC | Akash |
|--------|-----|-----|-------|
| **Reliability** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ |
| **Cost** | $$$$ | $$ | $ |
| **Compliance** | ✅ Full | ⚠️ Self-cert | ❌ None |
| **Support** | ✅ Enterprise | ✅ Email | ⚠️ Community |
| **Geographic** | 35+ regions | 8+ locations | 50+ countries |
| **SLA** | 99.95% | ~99% | None |
| **Egress fees** | $0.005/GB | $0 | $0 |

### Decision Matrix

**Use GCP when**:
- Production baseline
- Compliance required
- Need SLA
- Databases

**Use DFC when**:
- Cost-sensitive
- Burst capacity
- Stateless workloads
- No strict compliance

**Use Akash when**:
- Extreme cost optimization
- Emergency overflow
- Batch processing
- Testing/dev environments

## Roadmap

### Akash Network Roadmap

- **Confidential Compute**: TEE support (2026)
- **Provider Tiers**: Certified vs community providers
- **SLA Options**: Premium providers with guarantees
- **Persistent Storage**: Replicated, reliable storage layer

### Blazing Integration Roadmap

- **Provider scoring**: AI-driven provider selection
- **Blacklist support**: Exclude bad providers
- **Cost caps**: Per-provider budget limits
- **Performance monitoring**: Real-time provider metrics

## Next Steps

- [Provider Configuration](/docs/overview)
- 
- [Provider Scoring](/docs/overview)
- [Multi-Provider Setup](/docs/overview)


Configure Akash Network for decentralized, cost-effective overflow capacity

Akash Provider Configuration

Define and configure your services and workloads

Service Configuration


Services are the core building blocks of your application in Blazing Core Compose. Each service represents a containerized workload with its own configuration, resources, and scaling policies.

## Service Definition

A service is defined under the `services` block:

```yaml
version: "v0.2"

services:
  api:                      # Service name
    image: myapp:latest     # Container image
    cpu: 2                  # CPU cores
    memory: 4Gi             # Memory allocation
```

## Minimal Service

The smallest viable service configuration:

```yaml
services:
  web:
    image: nginx:latest
    cpu: 1
    memory: 2Gi
```

This creates a single replica with fixed resources.

## Complete Service Anatomy

Here's a fully configured service with all available options:

```yaml
services:
  api:
    # Container configuration
    image: registry.example.com/api:v2.1.0
    command: ["./api-server"]
    args: ["--port=8080", "--workers=4"]

    # Resource allocation
    cpu: 2
    memory: 4Gi

    # Environment and secrets
    variables:
      DATABASE_URL: postgres://db.example.com/mydb
      LOG_LEVEL: info
      ENVIRONMENT: production

    secrets:
      API_KEY: "!ref:secrets.api-key"
      DB_PASSWORD: "!ref:secrets.db-password"

    # Storage
    storage:
      - path: /data
        size: 10Gi
        type: persistent

    # GPU configuration
    gpu:
      count: 1
      model: nvidia-a100
      sharing:
        mode: exclusive

    # Autoscaling
    autoscaling:
      enabled: true
      min_replicas: 3
      max_replicas: 20
      target_cpu_percent: 70
      target_memory_percent: 80

    # Networking
    network:
      ingress:
        expose:
          - port: 443
            protocol: HTTPS
            tls:
              auto: true
      egress:
        lock_country: true

    # Placement constraints
    placement:
      residency:
        require_countries: ["US", "CA"]
      confidential_compute: preferred

    # Observability
    observability:
      metrics:
        endpoint: /metrics
        format: prometheus
      logs:
        stdout: true
        structured: json

    # Governance
    controls: [PCI-DSS-4.0, DATA-RESIDENCY-NA]
    profiles: [high-availability, cost-optimized]
```

## Field Reference

### Required Fields

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `image` | string | Container image (registry/name:tag) | `nginx:latest` |
| `cpu` | number | CPU cores (can be fractional) | `2` or `0.5` |
| `memory` | string | Memory allocation with unit | `4Gi` or `512Mi` |

### Container Configuration

#### Image

```yaml
services:
  api:
    image: registry.example.com/api:v2.1.0
```

Supported registries:
- Docker Hub: `nginx:latest`
- GitHub Container Registry: `ghcr.io/user/image:tag`
- Google Container Registry: `gcr.io/project/image:tag`
- Private registries: `registry.example.com/image:tag`

#### Command and Args

Override container entrypoint and arguments:

```yaml
services:
  api:
    image: myapp:latest
    command: ["./custom-entrypoint.sh"]
    args: ["--port=8080", "--debug"]
```

**Note**: `command` replaces ENTRYPOINT, `args` replaces CMD.

### Resource Allocation

#### CPU

Specify CPU cores (fractional or integer):

```yaml
services:
  # Small service
  worker:
    cpu: 0.5              # Half a core

  # Medium service
  api:
    cpu: 2                # 2 cores

  # Large service
  batch:
    cpu: 8                # 8 cores
```

**Cost Impact**: Linear scaling (2 CPU = 2x cost of 1 CPU)

#### Memory

Specify memory with units:

```yaml
services:
  # 512 megabytes
  cache:
    memory: 512Mi

  # 4 gigabytes
  api:
    memory: 4Gi

  # 16 gigabytes
  database:
    memory: 16Gi
```

**Supported Units**: `Mi` (mebibytes), `Gi` (gibibytes)

**Cost Impact**: Linear scaling (4Gi = 2x cost of 2Gi)

### Environment Variables

#### Variables (Plain Text)

```yaml
services:
  api:
    variables:
      DATABASE_URL: postgres://db.example.com/prod
      LOG_LEVEL: info
      ENVIRONMENT: production
      MAX_CONNECTIONS: "100"
```

**Note**: All values are strings (quote numbers).

#### Secrets (Encrypted)

```yaml
services:
  api:
    secrets:
      API_KEY: "!ref:secrets.stripe-api-key"
      DB_PASSWORD: "!ref:secrets.postgres-password"
      JWT_SECRET: "!ref:secrets.jwt-signing-key"
```

Secrets are:
- Encrypted at rest
- Injected as environment variables
- Never logged
- Rotatable via API

**Create secrets via CLI**:

```bash
core secrets create stripe-api-key "sk_live_abc123..."
core secrets create postgres-password "secure-password"
```

## Service Naming

Service names must:
- Be lowercase alphanumeric
- Start with a letter
- Use hyphens for word separation
- Be 1-63 characters long

**Good Names**:
```yaml
services:
  api:           # ✓
  web-frontend:  # ✓
  worker-batch:  # ✓
  db-primary:    # ✓
```

**Bad Names**:
```yaml
services:
  API:           # ✗ Uppercase
  web_frontend:  # ✗ Underscores
  1worker:       # ✗ Starts with number
  very-long-service-name-that-exceeds-the-maximum-length-limit:  # ✗ Too long
```

## Multi-Service Applications

Define multiple services in one deployment:

```yaml
services:
  # Frontend
  web:
    image: myapp/web:latest
    cpu: 1
    memory: 2Gi
    autoscaling:
      min_replicas: 3
      max_replicas: 10

  # Backend API
  api:
    image: myapp/api:latest
    cpu: 2
    memory: 4Gi
    autoscaling:
      min_replicas: 5
      max_replicas: 50

  # Background Workers
  worker:
    image: myapp/worker:latest
    cpu: 4
    memory: 8Gi
    autoscaling:
      min_replicas: 2
      max_replicas: 100

  # Database
  database:
    image: postgres:15
    cpu: 4
    memory: 16Gi
    autoscaling:
      enabled: false    # Fixed size for database
    storage:
      - path: /var/lib/postgresql/data
        size: 100Gi
        type: persistent
```

## Service Communication

Services within the same cluster can communicate via DNS:

```yaml
services:
  api:
    variables:
      DATABASE_URL: postgres://database:5432/mydb
      CACHE_URL: redis://cache:6379
      QUEUE_URL: amqp://queue:5672

  database:
    image: postgres:15

  cache:
    image: redis:7

  queue:
    image: rabbitmq:3
```

**DNS Format**: `{service-name}:{port}`

## Resource Sizing Guide

### CPU Recommendations

| Workload Type | CPU | Example |
|---------------|-----|---------|
| **Static site** | 0.25-0.5 | Simple HTML/JS |
| **API server** | 1-2 | REST/GraphQL API |
| **Web app** | 2-4 | Next.js, React SSR |
| **Worker** | 4-8 | Data processing |
| **Batch job** | 8-16 | ML training, encoding |

### Memory Recommendations

| Workload Type | Memory | Example |
|---------------|--------|---------|
| **Static site** | 512Mi-1Gi | nginx, S3 proxy |
| **API server** | 2Gi-4Gi | Node.js, Go API |
| **Web app** | 4Gi-8Gi | Rails, Django |
| **Worker** | 8Gi-16Gi | Python workers |
| **Database** | 16Gi-32Gi+ | PostgreSQL, MongoDB |

### Right-Sizing Example

Start conservative, scale up based on metrics:

**Phase 1**: Initial deployment

```yaml
services:
  api:
    cpu: 1
    memory: 2Gi
    autoscaling:
      min_replicas: 2
      max_replicas: 10
```

**Phase 2**: After monitoring (CPU at 80%)

```yaml
services:
  api:
    cpu: 2              # Doubled CPU
    memory: 2Gi         # Memory OK
    autoscaling:
      min_replicas: 2
      max_replicas: 10
```

**Phase 3**: After growth (scaling frequently)

```yaml
services:
  api:
    cpu: 2
    memory: 2Gi
    autoscaling:
      min_replicas: 5   # Increased baseline
      max_replicas: 20  # Increased ceiling
```

## Health Checks

### Liveness Probe

Check if container is alive:

```yaml
services:
  api:
    health:
      liveness:
        http:
          path: /health
          port: 8080
        initial_delay_seconds: 30
        period_seconds: 10
        timeout_seconds: 5
        failure_threshold: 3
```

**Behavior**: Restart container if checks fail.

### Readiness Probe

Check if container is ready for traffic:

```yaml
services:
  api:
    health:
      readiness:
        http:
          path: /ready
          port: 8080
        initial_delay_seconds: 10
        period_seconds: 5
        timeout_seconds: 3
        failure_threshold: 3
```

**Behavior**: Remove from load balancer if checks fail.

## Common Patterns

### Pattern 1: Stateless API

```yaml
services:
  api:
    image: myapi:latest
    cpu: 2
    memory: 4Gi
    autoscaling:
      enabled: true
      min_replicas: 3
      max_replicas: 20
    network:
      ingress:
        expose:
          - port: 443
            tls:
              auto: true
```

### Pattern 2: Background Worker

```yaml
services:
  worker:
    image: myworker:latest
    cpu: 4
    memory: 8Gi
    autoscaling:
      enabled: true
      min_replicas: 0      # Scale to zero
      max_replicas: 100
    # No ingress (internal only)
```

### Pattern 3: Database

```yaml
services:
  database:
    image: postgres:15
    cpu: 4
    memory: 16Gi
    autoscaling:
      enabled: false       # Fixed size
    storage:
      - path: /var/lib/postgresql/data
        size: 100Gi
        type: persistent
```

### Pattern 4: GPU Workload

```yaml
services:
  ml-trainer:
    image: ml-training:latest
    cpu: 8
    memory: 32Gi
    gpu:
      count: 2
      model: nvidia-a100
    autoscaling:
      min_replicas: 0
      max_replicas: 10
```

## Next Steps

- [Autoscaling Configuration](/docs/autoscaling)
- [Networking Configuration](/docs/service-basics)
- [Storage Configuration](/docs/service-basics)
- [GPU Configuration](/docs/service-basics)


Learn how to configure services in Blazing Core Compose

Service Configuration Basics


Autoscaling automatically adjusts the number of service replicas based on demand, optimizing both performance and cost.

## Basic Autoscaling

```yaml
services:
  api:
    image: myapp:latest
    cpu: 2
    memory: 4Gi

    autoscaling:
      enabled: true
      min_replicas: 3
      max_replicas: 20
      target_cpu_percent: 70
```

## Configuration Reference

### Complete Autoscaling Block

```yaml
services:
  api:
    autoscaling:
      # Basic settings
      enabled: true
      min_replicas: 3
      max_replicas: 20

      # CPU-based scaling
      target_cpu_percent: 70

      # Memory-based scaling (optional)
      target_memory_percent: 80

      # Scaling behavior
      scale_up_cooldown_seconds: 45
      scale_down_cooldown_seconds: 300

      # Custom metrics (optional)
      custom_metrics:
        active_connections:
          target: 100
          scale_down_threshold: 30
```

### Field Reference

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | false | Enable/disable autoscaling |
| `min_replicas` | number | 1 | Minimum replicas (0 for scale-to-zero) |
| `max_replicas` | number | 10 | Maximum replicas (hard ceiling) |
| `target_cpu_percent` | number | 70 | Target CPU utilization (%) |
| `target_memory_percent` | number | none | Optional memory threshold |
| `scale_up_cooldown_seconds` | number | 45 | Wait time before next scale-up |
| `scale_down_cooldown_seconds` | number | 300 | Wait time before scale-down |

## Scaling Strategies

### Strategy 1: Conservative (High Availability)

Keep ample headroom for traffic spikes:

```yaml
autoscaling:
  enabled: true
  min_replicas: 5          # High baseline
  max_replicas: 50
  target_cpu_percent: 50   # Scale at 50% CPU
  scale_up_cooldown_seconds: 30    # Fast scale-up
  scale_down_cooldown_seconds: 600 # Slow scale-down
```

**Use Case**: Production APIs, critical services

**Cost**: Higher baseline ($$$)

### Strategy 2: Balanced (Standard)

Balance cost and performance:

```yaml
autoscaling:
  enabled: true
  min_replicas: 3          # Moderate baseline
  max_replicas: 20
  target_cpu_percent: 70   # Scale at 70% CPU
  scale_up_cooldown_seconds: 45
  scale_down_cooldown_seconds: 300
```

**Use Case**: Most web applications

**Cost**: Moderate ($$)

### Strategy 3: Aggressive (Cost-Optimized)

Minimize replicas, scale reactively:

```yaml
autoscaling:
  enabled: true
  min_replicas: 1          # Minimal baseline
  max_replicas: 20
  target_cpu_percent: 85   # Scale at 85% CPU
  scale_up_cooldown_seconds: 60    # Slower scale-up
  scale_down_cooldown_seconds: 180 # Faster scale-down
```

**Use Case**: Dev/staging, batch jobs

**Cost**: Low ($)

### Strategy 4: Scale-to-Zero (Event-Driven)

No baseline cost when idle:

```yaml
autoscaling:
  enabled: true
  min_replicas: 0          # Scale to zero
  max_replicas: 100
  target_cpu_percent: 70
  scale_up_cooldown_seconds: 0     # Immediate scale-up
  scale_down_cooldown_seconds: 300
```

**Use Case**: Batch processing, webhooks, scheduled jobs

**Cost**: Minimal (pay only when running)

**Note**: Cold starts add 5-15 seconds latency.

## CPU-Based Scaling

### How It Works

1. Monitor average CPU across all replicas
2. If CPU > `target_cpu_percent`: scale up
3. If CPU < `target_cpu_percent`: scale down

### Scaling Formula

```
desired_replicas = current_replicas × (current_cpu / target_cpu)
```

**Example**:
- Current: 5 replicas at 90% CPU
- Target: 70% CPU
- Desired: 5 × (90 / 70) = 6.4 → **7 replicas**

### CPU Target Recommendations

| Target | Behavior | Use Case |
|--------|----------|----------|
| **50%** | Aggressive headroom | Critical services |
| **70%** | Balanced (default) | Standard applications |
| **85%** | Minimal headroom | Cost-sensitive |

**Warning**: Targets >85% risk saturation during scale-up lag.

## Memory-Based Scaling

Optional secondary metric:

```yaml
autoscaling:
  target_cpu_percent: 70
  target_memory_percent: 80
```

**Behavior**: Scale if **either** CPU or memory exceeds target.

### When to Use Memory Scaling

✅ **Use memory scaling when**:
- Application is memory-intensive (caching, data processing)
- Memory leaks are possible
- OOM kills would be catastrophic

❌ **Skip memory scaling when**:
- Application memory is stable
- CPU is the bottleneck
- Simplicity is preferred

## Cooldown Periods

### Scale-Up Cooldown

Wait time before **another scale-up**:

```yaml
scale_up_cooldown_seconds: 45    # Wait 45s between scale-ups
```

**Purpose**: Prevent thrashing during metric spikes.

**Recommendations**:
- **Fast APIs**: 30-45s
- **Slow startup**: 60-120s
- **Cold start**: 180s+

### Scale-Down Cooldown

Wait time before **scale-down**:

```yaml
scale_down_cooldown_seconds: 300    # Wait 5 minutes
```

**Purpose**: Prevent premature scale-down during temporary dips.

**Recommendations**:
- **Stable traffic**: 180-300s
- **Variable traffic**: 600s
- **Expensive startup**: 900s+

## Custom Metrics

Scale based on application-specific metrics:

```yaml
autoscaling:
  enabled: true
  min_replicas: 2
  max_replicas: 50

  custom_metrics:
    # Active database connections
    active_connections:
      target: 100
      scale_down_threshold: 30
      query: |
        avg_over_time(pg_stat_activity_count[1m])

    # Queue depth
    queue_depth:
      target: 1000
      scale_down_threshold: 100
      query: |
        rabbitmq_queue_messages{queue="tasks"}

    # Request latency (p95)
    p95_latency_ms:
      target: 200
      scale_up_threshold: 250
      query: |
        histogram_quantile(0.95,
          rate(http_request_duration_ms_bucket[1m])
        )
```

### Custom Metric Fields

| Field | Type | Description |
|-------|------|-------------|
| `target` | number | Ideal metric value |
| `scale_down_threshold` | number | Scale down below this |
| `scale_up_threshold` | number | Scale up above this (optional) |
| `query` | string | Prometheus query |

### Custom Metric Flow

```
1. Scrape: Prometheus adapter collects metrics
2. Normalize: Convert to percentage or absolute value
3. Evaluate: Autoscaler compares to target
4. Action: Scale up/down based on thresholds
```

## Real-World Examples

### Example 1: Production API

```yaml
services:
  api:
    image: myapp/api:v2
    cpu: 2
    memory: 4Gi

    autoscaling:
      enabled: true
      min_replicas: 5        # Always 5+ for redundancy
      max_replicas: 50       # Cap at 50
      target_cpu_percent: 65 # Conservative target

      # Fast scale-up for traffic spikes
      scale_up_cooldown_seconds: 30

      # Slow scale-down to avoid yo-yo
      scale_down_cooldown_seconds: 600
```

**Result**:
- Baseline: 5 replicas ($50/month)
- Peak: 30 replicas during business hours
- Cost: ~$180/month (vs $500/month fixed 50 replicas)

### Example 2: Batch Worker

```yaml
services:
  worker:
    image: myapp/worker:v1
    cpu: 4
    memory: 8Gi

    autoscaling:
      enabled: true
      min_replicas: 0        # Scale to zero when idle
      max_replicas: 100      # Massive burst capacity

      custom_metrics:
        queue_depth:
          target: 100        # 100 jobs per worker
          query: |
            rabbitmq_queue_messages{queue="tasks"}
```

**Result**:
- Idle: 0 replicas ($0/month)
- Active: Scales to match queue (1 replica per 100 jobs)
- Cost: Pay only for processing time

### Example 3: Database Proxy

```yaml
services:
  pgbouncer:
    image: pgbouncer:latest
    cpu: 1
    memory: 2Gi

    autoscaling:
      enabled: true
      min_replicas: 2        # Always 2 for HA
      max_replicas: 10       # Limited burst

      custom_metrics:
        active_connections:
          target: 200        # 200 connections per proxy
          scale_down_threshold: 50
          query: |
            avg_over_time(pgbouncer_active_clients[1m])
```

**Result**:
- Baseline: 2 proxies (400 connections)
- Peak: 8 proxies (1,600 connections)
- Cost: ~$30/month

### Example 4: ML Inference

```yaml
services:
  inference:
    image: ml-model:v3
    cpu: 8
    memory: 16Gi
    gpu:
      count: 1
      model: nvidia-a100

    autoscaling:
      enabled: true
      min_replicas: 1        # Keep 1 warm
      max_replicas: 20       # Scale to 20 GPUs

      target_cpu_percent: 70

      custom_metrics:
        inference_queue:
          target: 50         # 50 queued requests per GPU
          query: |
            sum(rate(inference_queue_depth[1m]))
```

**Result**:
- Warm: 1 GPU ready ($2/hour)
- Peak: 10 GPUs during batch inference
- Cost: ~$1,500/month (vs $14,000/month for 20 fixed GPUs)

## Troubleshooting

### Issue: Service Not Scaling Up

**Symptom**: CPU at 100%, but replicas not increasing

**Causes**:

1. **Hit max_replicas**:
   ```yaml
   max_replicas: 5    # Increase this
   ```

2. **Scale-up cooldown active**:
   ```yaml
   scale_up_cooldown_seconds: 300    # Reduce this
   ```

3. **Provider capacity exhausted**:
   - Add more providers
   - Check region availability

**Solution**:

```bash
# Check autoscaler status
core services describe api --show-autoscaler

# View scaling events
core events list --service api --type scaling
```

### Issue: Service Scaling Too Aggressively

**Symptom**: Constantly scaling up/down (yo-yo effect)

**Cause**: Cooldowns too short

**Solution**:

```yaml
autoscaling:
  scale_up_cooldown_seconds: 60      # Increase
  scale_down_cooldown_seconds: 600   # Increase
```

### Issue: Slow Scale-Up

**Symptom**: Latency spikes before scaling kicks in

**Solutions**:

1. **Lower CPU target**:
   ```yaml
   target_cpu_percent: 60    # From 70
   ```

2. **Increase min_replicas**:
   ```yaml
   min_replicas: 5          # From 3
   ```

3. **Reduce cooldown**:
   ```yaml
   scale_up_cooldown_seconds: 30    # From 60
   ```

### Issue: Scale-to-Zero Not Working

**Symptom**: Service stays at min_replicas despite no traffic

**Cause**: min_replicas > 0

**Solution**:

```yaml
autoscaling:
  min_replicas: 0    # Enable scale-to-zero
```

**Note**: Requires container to start in <15s for best experience.

## Best Practices

### 1. Start Conservative

```yaml
# Initial deployment
autoscaling:
  min_replicas: 3
  max_replicas: 10
  target_cpu_percent: 70
```

Monitor for 1-2 weeks, then optimize.

### 2. Set Realistic Maximums

Don't set max_replicas arbitrarily high:

```yaml
# Bad: Unlimited ceiling
max_replicas: 1000    # ✗ Risk of huge costs

# Good: Realistic ceiling
max_replicas: 50      # ✓ Based on expected traffic
```

### 3. Longer Scale-Down Cooldowns

Scale down slowly to avoid instability:

```yaml
scale_up_cooldown_seconds: 45      # Fast
scale_down_cooldown_seconds: 600   # Slow (10x)
```

### 4. Monitor Autoscaler Behavior

```yaml
observability:
  metrics:
    endpoint: /metrics
  alerts:
    - name: frequent_scaling
      query: rate(autoscaling_events[5m]) > 10
      action: investigate
```

### 5. Test Under Load

Use load testing to validate:

```bash
# Load test with scaling
core load-test api --rps 1000 --duration 10m --watch-scaling
```

## Next Steps

- [Custom Metrics](/docs/autoscaling)
- [Load Testing](/docs/autoscaling)
- 
- [Service Monitoring](/docs/service-basics)


Configure horizontal autoscaling for your services

Autoscaling Configuration

Deploy, manage, and monitor your infrastructure

Deployment & Operations


Blazing Core Compose follows a structured deployment lifecycle: **validate → plan → apply → monitor**.

## Lifecycle Overview

```
┌─────────────┐
│   Source    │  compose.yaml
│   (YAML)    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Validate   │  Schema + Policy checks (CLI)
│   (Local)   │  ✓ Fast feedback (50-200ms)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Plan     │  Show intent (CLI + Server)
│  (Preview)  │  ✓ Cost estimate, region selection
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Apply    │  Provision infrastructure (Server)
│  (Deploy)   │  ✓ Atomic execution
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Monitor   │  Track health and performance
│ (Operation) │  ✓ Metrics, logs, alerts
└─────────────┘
```

## Phase 1: Validate

Local validation of YAML configuration.

### Command

```bash
core validate compose.yaml
```

### What It Checks

1. **YAML Syntax**: Valid YAML structure
2. **Schema Compliance**: Matches Core Compose v0.2.0 schema
3. **Feature Availability**: Requested features are supported
4. **Policy Requirements**: Org-level policies are met
5. **Control Satisfaction**: Compliance controls can be satisfied

### Sample Output

```
Validating compose.yaml...

✓ YAML syntax valid
✓ Schema compliance (v0.2.0)
✓ Feature checks passed
✓ Policy requirements met
✓ Controls validated

Configuration is valid and ready to deploy.
```

### Validation Errors

```bash
$ core validate compose.yaml

ERROR: Validation failed

compose.yaml:15:7
  services.api.cpu: must be a number
  Found: "2GB" (string)
  Expected: 2 (number)

compose.yaml:32:9
  services.api.autoscaling.min_replicas: must be ≥ 0
  Found: -1
  Expected: 0 or greater

2 errors found. Fix these issues and try again.
```

## Phase 2: Plan

Preview what will be deployed without actually deploying.

### Command

```bash
core plan compose.yaml
```

### What It Shows

1. **Provider Selection**: Which providers will be used
2. **Region Allocation**: Specific regions to be provisioned
3. **Resource Summary**: CPU, memory, GPU, storage
4. **Cost Estimate**: Monthly cost with variance
5. **Compliance Status**: Controls met/unmet
6. **Placement Rationale**: Why providers were chosen

### Sample Output

```bash
$ core plan compose.yaml

Computing deployment plan...

═══════════════════════════════════════════════
  Deployment Plan
═══════════════════════════════════════════════

Organization: acme-corp
Project:      production
Cluster:      api-backend-cluster

───────────────────────────────────────────────
  Provider Selection
───────────────────────────────────────────────

Primary Providers:
  • GCP (3 regions)  - Reliability + spot savings
  • DFC (2 regions)  - Cost optimization

Fallback Providers:
  • Akash (global)   - Emergency capacity

───────────────────────────────────────────────
  Regional Distribution
───────────────────────────────────────────────

GCP Regions:
  ├─ us-central1 (Iowa)          $52/mo
  ├─ us-east1 (South Carolina)   $52/mo
  └─ us-west1 (Oregon)            $52/mo

DFC Regions:
  ├─ chicago (Illinois)           $31/mo
  └─ ashburn (Virginia)           $31/mo

───────────────────────────────────────────────
  Services
───────────────────────────────────────────────

api (myapp/api:v2.1.0):
  • 3-20 replicas (autoscaling enabled)
  • Resources: 2 CPU, 4Gi memory per replica
  • Ingress: HTTPS (TLS auto-provisioned)
  • Cost: $45-180/mo (depends on load)

worker (myapp/worker:v2.1.0):
  • 2-50 replicas (autoscaling enabled)
  • Resources: 4 CPU, 8Gi memory per replica
  • Cost: $90-450/mo (depends on queue depth)

───────────────────────────────────────────────
  Compliance
───────────────────────────────────────────────

✓ PCI-DSS-4.0:        Met (TLS + WAF enabled)
✓ DATA-RESIDENCY-NA:  Met (US/CA regions only)

───────────────────────────────────────────────
  Cost Estimate
───────────────────────────────────────────────

Monthly Cost: $218 ± 35%
  ├─ Baseline (min replicas): $135/mo
  ├─ Burst (autoscaling):     $50-250/mo
  ├─ Networking:              $18/mo
  └─ Storage:                 $15/mo

Annual Cost (estimated): $2,616

───────────────────────────────────────────────
  Placement Rationale
───────────────────────────────────────────────

1. GCP selected for baseline (score: 92/100)
   ✓ High reliability (99.95% SLA)
   ✓ Spot instances (60% savings)
   ✓ Standard tier (17x cheaper egress)
   ✓ All features available

2. DFC selected for burst (score: 87/100)
   ✓ Zero egress fees
   ✓ 60% cheaper than GCP standard
   ✓ Curated providers (>99% uptime)

3. Akash on standby (score: 65/100)
   ✓ Available for overflow
   ✗ Variable reliability

═══════════════════════════════════════════════

Ready to deploy? Run: core apply compose.yaml
```

### Plan Options

```bash
# Show detailed provider scoring
core plan --show-scoring

# Show effective merged YAML
core plan --show-effective

# Export plan as JSON
core plan --output json > plan.json

# Estimate cost for specific load
core plan --load-profile high    # High traffic scenario
```

## Phase 3: Apply

Execute the deployment plan.

### Command

```bash
core apply compose.yaml
```

### What It Does

1. **Server-Side Orchestration**: API runs placement algorithm
2. **Resource Provisioning**: Creates compute nodes, IPs, storage
3. **Network Setup**: Configures ingress/egress, TLS certificates
4. **Service Deployment**: Deploys containers across regions
5. **Health Verification**: Waits for readiness probes
6. **Audit Logging**: Records deployment details

### Sample Output

```bash
$ core apply compose.yaml

Applying deployment...

⚙  Validating configuration...
✓  Configuration valid

⚙  Computing placement...
✓  Selected 5 regions (3 GCP, 2 DFC)

⚙  Provisioning infrastructure...
├─ Creating GCP clusters... done
├─ Creating DFC deployments... done
├─ Allocating IPs... done
└─ Provisioning storage... done

⚙  Configuring networking...
├─ Setting up ingress... done
├─ Configuring TLS... done
└─ Applying firewall rules... done

⚙  Deploying services...
├─ api: 3 replicas... healthy
└─ worker: 2 replicas... healthy

✓  Deployment successful!

───────────────────────────────────────────────
  Deployment Summary
───────────────────────────────────────────────

Deployment ID: df-2025-12-03-00412
Status:        live
Endpoints:     https://api-backend.blazing.app

Services:
  • api (3 replicas) - healthy
  • worker (2 replicas) - healthy

View logs:    core logs api
View metrics: core metrics api
Scale service: core scale api --replicas 5

───────────────────────────────────────────────
```

### Apply Options

```bash
# Auto-approve (skip confirmation)
core apply --yes

# Dry-run (validate but don't deploy)
core apply --dry-run

# Watch deployment progress
core apply --watch

# Set timeout
core apply --timeout 30m
```

## Phase 4: Monitor

Track deployed services.

### Monitoring Commands

```bash
# Service status
core services list

# Service details
core services describe api

# Live logs
core logs api --follow

# Metrics
core metrics api --last 1h

# Events
core events list --service api

# Scaling status
core autoscaling status api
```

### Sample Monitoring

```bash
$ core services list

NAME     REPLICAS   STATUS     CPU      MEMORY    UPTIME
api      8/20       healthy    65%      72%       5h 23m
worker   12/50      healthy    78%      81%       5h 23m

$ core logs api --follow --tail 10

2025-12-03 15:42:31 [INFO] Request: GET /api/v1/users
2025-12-03 15:42:31 [INFO] Response: 200 (12ms)
2025-12-03 15:42:32 [INFO] Request: POST /api/v1/orders
2025-12-03 15:42:32 [INFO] Response: 201 (45ms)
```

## Deployment States

| State | Description | Actions Available |
|-------|-------------|-------------------|
| **draft** | YAML loaded but not validated | validate, plan |
| **validated** | Schema checks passed | plan, apply |
| **planning** | Computing placement | wait |
| **provisioning** | Creating infrastructure | wait, cancel |
| **deploying** | Rolling out services | wait, watch |
| **healthy** | All services running | scale, update, destroy |
| **degraded** | Some replicas unhealthy | rollback, investigate |
| **failed** | Deployment failed | retry, rollback |

## Atomic Deployments

Blazing uses **atomic deployments**: all resources succeed or all fail.

### Success Path

```
1. Provision all infrastructure  ✓
2. Deploy all services          ✓
3. Verify health checks         ✓
4. Update DNS                   ✓
→ Deployment successful
```

### Failure Path

```
1. Provision all infrastructure  ✓
2. Deploy all services          ✗  (one service fails)
3. Rollback all changes         ✓
→ Deployment failed, state restored
```

**No partial deployments**: Either everything works or nothing changes.

## Update Deployments

Modify existing deployments with `apply`:

```bash
# Edit compose.yaml
vim compose.yaml

# Apply changes
core apply compose.yaml
```

### Rolling Updates

Updates are rolled out gradually:

```
1. Deploy new replica    [new]
2. Wait for health      ✓
3. Remove old replica   [old] →
4. Repeat for all replicas
```

### Zero-Downtime Updates

Guaranteed zero downtime if:
- `min_replicas ≥ 2`
- Health checks configured
- Gradual rollout (default)

### Update Example

```bash
# Update image version
vim compose.yaml  # Change image: myapp:v2.1.0 → v2.2.0

# Apply update
$ core apply compose.yaml

Detected changes:
  • services.api.image: myapp:v2.1.0 → myapp:v2.2.0

Rolling update strategy:
  • 1 replica at a time
  • Wait for health checks
  • 30 second intervals

Proceed? [y/N]: y

Updating api service...
├─ Deploying replica 1/8... healthy
├─ Deploying replica 2/8... healthy
├─ Deploying replica 3/8... healthy
...
└─ Deploying replica 8/8... healthy

✓ Update successful (0 downtime)
```

## Rollback

Revert to previous deployment:

```bash
# View deployment history
core deployments list

# Rollback to previous
core rollback

# Rollback to specific deployment
core rollback --to df-2025-12-03-00300
```

### Automatic Rollback

Blazing automatically rolls back if:
- Health checks fail
- Deployment timeout exceeded
- Critical error during apply

## Deployment Comparison

Compare two deployments:

```bash
# Compare with previous
core diff

# Compare with specific deployment
core diff --compare df-2025-12-03-00300

# Show only service changes
core diff --services-only
```

### Sample Diff

```diff
Comparing deployments:
  Old: df-2025-12-03-00300 (deployed 2h ago)
  New: current

services.api:
  + image: myapp:v2.2.0 (was v2.1.0)
  + cpu: 4 (was 2)
  + memory: 8Gi (was 4Gi)

services.api.autoscaling:
  + max_replicas: 30 (was 20)

services.worker:
  (no changes)

Estimated cost impact: +$45/mo (+20%)
```

## Best Practices

### 1. Always Validate First

```bash
core validate compose.yaml && core plan compose.yaml && core apply compose.yaml
```

### 2. Review Plans Carefully

Check:
- Cost estimates
- Region selection
- Compliance status
- Resource allocation

### 3. Use Staged Rollouts

```bash
# Deploy to staging first
core apply --project staging

# Verify
core services list --project staging

# Deploy to production
core apply --project production
```

### 4. Monitor After Deploy

```bash
core apply compose.yaml && core logs api --follow
```

Watch for errors in the first 5-10 minutes.

### 5. Tag Deployments

```bash
core apply --tag "release-v2.2.0"
core apply --tag "hotfix-security"
```

Makes rollback easier:

```bash
core rollback --to-tag "release-v2.1.0"
```

## Next Steps

- 
- 
- 
- 


Understanding the deployment process from plan to production

Deployment Lifecycle

Understand governance features and compliance controls

Governance & Compliance


Blazing Core Compose includes a **governance layer** that tracks platform capabilities and ensures compliance through features and controls.

## Overview

Two registries govern platform capabilities:

| Registry | Purpose | Example |
|----------|---------|---------|
| **Feature Registry** | Tracks platform capabilities | GPU-MIG, NET-ANYCAST |
| **Control Registry** | Defines compliance requirements | PCI-DSS-4.0, GDPR |

Both are version-controlled and audited automatically.

## Feature Registry

### What Are Features?

Features are **specific capabilities** offered by the platform:

- **NET-ANYCAST**: Anycast IP addressing
- **GPU-MIG**: NVIDIA MIG GPU slicing
- **EGR-LOCK-COUNTRY**: Egress country lock
- **TLS-ROTATION**: TLS blue-green rotation

### Feature States

| State | Meaning | Behavior |
|-------|---------|----------|
| **implemented** | Fully available | No warnings, works everywhere |
| **experimental** | Available with warnings | Works but may change |
| **planned** | Coming soon | Warns or blocks (depends on policy) |
| **deprecated** | Being phased out | Warns, suggests replacement |
| **removed** | No longer exists | Blocks deployment |

### Feature Example

```yaml
# Feature definition (internal)
- id: GPU-MIG
  name: NVIDIA MIG GPU Slicing
  status: planned
  providers: [DFE, AWS]
  owner: gpu-team
  target_version: 0.3.0
  since: null
```

### Checking Feature Availability

```bash
# List all features
core features list

# Check specific feature
core features check GPU-MIG

# Check feature by provider
core features list --provider GCP
```

Sample output:

```bash
$ core features check GPU-MIG

Feature: GPU-MIG
Name: NVIDIA MIG GPU Slicing
Status: planned
Providers: DFE, AWS (not GCP, DFC, Akash)
Target Version: v0.3.0
Owner: gpu-team

⚠ This feature is planned but not yet implemented.
Using it will generate a warning.

Workaround: Use whole GPU allocation for now.
```

## Control Registry

### What Are Controls?

Controls are **compliance policies** that map to business requirements:

- **PCI-DSS-4.0**: Payment Card Industry compliance
- **GDPR**: European data protection
- **HIPAA**: Healthcare data compliance
- **SOC2**: Security and availability standards

### Control Structure

Controls define **required** and **optional** features:

```yaml
# Control definition (internal)
- id: PCI-DSS-4.0
  name: Payment Card Industry Security Standard
  required_features:
    - TLS-AUTO
    - WAF-ENABLED
    - LOG-AUDIT-IMMUTABLE
  optional_features:
    - TEE-ATTESTED-SECRETS
  enforcement: strict
  version_introduced: v0.2.0
```

### Declaring Controls

Add controls to your services:

```yaml
services:
  api:
    image: payment-api:latest
    controls: [PCI-DSS-4.0, DATA-RESIDENCY-EU]

    # Control requirements automatically enforced
    network:
      ingress:
        protections:
          waf: enabled        # Required by PCI-DSS
        tls:
          auto: true          # Required by PCI-DSS

    observability:
      logs:
        retention: 90d        # Required by PCI-DSS
```

### Enforcement Levels

| Mode | Description | Behavior |
|------|-------------|----------|
| **strict** | Blocking | Deployment fails if requirements not met |
| **advisory** | Warning | Warns but allows deployment |
| **informative** | Logging | Logs only, no user notification |

## Validation Flow

### Validation Process

```
1. Load features.yaml and controls.yaml
2. Load user's compose.yaml
3. For each feature used:
   - Check feature status
   - If planned → warn
   - If removed → error
4. For each control declared:
   - Check required features
   - If missing → error (strict) or warn (advisory)
5. Generate audit record
```

### Validation Pseudocode

```python
def validate_features(spec, features, policy):
    for path in spec.get_all_paths():
        feature_id = FEATURE_MAP.get(path)
        if not feature_id:
            continue

        feature = features.get(feature_id)

        if feature.status == "planned":
            warn(f"FEATURE_NOT_YET_SUPPORTED: {feature_id}")
            if policy.must_be_implemented:
                raise ValidationError

        elif feature.status == "removed":
            error(f"FEATURE_REMOVED: {feature_id}")

def validate_controls(spec, controls):
    for service in spec.services:
        for control_id in service.controls:
            ctrl = controls.get(control_id)

            missing = []
            for req in ctrl.required_features:
                if not is_feature_available(req):
                    missing.append(req)

            if missing:
                if ctrl.enforcement == "strict":
                    error(f"CONTROL_NOT_SATISFIED: {control_id}")
                elif ctrl.enforcement == "advisory":
                    warn(f"CONTROL_NOT_FULLY_MET: {control_id}")
```

## Common Controls

### PCI-DSS-4.0

Payment Card Industry compliance:

```yaml
services:
  payment-api:
    controls: [PCI-DSS-4.0]

    # Automatically requires:
    network:
      ingress:
        protections:
          waf: enabled        # ✓ Web Application Firewall
        tls:
          mode: terminate     # ✓ TLS termination

    observability:
      logs:
        retention: 90d        # ✓ Audit logs for 90 days
        immutable: true       # ✓ Tamper-proof logs
```

### DATA-RESIDENCY-EU

European data residency:

```yaml
services:
  user-data:
    controls: [DATA-RESIDENCY-EU]

    # Automatically requires:
    placement:
      residency:
        require_countries: ["PT", "ES", "FR", "DE", "NL"]

    network:
      egress:
        lock_country: true    # ✓ Prevent data leaving EU
        verification:
          method: geoip_check # ✓ Verify egress location
```

### SOC2-TYPE2

Security and availability compliance:

```yaml
services:
  saas-api:
    controls: [SOC2-TYPE2]

    # Automatically requires:
    autoscaling:
      enabled: true
      min_replicas: 3         # ✓ High availability

    observability:
      logs:
        retention: 365d       # ✓ 1 year retention
        encrypted: true       # ✓ Encrypted logs

    placement:
      confidential_compute: required  # ✓ TEE enforcement
```

### HIPAA

Healthcare data compliance:

```yaml
services:
  patient-records:
    controls: [HIPAA]

    # Automatically requires:
    storage:
      - path: /data
        size: 100Gi
        encrypted: true       # ✓ Encryption at rest

    network:
      ingress:
        tls:
          mode: mtls          # ✓ Mutual TLS

    observability:
      logs:
        retention: 2555d      # ✓ 7 year retention (HIPAA)
        audit: true           # ✓ Audit access logs
```

## Policy Hooks

### Organization-Level Policy

Set global requirements:

```yaml
# Organization policy (configured via API)
policy:
  features:
    must_be_implemented: true   # Block planned features
    must_be_verified: true      # Restrict to verified providers

  controls:
    enforce_all: strict         # All controls are strict

  budget:
    max_monthly: 10000          # $10k/month cap
```

### Project-Level Policy

Override for specific projects:

```yaml
# Staging project policy
policy:
  features:
    must_be_implemented: false  # Allow planned features

  controls:
    enforce_all: advisory       # Warn instead of block
```

## Validation Examples

### Example 1: Feature Not Yet Supported

```bash
$ core validate compose.yaml

⚠ FEATURE_NOT_YET_SUPPORTED: GPU-MIG (planned)

services.ml-trainer.gpu.sharing.mode: mig
  Feature GPU-MIG is planned for v0.3.0 but not yet available.

  Workaround: Use exclusive mode instead:
    gpu:
      sharing:
        mode: exclusive

Validation passed with 1 warning.
```

### Example 2: Control Not Satisfied

```bash
$ core validate compose.yaml

❌ CONTROL_NOT_SATISFIED: PCI-DSS-4.0

services.payment-api.controls: [PCI-DSS-4.0]
  Missing required feature: WAF-ENABLED

  Required by PCI-DSS:
    ✓ TLS-AUTO: configured
    ✗ WAF-ENABLED: missing
    ✓ LOG-AUDIT-IMMUTABLE: configured

  Fix: Add WAF to ingress:
    network:
      ingress:
        protections:
          waf: enabled

Validation failed with 1 error.
```

### Example 3: Feature Removed

```bash
$ core validate compose.yaml

❌ FEATURE_REMOVED: LEGACY-PLACEMENT

services.api.placement.legacy_mode: true
  Feature LEGACY-PLACEMENT was removed in v0.2.0.

  Migration: Use new placement syntax:
    placement:
      strategy:
        mode: cost_optimized

  See: https://blazing.work/docs/migration-v0.2

Validation failed with 1 error.
```

## Audit Records

Every deployment creates an audit record:

```json
{
  "deployment_id": "df-2025-12-03-00412",
  "action": "apply",
  "actor": "alice@acme.com",
  "timestamp": "2025-12-03T22:00:00Z",
  "hash": "sha256:8f9d7e6c...",

  "features_used": {
    "TLS-AUTO": "implemented",
    "EGR-LOCK-COUNTRY": "implemented",
    "GPU-MIG": "planned"
  },

  "controls_evaluated": {
    "PCI-DSS-4.0": "passed",
    "DATA-RESIDENCY-EU": "passed",
    "SOC2-TYPE2": "failed"
  },

  "providers": ["GCP", "DFC"],
  "regions": ["us-central1", "us-east1", "chicago"],
  "cost_actual": 187.43
}
```

### Viewing Audit Logs

```bash
# List all deployments with audit status
core audit list

# View specific deployment audit
core audit show df-2025-12-03-00412

# Export audit logs
core audit export --from 2025-12-01 --to 2025-12-31 --format json
```

## Feature Map

The **Feature Map** links YAML paths to feature IDs:

```yaml
# Internal feature map
network.ingress.anycast: NET-ANYCAST
network.egress.lock_country: EGR-LOCK-COUNTRY
gpu.sharing.mig_profile: GPU-MIG
tls.rotation.strategy: TLS-ROTATION
placement.confidential_compute: TEE-COMPUTE
```

This enables automatic feature detection:

```yaml
services:
  api:
    network:
      ingress:
        anycast: true    # → Detected as NET-ANYCAST feature
```

## Future Extensions

Planned governance enhancements:

| Extension | Description | Target Version |
|-----------|-------------|----------------|
| **depends_on** | Feature dependencies | v0.3.0 |
| **supersedes** | Replacement mapping | v0.3.0 |
| **conditions** | ALL/ANY evaluation | v0.4.0 |
| **score** | Weighted compliance | v0.4.0 |
| **custom_controls** | User-defined controls | v0.5.0 |

## Best Practices

### 1. Declare Controls Early

```yaml
services:
  api:
    controls: [PCI-DSS-4.0]    # Declare at service level
```

Validation catches issues before deployment.

### 2. Use Advisory Mode for Testing

```yaml
# Staging environment
policy:
  controls:
    enforce_all: advisory    # Warn, don't block
```

### 3. Check Features Before Using

```bash
core features check GPU-MIG
```

Avoid surprises during deployment.

### 4. Review Audit Logs Regularly

```bash
core audit list --failed
```

Track compliance failures.

### 5. Stay Updated

```bash
core features list --new
```

See newly available features.

## Next Steps

- [Compliance Guide](/docs/features-and-controls)
- [Feature Roadmap](/docs/features-and-controls)
- [Custom Controls](/docs/features-and-controls)
- [Audit Reports](/docs/features-and-controls)


Understanding the governance layer, feature registry, and compliance controls

Features and Controls

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    code: "code",
    h2: "h2",
    h3: "h3",
    li: "li",
    ol: "ol",
    p: "p",
    pre: "pre",
    span: "span",
    strong: "strong",
    ul: "ul",
    ...props.components
  }, {PreviewCode} = _components;
  if (!PreviewCode) _missingMdxReference("PreviewCode", true);
  return _jsxs(_Fragment, {
    children: [_jsxs(_components.h2, {
      id: "prerequisites",
      children: ["Prerequisites", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#prerequisites",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "A Digital Frontier account"
      }), "\n", _jsx(_components.li, {
        children: "Core CLI installed"
      }), "\n"]
    }), "\n", _jsxs(_components.h2, {
      id: "installation",
      children: ["Installation", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#installation",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.h3, {
      id: "macos",
      children: ["macOS", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#macos",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "brew install blazing-cli\n"
      })
    }), "\n", _jsxs(_components.h3, {
      id: "linux",
      children: ["Linux", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#linux",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "curl -fsSL https://get.digitalfrontier.so/core | sh\n"
      })
    }), "\n", _jsxs(_components.h3, {
      id: "verify-installation",
      children: ["Verify Installation", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#verify-installation",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core --version\n"
      })
    }), "\n", _jsxs(_components.h2, {
      id: "initialize-your-project",
      children: ["Initialize Your Project", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#initialize-your-project",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.p, {
      children: "Create a new project directory:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "mkdir my-app && cd my-app\ncore init\n"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["This creates a basic ", _jsx(_components.code, {
        children: "compose.yaml"
      }), " file."]
    }), "\n", _jsxs(_components.h2, {
      id: "your-first-service",
      children: ["Your First Service", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#your-first-service",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.p, {
      children: ["Edit ", _jsx(_components.code, {
        children: "compose.yaml"
      }), " to define a simple web service:"]
    }), "\n", _jsx(PreviewCode, {
      tier: "dev-preview",
      lines: "14",
      lang: "yaml",
      children: _jsx(_components.pre, {
        children: _jsx(_components.code, {
          className: "language-yaml",
          children: "version: \"0.2\"\n\nservices:\n  web:\n    image: nginx:latest\n    cpu: 1\n    memory: \"2Gi\"\n    replicas: 2\n\n    network:\n      ingress:\n        expose:\n          - port: 80\n            protocol: http\n"
        })
      })
    }), "\n", _jsxs(_components.h2, {
      id: "validate-your-configuration",
      children: ["Validate Your Configuration", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#validate-your-configuration",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.p, {
      children: "Check for errors:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core validate\n"
      })
    }), "\n", _jsx(_components.p, {
      children: "You should see:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "✓ Schema validation passed\n✓ Feature validation passed\n✓ No compliance issues\n"
      })
    }), "\n", _jsxs(_components.h2, {
      id: "preview-the-deployment",
      children: ["Preview the Deployment", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#preview-the-deployment",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.p, {
      children: "See what will be deployed:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core plan\n"
      })
    }), "\n", _jsx(_components.p, {
      children: "Output:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "⚙ Running core plan...\n\nProvider Selection:\n  Primary: GCP (cost-optimized)\n  Fallback: [Akash, DFC]\n\nResources:\n  ✓ Service: web (2 replicas)\n  ✓ Load Balancer: HTTP (port 80)\n  ✓ Auto-scaling: disabled\n\nEstimated Cost: $12/month ± 10%\n\n✓ Plan successful\n"
      })
    }), "\n", _jsxs(_components.h2, {
      id: "deploy",
      children: ["Deploy", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#deploy",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.p, {
      children: "Apply your configuration:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core apply\n"
      })
    }), "\n", _jsx(_components.p, {
      children: "Output:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "⚙ Deploying...\n  ✓ Creating service: web\n  ✓ Provisioning load balancer\n  ✓ Starting replicas (2/2)\n\n✅ Deployment successful\n\nService URL: http://web-a3d5.df.app\nStatus: https://console.digitalfrontier.so/deployments/df-20251203-00123\n"
      })
    }), "\n", _jsxs(_components.h2, {
      id: "check-status",
      children: ["Check Status", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#check-status",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.p, {
      children: "View your deployment:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core status\n"
      })
    }), "\n", _jsxs(_components.h2, {
      id: "update-your-service",
      children: ["Update Your Service", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#update-your-service",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.p, {
      children: ["Let's add HTTPS and autoscaling. Edit ", _jsx(_components.code, {
        children: "compose.yaml"
      }), ":"]
    }), "\n", _jsx(PreviewCode, {
      tier: "dev-preview",
      lines: "20",
      lang: "yaml",
      children: _jsx(_components.pre, {
        children: _jsx(_components.code, {
          className: "language-yaml",
          children: "version: \"0.2\"\n\nservices:\n  web:\n    image: nginx:latest\n    cpu: 1\n    memory: \"2Gi\"\n\n    # Add autoscaling\n    autoscaling:\n      enabled: true\n      min_replicas: 2\n      max_replicas: 10\n      target_cpu_percent: 70\n\n    network:\n      ingress:\n        expose:\n          - port: 443\n            protocol: https\n            tls:\n              auto: true  # Automatic TLS certificates\n"
        })
      })
    }), "\n", _jsx(_components.p, {
      children: "Apply the changes:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core apply\n"
      })
    }), "\n", _jsx(_components.p, {
      children: "Blazing Core will:"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Provision TLS certificates automatically"
      }), "\n", _jsx(_components.li, {
        children: "Update the load balancer to HTTPS"
      }), "\n", _jsx(_components.li, {
        children: "Enable autoscaling (2-10 replicas)"
      }), "\n"]
    }), "\n", _jsxs(_components.h2, {
      id: "add-a-database",
      children: ["Add a Database", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#add-a-database",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.p, {
      children: ["Let's add a PostgreSQL database. Update ", _jsx(_components.code, {
        children: "compose.yaml"
      }), ":"]
    }), "\n", _jsx(PreviewCode, {
      tier: "dev-preview",
      lines: "17",
      lang: "yaml",
      children: _jsx(_components.pre, {
        children: _jsx(_components.code, {
          className: "language-yaml",
          children: "version: \"0.2\"\n\nservices:\n  web:\n    image: nginx:latest\n    cpu: 1\n    memory: \"2Gi\"\n    autoscaling:\n      enabled: true\n      min_replicas: 2\n      max_replicas: 10\n      target_cpu_percent: 70\n    network:\n      ingress:\n        expose:\n          - port: 443\n            protocol: https\n            tls:\n              auto: true\n    # Reference database credentials\n    secrets:\n      - secret_ref: db-credentials\n        mode: env\n        keys:\n          host: DB_HOST\n          username: DB_USER\n          password: DB_PASSWORD\n\n  db:\n    image: postgres:15\n    cpu: 2\n    memory: \"4Gi\"\n    replicas: 1\n    storage:\n      - mount_path: /var/lib/postgresql/data\n        size: \"50Gi\"\n        persistent: true\n    network:\n      ingress:\n        expose:\n          - port: 5432\n            protocol: tcp\n            internal_only: true  # Not exposed to internet\n"
        })
      })
    }), "\n", _jsx(_components.p, {
      children: "Create the database secret:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core secrets create db-credentials \\\n  --type db-credentials \\\n  --data host=db.internal \\\n  --data username=appuser \\\n  --data password=your-secure-password\n"
      })
    }), "\n", _jsx(_components.p, {
      children: "Apply:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core apply\n"
      })
    }), "\n", _jsxs(_components.h2, {
      id: "clean-up",
      children: ["Clean Up", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#clean-up",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.p, {
      children: "Remove all resources:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-bash",
        children: "core destroy\n"
      })
    }), "\n", _jsx(_components.p, {
      children: "Confirm when prompted."
    }), "\n", _jsxs(_components.h2, {
      id: "next-steps",
      children: ["Next Steps", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#next-steps",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.h3, {
      id: "learn-core-concepts",
      children: ["Learn Core Concepts", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#learn-core-concepts",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/service-basics",
          children: "Services"
        }), " - Understanding service configuration"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/architecture",
          children: "Architecture"
        }), " - Core platform architecture"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/organizational-hierarchy",
          children: "Organizational Hierarchy"
        }), " - Teams and projects"]
      }), "\n"]
    }), "\n", _jsxs(_components.h3, {
      id: "advanced-features",
      children: ["Advanced Features", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#advanced-features",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/autoscaling",
          children: "Autoscaling"
        }), " - Scale based on metrics"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/overview",
          children: "Multi-Cloud"
        }), " - Deploy across clouds"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/deployment-lifecycle",
          children: "Deployment Lifecycle"
        }), " - Manage deployments"]
      }), "\n"]
    }), "\n", _jsxs(_components.h3, {
      id: "providers",
      children: ["Providers", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#providers",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/gcp-provider",
          children: "GCP Provider"
        }), " - Deploy to Google Cloud"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/dfc-provider",
          children: "DFC Provider"
        }), " - Digital Frontier Cloud"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs/akash-provider",
          children: "Akash Provider"
        }), " - Decentralized compute"]
      }), "\n"]
    }), "\n", _jsxs(_components.h2, {
      id: "common-commands",
      children: ["Common Commands", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#common-commands",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.p, {
      children: ["| Command | Description |\n|---------|-------------|\n| ", _jsx(_components.code, {
        children: "core init"
      }), " | Initialize a new project |\n| ", _jsx(_components.code, {
        children: "core validate"
      }), " | Validate configuration locally |\n| ", _jsx(_components.code, {
        children: "core plan"
      }), " | Preview deployment changes |\n| ", _jsx(_components.code, {
        children: "core apply"
      }), " | Deploy infrastructure |\n| ", _jsx(_components.code, {
        children: "core status"
      }), " | Check deployment status |\n| ", _jsx(_components.code, {
        children: "core logs"
      }), " | View service logs |\n| ", _jsx(_components.code, {
        children: "core destroy"
      }), " | Delete all resources |"]
    }), "\n", _jsxs(_components.h2, {
      id: "getting-help",
      children: ["Getting Help", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#getting-help",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "/docs",
          children: "Documentation"
        }), " - Complete reference"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "https://discord.gg/blazing",
          children: "Discord Community"
        }), " - Get support"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.a, {
          href: "mailto:admin@blazing.work",
          children: "Email Support"
        }), " - Contact us"]
      }), "\n"]
    }), "\n", _jsxs(_components.h2, {
      id: "example-projects",
      children: ["Example Projects", _jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#example-projects",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      })]
    }), "\n", _jsx(_components.p, {
      children: "Browse complete examples:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: "Simple Web App"
        }), " - Basic HTTP service"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: "API with Database"
        }), " - REST API + PostgreSQL"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: "ML Training"
        }), " - GPU workload with autoscaling"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: "Microservices"
        }), " - Multi-service application"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: "Multi-Cloud HA"
        }), " - High-availability deployment"]
      }), "\n"]
    }), "\n", _jsxs(_components.p, {
      children: ["Find examples at ", _jsx(_components.a, {
        href: "https://github.com/digitalfrontier/core-compose-examples",
        children: "github.com/digitalfrontier/core-compose-examples"
      })]
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};
function _missingMdxReference(id, component) {
  throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it.");
}
