CockroachDB Cluster

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cockroachlabs.com/schemas/cockroachdb/cluster.json",
  "title": "CockroachDB Cluster",
  "description": "Schema representing a CockroachDB Cloud cluster, which is an instance of CockroachDB running in one or more cloud regions on Serverless or Dedicated infrastructure.",
  "type": "object",
  "required": ["id", "name", "cloud_provider", "state", "operation_status", "plan", "regions", "cockroach_version", "creator_id"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier of the cluster assigned by CockroachDB Cloud."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name of the cluster.",
      "maxLength": 40
    },
    "cloud_provider": {
      "type": "string",
      "description": "Cloud infrastructure provider hosting the cluster.",
      "enum": ["GCP", "AWS", "AZURE"]
    },
    "cockroach_version": {
      "type": "string",
      "description": "Version string of CockroachDB running on the cluster (e.g. v23.1.0).",
      "pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+"
    },
    "plan": {
      "type": "string",
      "description": "Service tier of the cluster, either Serverless or Dedicated.",
      "enum": ["DEDICATED", "SERVERLESS"]
    },
    "state": {
      "type": "string",
      "description": "Overall lifecycle state of the cluster.",
      "enum": ["CREATING", "CREATED", "CREATION_FAILED", "DELETED", "LOCKED"]
    },
    "operation_status": {
      "type": "string",
      "description": "Current operational status reflecting any in-progress or failed operations.",
      "enum": ["CLUSTER_STATUS_UNSPECIFIED", "CRDB_MAJOR_UPGRADE_RUNNING", "CRDB_MAJOR_ROLLBACK_RUNNING", "CRDB_PATCH_RUNNING", "CRDB_SCALE_RUNNING", "TENANT_RESTORE_RUNNING", "CRDB_MAJOR_UPGRADE_PENDING", "CRDB_MAJOR_ROLLBACK_PENDING", "CRDB_PATCH_PENDING", "CRDB_SCALE_PENDING", "NONE"]
    },
    "regions": {
      "type": "array",
      "description": "Cloud provider regions where the cluster is deployed. Multi-region clusters have multiple entries.",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/Region"
      }
    },
    "config": {
      "$ref": "#/$defs/ClusterConfig",
      "description": "Configuration settings for the cluster, containing either serverless or dedicated configuration."
    },
    "creator_id": {
      "type": "string",
      "description": "Identifier of the user who created the cluster."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 timestamp when the cluster was created."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 timestamp of the most recent modification to the cluster."
    },
    "deleted_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 timestamp when the cluster was deleted. Only present for deleted clusters."
    },
    "sql_dns": {
      "type": "string",
      "description": "DNS hostname used for SQL connections to the cluster."
    },
    "upgrade_status": {
      "type": "string",
      "description": "Status of any in-progress version upgrade operation.",
      "enum": ["UPGRADE_AVAILABLE", "UPGRADING", "UPGRADE_QUEUED", "ROLLBACK_RUNNING", "FINALIZATION_PENDING", "FINALIZATION_FAILED", "MAJOR_UPGRADE_RUNNING"]
    },
    "account_id": {
      "type": "string",
      "description": "Cloud provider account ID for the cluster, used for trust relationship configuration."
    },
    "parent_id": {
      "type": "string",
      "description": "Folder ID of the folder containing this cluster, if any."
    },
    "labels": {
      "type": "object",
      "description": "User-defined key-value labels attached to the cluster for organization and filtering.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "delete_protection": {
      "type": "string",
      "description": "Whether delete protection is enabled, preventing accidental cluster deletion.",
      "enum": ["DELETE_PROTECTION_ENABLED", "DELETE_PROTECTION_DISABLED"]
    },
    "egress_traffic_policy": {
      "type": "string",
      "description": "Policy governing outbound network traffic from the cluster.",
      "enum": ["EGRESS_TRAFFIC_POLICY_UNSPECIFIED", "DEFAULT_ALLOW", "DEFAULT_DENY"]
    },
    "network_visibility": {
      "type": "string",
      "description": "Network accessibility configuration controlling whether the cluster is publicly accessible.",
      "enum": ["PRIVATE", "PUBLIC"]
    },
    "azure_cluster_identity_client_id": {
      "type": "string",
      "description": "Client ID of the Azure cluster identity, present for Azure deployments that support CMEK."
    },
    "cidr_range": {
      "type": "string",
      "description": "IPv4 CIDR range reserved for the cluster. Only set on GCP Advanced tier clusters.",
      "pattern": "^([0-9]{1,3}\\.){3}[0-9]{1,3}/[0-9]{1,2}$"
    },
    "customer_cloud_account": {
      "$ref": "#/$defs/CustomerCloudAccount",
      "description": "Customer cloud account details for BYOC (Bring Your Own Cloud) deployments."
    }
  },
  "$defs": {
    "Region": {
      "type": "object",
      "description": "A geographic region where the cluster or its nodes are deployed.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Cloud provider region identifier (e.g. us-east-1, us-central1)."
        },
        "sql_dns": {
          "type": "string",
          "description": "DNS hostname for SQL connections routed specifically to this region."
        },
        "node_count": {
          "type": "integer",
          "description": "Number of CockroachDB nodes deployed in this region.",
          "minimum": 1
        },
        "primary": {
          "type": "boolean",
          "description": "Whether this is the primary region for a multi-region cluster."
        }
      }
    },
    "ClusterConfig": {
      "type": "object",
      "description": "Configuration container for a cluster, holding either serverless or dedicated settings.",
      "properties": {
        "serverless": {
          "$ref": "#/$defs/ServerlessClusterConfig",
          "description": "Configuration specific to Serverless clusters. Present when plan is SERVERLESS."
        },
        "dedicated": {
          "$ref": "#/$defs/DedicatedClusterConfig",
          "description": "Configuration specific to Dedicated clusters. Present when plan is DEDICATED."
        }
      }
    },
    "ServerlessClusterConfig": {
      "type": "object",
      "description": "Configuration specific to a CockroachDB Serverless cluster.",
      "properties": {
        "spend_limit": {
          "type": "integer",
          "description": "Monthly spend limit in US cents. Set to 0 for unlimited spend.",
          "minimum": 0
        },
        "routing_id": {
          "type": "string",
          "description": "Unique routing identifier used to route SQL connections to the correct serverless cluster."
        },
        "usage_limits": {
          "$ref": "#/$defs/UsageLimits",
          "description": "Request unit and storage limits for the serverless cluster."
        }
      }
    },
    "UsageLimits": {
      "type": "object",
      "description": "Usage-based limits for a Serverless cluster.",
      "properties": {
        "request_unit_limit": {
          "type": "integer",
          "format": "int64",
          "description": "Maximum number of request units per month. 0 means no limit."
        },
        "storage_mib_limit": {
          "type": "integer",
          "format": "int64",
          "description": "Maximum storage in mebibytes. 0 means no limit."
        }
      }
    },
    "DedicatedClusterConfig": {
      "type": "object",
      "description": "Configuration specific to a CockroachDB Dedicated cluster.",
      "properties": {
        "machine_type": {
          "type": "string",
          "description": "Machine type used for cluster nodes (e.g. m5.xlarge on AWS)."
        },
        "num_virtual_cpus": {
          "type": "integer",
          "description": "Number of virtual CPUs allocated per node.",
          "minimum": 2
        },
        "storage_gib": {
          "type": "integer",
          "description": "Storage capacity per node in gibibytes.",
          "minimum": 15
        },
        "memory_gib": {
          "type": "number",
          "description": "Memory per node in gibibytes.",
          "exclusiveMinimum": 0
        },
        "disk_iops": {
          "type": "integer",
          "description": "Disk input/output operations per second allocated per node.",
          "minimum": 0
        }
      }
    },
    "CustomerCloudAccount": {
      "type": "object",
      "description": "Customer cloud account details for Bring Your Own Cloud (BYOC) cluster deployments.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Cloud provider account or project ID."
        },
        "provider": {
          "type": "string",
          "description": "Cloud provider for the customer account.",
          "enum": ["GCP", "AWS", "AZURE"]
        }
      }
    },
    "AllowlistEntry": {
      "type": "object",
      "description": "An IP allowlist entry defining a CIDR range authorized to connect to the cluster.",
      "required": ["cidr_ip", "cidr_mask"],
      "properties": {
        "cidr_ip": {
          "type": "string",
          "description": "IPv4 base address of the CIDR range.",
          "pattern": "^([0-9]{1,3}\\.){3}[0-9]{1,3}$"
        },
        "cidr_mask": {
          "type": "integer",
          "description": "Prefix length of the CIDR range (e.g. 24 for /24).",
          "minimum": 0,
          "maximum": 32
        },
        "name": {
          "type": "string",
          "description": "Human-readable label for this allowlist entry (e.g. office-network)."
        },
        "ui": {
          "type": "boolean",
          "description": "Whether this entry grants access to the DB Console web interface."
        },
        "sql": {
          "type": "boolean",
          "description": "Whether this entry grants SQL connection access."
        }
      }
    },
    "MaintenanceWindow": {
      "type": "object",
      "description": "Defines the preferred time window for automatic maintenance and version upgrade operations.",
      "properties": {
        "day_of_week": {
          "type": "integer",
          "description": "Day of the week for the maintenance window. 0=Sunday through 6=Saturday.",
          "minimum": 0,
          "maximum": 6
        },
        "start_hour": {
          "type": "integer",
          "description": "Hour of day in UTC when the maintenance window begins (0-23).",
          "minimum": 0,
          "maximum": 23
        }
      }
    },
    "CMEKRegionSpec": {
      "type": "object",
      "description": "Customer-managed encryption key specification for a specific cloud region.",
      "required": ["region", "key"],
      "properties": {
        "region": {
          "type": "string",
          "description": "Cloud provider region this key specification applies to."
        },
        "key": {
          "$ref": "#/$defs/CMEKKeySpec",
          "description": "Encryption key specification for this region."
        }
      }
    },
    "CMEKKeySpec": {
      "type": "object",
      "description": "Specification for a customer-managed encryption key.",
      "required": ["type", "uri"],
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of encryption key. AWS_KMS for AWS, GCP_CLOUD_KMS for GCP.",
          "enum": ["AWS_KMS", "GCP_CLOUD_KMS"]
        },
        "uri": {
          "type": "string",
          "description": "Full URI of the customer-managed key in the cloud provider's KMS."
        },
        "auth_principal": {
          "type": "string",
          "description": "IAM role ARN (AWS) or service account email (GCP) used to access the key."
        }
      }
    },
    "LogExportGroup": {
      "type": "object",
      "description": "A log channel group configuration for selective log export.",
      "required": ["channels"],
      "properties": {
        "log_name": {
          "type": "string",
          "description": "Name of the log group or stream in the destination service."
        },
        "channels": {
          "type": "array",
          "description": "List of CockroachDB log channel names to include in this group.",
          "items": {
            "type": "string"
          }
        },
        "min_level": {
          "type": "string",
          "description": "Minimum severity level of log entries to export.",
          "enum": ["INFO", "WARNING", "ERROR", "FATAL"]
        },
        "redact": {
          "type": "boolean",
          "description": "Whether to redact sensitive information from log entries before export."
        }
      }
    },
    "BackupConfiguration": {
      "type": "object",
      "description": "Backup retention and frequency settings for a CockroachDB cluster.",
      "properties": {
        "cluster_id": {
          "type": "string",
          "description": "ID of the cluster this backup configuration applies to."
        },
        "frequency_minutes": {
          "type": "integer",
          "description": "How often automated backups are taken, in minutes.",
          "minimum": 1
        },
        "retention_days": {
          "type": "integer",
          "description": "Number of days automated backups are retained before deletion.",
          "minimum": 1,
          "maximum": 365
        }
      }
    }
  }
}