New in Rulebricks: Reactive Rule Flows. More →
Private Deployment
Configuration Reference

Configuration Reference

This document provides a complete reference for the rulebricks.yaml configuration file schema.

Configuration File Structure

The configuration file is a YAML file that defines all aspects of your Rulebricks deployment. Here's the complete schema:

version: "1.0"                    # Configuration version
 
project:                         # Project settings
  name: string                   # Required: Kubernetes-compatible name
  domain: string                 # Required: Application domain
  email: string                  # Required: Admin email
  license: string                # Required: License key or env:VAR
  version: string                # Optional: Project version
  namespace: string              # Optional: Override namespace
 
cloud:                           # Cloud provider settings
  provider: string               # Required: aws, azure, or gcp
  region: string                 # Required: Cloud region
  aws:                           # Optional: AWS-specific
  azure:                         # Optional: Azure-specific
  gcp:                           # Optional: GCP-specific
 
kubernetes:                      # Kubernetes cluster settings
  cluster_name: string           # Optional: Cluster name
  node_count: int                # Required: Initial node count
  enable_autoscale: bool         # Optional: Enable autoscaling
  min_nodes: int                 # Optional: Min nodes (if autoscaling)
  max_nodes: int                 # Optional: Max nodes (if autoscaling)
 
database:                        # Database configuration
  type: string                   # Required: self-hosted, managed, external
  provider: string               # Optional: Database provider
  supabase:                      # Optional: Supabase settings
  pooling:                       # Optional: Connection pooling
 
email:                           # Email configuration
  provider: string               # Optional: smtp, sendgrid, etc.
  from: string                   # Required: From email address
  from_name: string              # Optional: From display name
  smtp:                          # Optional: SMTP settings
  templates:                     # Optional: Custom email templates
 
security:                        # Security settings
  tls:                           # Optional: TLS configuration
  secrets:                       # Optional: Secrets management
  network:                       # Optional: Network security
 
monitoring:                      # Monitoring configuration
  enabled: bool                  # Required: Enable monitoring
  mode: string                   # Optional: local or remote
  local:                         # Optional: Local monitoring settings
  remote:                        # Optional: Remote monitoring settings
  metrics:                       # Optional: Metrics configuration
  logs:                          # Optional: Logs configuration
 
logging:                         # Logging configuration
  enabled: bool                  # Required: Enable logging
  vector:                        # Optional: Vector settings
 
performance:                     # Performance tuning
  volume_level: string           # Optional: small, medium, large
  hps_replicas: int              # Optional: HPS replicas
  hps_worker_replicas: int       # Optional: Worker replicas
  hps_worker_max_replicas: int  # Optional: Max worker replicas
  kafka_partitions: int          # Optional: Kafka partitions
  # ... more performance settings
 
ai:                              # AI integration
  enabled: bool                  # Required: Enable AI features
  openai_api_key_from: string   # Optional: OpenAI API key source
 
advanced:                        # Advanced settings
  terraform:                     # Optional: Terraform backend
  backup:                        # Optional: Backup configuration
  docker_registry:               # Optional: Custom Docker registry
  custom_values:                 # Optional: Custom Helm values

Detailed Field Reference

version

Configuration file version. Currently "1.0".

version: "1.0"

project

Project metadata and naming.

FieldTypeRequiredDescription
namestringYesKubernetes-compatible name (lowercase, alphanumeric, hyphens)
domainstringYesPrimary application domain
emailstringYesAdmin email for notifications
licensestringYesLicense key or env:VAR_NAME
versionstringNoProject version string
namespacestringNoOverride default namespace naming

Example:

project:
  name: my-rulebricks-app
  domain: app.example.com
  email: admin@example.com
  license: env:RULEBRICKS_LICENSE_KEY
  version: "1.0.0"

cloud

Cloud provider configuration.

FieldTypeRequiredDescription
providerstringYesaws, azure, or gcp
regionstringYesCloud provider region
awsobjectNoAWS-specific settings (see below)
azureobjectNoAzure-specific settings (see below)
gcpobjectNoGCP-specific settings (see below)

AWS Configuration (cloud.aws)

FieldTypeRequiredDescription
account_idstringNoAWS account ID (auto-detected if not set)
vpc_cidrstringNoVPC CIDR block (default: 10.0.0.0/16)
instance_typestringNoEC2 instance type (default: c8g.large)

Example:

cloud:
  provider: aws
  region: us-east-1
  aws:
    instance_type: c8g.large
    vpc_cidr: "10.0.0.0/16"

Azure Configuration (cloud.azure)

FieldTypeRequiredDescription
subscription_idstringNoAzure subscription ID
resource_groupstringNoResource group name
vm_sizestringNoVM size (default: Standard_D4ps_v5)

