cozystack/packages/apps/foundationdb

Managed FoundationDB Service

A managed FoundationDB service for Cozystack.

Overview

FoundationDB is a distributed database designed to handle large volumes of structured data across clusters of commodity servers. It organizes data as an ordered key-value store and employs ACID transactions for all operations.

This package provides a managed FoundationDB cluster deployment using the FoundationDB Kubernetes Operator.

Features

• High Availability: Multi-instance deployment with automatic failover
• ACID Transactions: Full ACID transaction support across the cluster
• Scalable: Easily scale storage and compute resources
• Backup Integration: Optional S3-compatible backup storage
• Monitoring: Built-in monitoring and alerting through WorkloadMonitor
• Flexible Configuration: Support for custom FoundationDB parameters

Configuration

Basic Configuration

# FoundationDB major.minor version (v7.4, v7.3)
version: v7.3

# Cluster process configuration
cluster:
  processCounts:
    storage: 3           # Number of storage processes (determines cluster size)
    stateless: -1        # Automatically calculated
    cluster_controller: 1
  faultDomain:
    key: "kubernetes.io/hostname"
    valueFrom: "spec.nodeName"

Storage

storage:
  size: "16Gi"           # Storage size per instance
  storageClass: ""       # Storage class (optional)

Resources

# Use preset sizing
resourcesPreset: "medium"  # small, medium, large, xlarge, 2xlarge

# Or custom resource configuration
resources:
  cpu: "2000m"
  memory: "4Gi"

Backups

The recommended backup flow uses the Cozystack backups framework: a cluster-scoped BackupClass binds apps.cozystack.io/FoundationDB to a strategy.backups.cozystack.io/FoundationDB strategy, and tenants drive runs via BackupJob / RestoreJob. See examples/backups/foundationdb/ for an end-to-end walkthrough (admin setup, backup, in-place restore, to-copy restore).

The legacy in-chart backup.* values (backup.enabled, backup.s3, backup.retentionPolicy) are DEPRECATED but still render the original FoundationDBBackup CR unchanged when backup.enabled=true, for backward compatibility. New deployments should leave backup.enabled=false (the default) and use the BackupClass flow above. Mixing the two on the same cluster is unsupported — the FoundationDB operator only permits one running backup directory per cluster, and the backup driver fails fast with Ready=False/ConflictingInChartBackup when it sees a chart-rendered Running backup against the same target.

Advanced Configuration

# Custom FoundationDB parameters
customParameters:
  - "knob_disable_posix_kernel_aio=1"

# Image type (split is the default; matches existing clusters' effective value)
imageType: "split"

# Enable automatic pod replacements
automaticReplacements: true

# Security context configuration
securityContext:
  runAsUser: 4059
  runAsGroup: 4059

Prerequisites

• FoundationDB Operator must be installed in the cluster
• Sufficient storage and compute resources
• For backups: S3-compatible storage credentials

Deployment

1. Install the FoundationDB operator (system package)
2. Deploy this application package with your desired configuration
3. The cluster will be automatically provisioned and configured

Monitoring

This package includes WorkloadMonitor integration for cluster health monitoring and resource tracking. Monitoring can be disabled by setting:

monitoring:
  enabled: false

Security

• All containers run with restricted security contexts
• No privilege escalation allowed
• Read-only root filesystem where possible
• Custom security context configurations supported

Fault Tolerance

FoundationDB is designed for high availability:

• Automatic failure detection and recovery
• Data replication across instances
• Configurable fault domains for rack/zone awareness
• Transaction log redundancy

The included WorkloadMonitor is automatically configured based on the cluster.redundancyMode value. It sets the minReplicas property on the WorkloadMonitor resource to ensure the cluster's health status accurately reflects its fault tolerance level. The number of tolerated failures is as follows:

• single: 0 failures
• double: 1 failure
• triple and datacenter-aware modes: 2 failures

For example, with the default configuration (redundancyMode: double and 3 storage pods), minReplicas will be set to 2.

Performance Considerations

• Use SSD storage for better performance
• Consider dedicating nodes for storage processes
• Monitor cluster metrics for optimization opportunities
• Scale storage and stateless processes based on workload

Support

For issues related to FoundationDB itself, refer to the FoundationDB documentation.

For Cozystack-specific issues, consult the Cozystack documentation or support channels.

storageClass is annotated as immutable in the chart schema — see docs/storage-immutability.md for the contract and which consumers enforce it.

Parameters

Common parameters

Name	Description	Type	Value
version	FoundationDB major.minor version to deploy	string	v7.3
cluster	Cluster configuration.	object	{}
cluster.processCounts	Process counts for different roles.	object	{}
cluster.processCounts.stateless	Number of stateless processes (-1 for automatic).	int	-1
cluster.processCounts.storage	Number of storage processes (determines cluster size).	int	3
cluster.processCounts.cluster_controller	Number of cluster controller processes.	int	1
cluster.redundancyMode	Database redundancy mode (single, double, triple, three_datacenter, three_datacenter_fallback).	string	double
cluster.storageEngine	Storage engine (ssd-2, ssd-redwood-v1, ssd-rocksdb-v1, memory).	string	ssd-2
cluster.faultDomain	Fault domain configuration.	object	{}
cluster.faultDomain.key	Fault domain key.	string	kubernetes.io/hostname
cluster.faultDomain.valueFrom	Fault domain value source.	string	spec.nodeName
storage	Storage configuration.	object	{}
storage.size	Size of persistent volumes for each instance.	quantity	16Gi
storage.storageClass	Storage class (if not set, uses cluster default).	string	""
resources	Explicit CPU and memory configuration for each FoundationDB instance. When omitted, the preset defined in resourcesPreset is applied.	object	{}
resources.cpu	CPU available to each instance.	quantity	""
resources.memory	Memory (RAM) available to each instance.	quantity	""
resourcesPreset	Default sizing preset used when resources is omitted.	string	c1.small
backup	DEPRECATED Backup configuration (use the Cozystack backups framework: BackupClass + FoundationDB strategy).	object	{}
backup.enabled	DEPRECATED Enable in-chart backups (superseded by BackupClass + FoundationDB strategy).	bool	false
backup.s3	DEPRECATED S3 configuration for backups.	object	{}
backup.s3.bucket	DEPRECATED S3 bucket name.	string	""
backup.s3.endpoint	DEPRECATED S3 endpoint URL.	string	""
backup.s3.region	DEPRECATED S3 region.	string	us-east-1
backup.s3.credentials	DEPRECATED S3 credentials.	object	{}
backup.s3.credentials.accessKeyId	DEPRECATED S3 access key ID.	string	""
backup.s3.credentials.secretAccessKey	DEPRECATED S3 secret access key.	string	""
backup.retentionPolicy	DEPRECATED Retention policy for backups.	string	7d
monitoring	Monitoring configuration.	object	{}
monitoring.enabled	Enable WorkloadMonitor integration.	bool	true

FoundationDB configuration

Name	Description	Type	Value
customParameters	Custom parameters to pass to FoundationDB.	[]string	[]
imageType	Container image deployment type.	string	split
securityContext	Security context for containers.	object	{}
securityContext.runAsUser	User ID to run the container.	int	4059
securityContext.runAsGroup	Group ID to run the container.	int	4059
automaticReplacements	Enable automatic pod replacements.	bool	true