Files
cozystack/packages/apps/foundationdb/README.md
T
myasnikovdaniil 4087218a02 docs: move the repo-only guides onto the website (#5034)
## What this PR does

Seven guides under `docs/` were operator facing and written alongside
the code, and left in the source tree where no user looks. They are on
the website now, so this deletes them here and repoints every reference.

```
docs/operations/backup-classes.md                  -> operations/services/backup-classes
docs/operations/resource-presets.md                -> guides/resource-management
docs/storage-immutability.md                       -> operations/storage-class-immutability
docs/operations/system-memory-limits.md            -> operations/configuration/system-memory-limits
docs/gateway-classes.md                            -> networking/gateway-classes
docs/observability/distributed-tracing.md          -> operations/services/monitoring/distributed-tracing
docs/operations/seaweedfs-capacity-for-backups.md  -> operations/services/object-storage/capacity-for-backups
```

`docs/release.md`, `docs/deprecating-applications.md` and the two
SeaweedFS runbooks in `docs/operations/` stay. A workflow, `AGENTS.md`,
a migration and a bats suite read them by path, which is the test from
#3777.

References point at `https://cozystack.io/docs/v1/...`. The site
rewrites that short prefix to the latest version in `layouts/404.html`,
so the links follow releases and pin none. Backup Classes, resource
management and `storageClass` immutability exist in the latest version
already. The other four pages are only in `next/` until 1.7.0 is
promoted, and their links start to resolve then. The generated mongodb
files come from `values.yaml` through `make generate` with
cozyvalues-gen v1.7.0, the version pinned in
`.github/workflows/pre-commit.yml`.

Tests: helm unit tests for mongodb (151), postgres (209), vm-disk (114)
and kubernetes-nodes (223), go tests for backupcontroller, presets and
the operator, rd-presets-check, the migration-50 bats suite.

### Downstream repositories

- [x] [cozystack/website](https://github.com/cozystack/website) -
follow-up: cozystack/website#763

Walked the rest of the trigger map against the diff. No provider
follow-up: the mongodb `values.schema.json` diff is one `description`
string, with no field added, removed or renamed, no enum, no default,
and no `kind`, `plural` or `release.prefix` change.
`packages/core/platform/values.yaml` changed in comments only and no
key, so the hand written platform-package table on the site is
unaffected.

Please merge after cozystack/website#763, the links in the code only
resolve once those pages deploy.

### Release note

```release-note
docs: seven guides move from the docs/ directory of this repository to cozystack.io (Backup Classes, resource presets, storageClass immutability, system component memory limits, GatewayClass selection, distributed tracing, SeaweedFS capacity for backups), and in-repo references point there.
```
2026-11-03 23:09:46 +05:00

205 lines
13 KiB
Markdown

# 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
```yaml
# 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
```yaml
storage:
size: "16Gi" # Storage size per instance
storageClass: "" # Storage class (optional)
```
### Resources
```yaml
# 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/`](../../../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
```yaml
# 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:
```yaml
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](https://apple.github.io/foundationdb/).
For Cozystack-specific issues, consult the Cozystack documentation or support channels.
> `storageClass` is annotated as immutable in the chart schema — see [storageClass immutability](https://cozystack.io/docs/v1/operations/storage-class-immutability/) 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` |