Example:

cloud:
  provider: azure
  region: eastus
  azure:
    subscription_id: "xxxxx-xxxxx-xxxxx"
    resource_group: "my-rg"
    vm_size: "Standard_D4ps_v5"

GCP Configuration (cloud.gcp)

FieldTypeRequiredDescription
project_idstringYesGCP project ID
zonestringNoGCP zone (auto-derived from region)
machine_typestringNoMachine type (default: t2a-standard-4)

Example:

cloud:
  provider: gcp
  region: us-central1
  gcp:
    project_id: "my-gcp-project"
    machine_type: "t2a-standard-4"

kubernetes

Kubernetes cluster configuration.

FieldTypeRequiredDescription
cluster_namestringNoCluster name (auto-generated if not set)
node_countintYesInitial number of nodes (minimum: 1)
enable_autoscaleboolNoEnable cluster autoscaling
min_nodesintNoMinimum nodes (required if autoscaling)
max_nodesintNoMaximum nodes (required if autoscaling)

Example:

kubernetes:
  cluster_name: my-rulebricks-cluster
  node_count: 3
  enable_autoscale: true
  min_nodes: 3
  max_nodes: 10

database

Database deployment configuration.

FieldTypeRequiredDescription
typestringYesself-hosted, managed, or external
providerstringNoDatabase provider (for managed)
supabaseobjectNoSupabase settings (see below)
poolingobjectNoConnection pooling (see below)

Supabase Configuration (database.supabase)

FieldTypeRequiredDescription
project_namestringNoSupabase project name
regionstringNoSupabase region
org_idstringNoOrganization ID

Example:

database:
  type: managed
  supabase:
    project_name: my-project
    region: us-east-1

Connection Pooling (database.pooling)

FieldTypeRequiredDescription
enabledboolNoEnable connection pooling
min_sizeintNoMinimum pool size
max_sizeintNoMaximum pool size

email

Email provider configuration.

FieldTypeRequiredDescription
providerstringNoProvider name (smtp, sendgrid, etc.)
fromstringYesFrom email address
from_namestringNoFrom display name
smtpobjectNoSMTP settings (see below)
templatesobjectNoCustom email templates (see below)

SMTP Configuration (email.smtp)

FieldTypeRequiredDescription
hoststringYesSMTP hostname
portintYesSMTP port
usernamestringYesSMTP username
password_fromstringYesPassword source (e.g., env:VAR)
encryptionstringNotls, ssl, or none
admin_emailstringNoAdmin email for notifications

Example:

email:
  provider: smtp
  from: noreply@example.com
  from_name: "Rulebricks"
  smtp:
    host: smtp.example.com
    port: 587
    username: smtp-user
    password_from: env:SMTP_PASSWORD
    encryption: tls

security

Security and network configuration.

TLS Configuration (security.tls)

FieldTypeRequiredDescription
enabledboolNoEnable TLS/SSL
providerstringNocert-manager or custom
custom_certstringNoPath to custom certificate
custom_keystringNoPath to custom key
acme_emailstringNoEmail for Let's Encrypt
domainsarrayNoAdditional domains for certificates

Example:

security:
  tls:
    enabled: true
    provider: cert-manager
    acme_email: admin@example.com
    domains:
      - api.example.com
      - admin.example.com

Network Security (security.network)

FieldTypeRequiredDescription
allowed_ipsarrayNoIP whitelist (empty = allow all)
rate_limitingboolNoEnable rate limiting

monitoring

Monitoring stack configuration.

FieldTypeRequiredDescription
enabledboolYesEnable monitoring
modestringNolocal or remote
localobjectNoLocal monitoring settings
remoteobjectNoRemote monitoring settings
metricsobjectNoMetrics configuration (not fully implemented - see note below)
logsobjectNoLogs configuration (not fully implemented)

Local Monitoring (monitoring.local)

FieldTypeRequiredDescription
prometheus_enabledboolNoEnable Prometheus
grafana_enabledboolNoEnable Grafana
retentionstringNoRetention period (e.g., 30d)
storage_sizestringNoStorage size (e.g., 50Gi)

Remote Monitoring (monitoring.remote)

FieldTypeRequiredDescription
providerstringYesprometheus, grafana-cloud, newrelic, custom
prometheus_writeobjectNoPrometheus remote write config
newrelicobjectNoNew Relic configuration

Example (Grafana Cloud):

monitoring:
  enabled: true
  mode: remote
  remote:
    provider: grafana-cloud
    prometheus_write:
      url: https://prometheus-us-central1.grafana.net/api/prom/push
      username: "123456"
      password_from: env:MONITORING_PASSWORD

Metrics Configuration (monitoring.metrics)

💡

This configuration section exists in the schema but is not fully implemented. Use monitoring.local.retention for local mode retention instead.

FieldTypeRequiredDescription
retentionstringNoMetrics retention period (not implemented - use monitoring.local.retention)
intervalstringNoScrape interval (not implemented - Prometheus uses defaults)

Logs Configuration (monitoring.logs)

💡

This configuration section exists in the schema but is not currently implemented.

FieldTypeRequiredDescription
levelstringNoLog level (not implemented)
retentionstringNoLog retention period (not implemented)

logging

Centralized logging configuration.

FieldTypeRequiredDescription
enabledboolYesEnable logging
vectorobjectNoVector configuration

Vector Sink (logging.vector.sink)

FieldTypeRequiredDescription
typestringYesSink type (see below)
endpointstringNoEndpoint URL
api_keystringNoAPI key or env:VAR
configobjectNoSink-specific configuration

Sink Types:

  • console - Output to stdout
  • elasticsearch - Elasticsearch endpoint
  • datadog_logs - Datadog logs
  • splunk_hec - Splunk HEC
  • aws_s3 - AWS S3 bucket
  • gcp_cloud_storage - Google Cloud Storage
  • azure_blob - Azure Blob Storage
  • loki - Loki endpoint
  • http - Generic HTTP endpoint
  • new_relic_logs - New Relic logs

See Vector Logging Setup for detailed examples.

performance

Performance tuning and resource configuration.

FieldTypeRequiredDescription
volume_levelstringNosmall, medium, or large
hps_replicasintNoInitial HPS replicas
hps_worker_replicasintNoInitial worker replicas
hps_worker_max_replicasintNoMaximum worker replicas
kafka_partitionsintNoKafka partitions
kafka_lag_thresholdintNoLag threshold for autoscaling
kafka_retention_hoursintNoMessage retention (hours)
kafka_storage_sizestringNoKafka storage size
kafka_replication_factorintNoReplication factor
hps_resourcesobjectNoHPS resource limits
worker_resourcesobjectNoWorker resource limits

Example:

performance:
  volume_level: medium
  hps_replicas: 2
  hps_worker_max_replicas: 20
  kafka_partitions: 10
  hps_resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "2000m"
      memory: "4Gi"

ai

AI integration settings.

FieldTypeRequiredDescription
enabledboolYesEnable AI features
openai_api_key_fromstringNoOpenAI API key source

advanced

Advanced configuration options.

Terraform Backend (advanced.terraform)

FieldTypeRequiredDescription
backendstringNoBackend type: local, s3, gcs, azurerm
backend_configobjectNoBackend-specific configuration
variablesobjectNoCustom Terraform variables

Backup Configuration (advanced.backup)

💡

Backup functionality is planned but not yet implemented. This configuration exists in the schema for future use but is not currently processed during deployment.

FieldTypeRequiredDescription
enabledboolNoEnable automated backups (not yet implemented)
schedulestringNoCron schedule (not yet implemented)
retentionstringNoRetention period (not yet implemented)
providerstringNoBackup provider: s3, gcs, azure (not yet implemented)
provider_configobjectNoProvider-specific config (not yet implemented)

For now, you'll need to set up database backups manually. See Upgrades & Maintenance for manual backup options.

Docker Registry (advanced.docker_registry)

FieldTypeRequiredDescription
urlstringNoRegistry URL
app_imagestringNoCustom app image
hps_imagestringNoCustom HPS image

Environment Variables

Secrets can be sourced from environment variables using the env:VAR_NAME syntax:

project:
  license: env:RULEBRICKS_LICENSE_KEY
 
email:
  smtp:
    password_from: env:SMTP_PASSWORD
 
monitoring:
  remote:
    prometheus_write:
      password_from: env:MONITORING_PASSWORD

Configuration Validation

The CLI validates your configuration before deployment. Common validation errors:

  • Missing required fields: Ensure all required fields are present
  • Invalid project name: Must be Kubernetes-compatible
  • Invalid email format: Must be a valid email address
  • Invalid cloud provider: Must be aws, azure, or gcp
  • Invalid database type: Must be self-hosted, managed, or external
  • Invalid node count: Must be at least 1

Default Values

Many fields have sensible defaults. See the example configuration file for all default values.

Best Practices

  1. Use environment variables for secrets - Never commit secrets to version control
  2. Start with defaults - Only override what you need to change
  3. Document customizations - Add comments explaining non-standard choices
  4. Version control your config - Commit rulebricks.yaml (without secrets) to version control
  5. Test changes - Validate configuration before deploying

See Also

Quick StartInitial Setup