Managed Applications: Guides and Reference on Cozystack

Application Backup and Recovery

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers backing up and restoring Cozystack-managed databases — Postgres, MariaDB, ClickHouse, and Etcd — as a tenant user: running one-off and scheduled backups, checking status, and restoring from a backup either in place or into a separate target instance.

Storage and the BackupClass are platform-provisioned. Cozystack ships a single cluster-scoped BackupClass named cozy-default that covers Postgres, MariaDB, ClickHouse, Etcd, VMInstance, and VMDisk via a per-Kind strategies[] array. You reference it by name from BackupJob / Plan / RestoreJob — there is no per-application BackupClass, and you do not create or supply S3 credentials, endpoints, or paths. The platform projects a credentials Secret (cozy-backups-creds) into your tenant namespace automatically right before each BackupJob or RestoreJob runs.

Adding External Applications to Cozystack Catalog

Mon, 01 Jan 0001 00:00:00 +0000

Cozystack administrators can add applications from external sources in addition to the standard application catalog. These applications appear in the same catalog and behave like regular managed applications for platform users.

This guide explains the structure of an external application package and how to add it to a Cozystack cluster.

For a complete working example, see github.com/cozystack/external-apps-example.

Note: This page describes the Git-and-HelmRelease bootstrap. A repository can also be published as an OCI artifact and connected with one command, using the PackageSource model described in Application Marketplace. The two coexist on a cluster; the pipeline on this page is untouched.

Just like standard Cozystack applications, this external application package uses Helm and FluxCD. To learn more about developing application packages, read the Cozystack Developer Guide.

S3 Bucket Reference

Mon, 01 Jan 0001 00:00:00 +0000

Parameters

Name	Description	Type	Value
`locking`	Provisions bucket from the `-lock` BucketClass (with object lock enabled).	`bool`	`false`
`storagePool`	Selects a specific BucketClass by storage pool name.	`string`	`""`
`users`	Users configuration map.	`map[string]object`	`{}`
`users[name].readonly`	Whether the user has read-only access.	`bool`	`false`

Managed ClickHouse Service

Mon, 01 Jan 0001 00:00:00 +0000

ClickHouse is an open source high-performance and column-oriented SQL database management system (DBMS). It is used for online analytical processing (OLAP).

Backup orchestration

Two backup paths coexist on the chart; pick one per release.

Recommended: BackupClass + Plan via the Altinity strategy

The cluster-scoped Altinity strategy (strategy.backups.cozystack.io/v1alpha1) wraps Altinity’s clickhouse-backup in a one-shot batch/v1.Job per BackupJob / RestoreJob. It is engine-aware (FREEZE + upload), supports both in-place and targetApplicationRef (to-copy) restore, and does not require any in-chart CronJob.

FoundationDB

Mon, 01 Jan 0001 00:00:00 +0000

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).

Managed Harbor Container Registry

Mon, 01 Jan 0001 00:00:00 +0000

Harbor is an open-source trusted cloud-native registry project that stores, signs, and scans content.

Prerequisites

The Cozystack Harbor app stores its registry data exclusively in S3-compatible object storage: the chart pins the registry backend to S3 and exposes no filesystem option. That bucket is provisioned through COSI (objectstorage.k8s.io) from a SeaweedFS deployment, so before deploying Harbor the tenant must have SeaweedFS available — enabled on the same tenant or inherited from a parent tenant (the resolved class is propagated down the tenant tree, surfaced as the namespace.cozystack.io/seaweedfs namespace label).

Managed Kafka Service

Mon, 01 Jan 0001 00:00:00 +0000

Parameters

Common parameters

Name	Description	Type	Value
`external`	Enable external access from outside the cluster.	`bool`	`false`
`tls`	TLS configuration. Strimzi manages the cluster PKI automatically (no cert-manager is involved for this chart): the operator auto-creates `<release>-cluster-ca-cert` and `<release>-clients-ca-cert` secrets, both exposed for client trust setup. The internal TLS listener on 9093 is always on; this toggle only controls the external listener on 9094.	`object`	`{}`
`tls.enabled`	Enable TLS on the external listener. When unset, inherits the value of `external` (TLS is on when external access is enabled). Warning: setting this to false while external is true exposes Kafka over plaintext on a public IP via LoadBalancer. Strimzi does not provide authentication on this listener unless SCRAM, mTLS, or OAuth is separately configured. Use only in controlled networks.	`*bool`	`null`
`version`	Kafka version to deploy. Upgrade-only: once a cluster’s KRaft metadata is at a given version, Strimzi refuses an in-place downgrade, so lowering this on a running cluster (e.g. v3.9 back to v3.8) leaves the Kafka CR stuck in a reconcile error. Pick the target version at creation and only ever raise it.	`string`	`v3.9`

Application-specific parameters

Name	Description	Type	Value
`topics`	Topics configuration.	`[]object`	`[]`
`topics[i].name`	Topic name.	`string`	`""`
`topics[i].partitions`	Number of partitions.	`int`	`0`
`topics[i].replicas`	Number of replicas.	`int`	`0`
`topics[i].config`	Topic configuration.	`*object`	`null`

Kafka configuration

Name	Description	Type	Value
`kafka`	Kafka configuration.	`object`	`{}`
`kafka.replicas`	Number of Kafka replicas.	`int`	`3`
`kafka.resources`	Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied.	`object`	`{}`
`kafka.resources.cpu`	CPU available to each replica.	`quantity`	`""`
`kafka.resources.memory`	Memory (RAM) available to each replica.	`quantity`	`""`
`kafka.resourcesPreset`	Default sizing preset used when `resources` is omitted.	`string`	`c1.small`
`kafka.size`	Persistent Volume size for Kafka.	`quantity`	`10Gi`
`kafka.storageClass`	StorageClass used to store the Kafka data.	`string`	`""`
`kafka.controllerStorageSize`	Persistent Volume size for KRaft controller metadata (used during ZK-to-KRaft migration).	`quantity`	`5Gi`

Parameter examples and reference

resources and resourcesPreset

resources sets explicit CPU and memory configurations for each replica. Every resource it leaves unset is taken from the preset defined in resourcesPreset.

Managed MariaDB Service

Mon, 01 Jan 0001 00:00:00 +0000

The Managed MariaDB Service offers a powerful and widely used relational database solution. This service allows you to create and manage a replicated MariaDB cluster seamlessly.

Deployment Details

This managed service is controlled by mariadb-operator, ensuring efficient management and seamless operation.

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

Managed MongoDB Service

Mon, 01 Jan 0001 00:00:00 +0000

MongoDB is a popular document-oriented NoSQL database known for its flexibility and scalability. The Managed MongoDB Service provides a self-healing replicated cluster managed by the Percona Operator for MongoDB.

Deployment Details

This managed service is controlled by the Percona Operator for MongoDB, ensuring efficient management and seamless operation.

Deployment Modes

Replica Set Mode (default)

By default, MongoDB deploys as a replica set with the specified number of replicas. This mode is suitable for most use cases requiring high availability.

Managed NATS Service

Mon, 01 Jan 0001 00:00:00 +0000

NATS is an open-source, simple, secure, and high performance messaging system. It provides a data layer for cloud native applications, IoT messaging, and microservices architectures.

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
`replicas`	Number of replicas.	`int`	`2`
`resources`	Explicit CPU and memory configuration for each NATS replica. When omitted, the preset defined in `resourcesPreset` is applied.	`object`	`{}`
`resources.cpu`	CPU available to each replica.	`quantity`	`""`
`resources.memory`	Memory (RAM) available to each replica.	`quantity`	`""`
`resourcesPreset`	Default sizing preset used when `resources` is omitted.	`string`	`t1.nano`
`storageClass`	StorageClass used to store the data.	`string`	`""`
`external`	Enable external access from outside the cluster.	`bool`	`false`
`tls`	TLS configuration. When omitted, TLS follows the `external` flag.	`object`	`{}`
`tls.enabled`	Enable TLS. When omitted, TLS is enabled automatically when `external` is true.	`*bool`	`null`

Application-specific parameters

Name	Description	Type	Value
`users`	Users configuration map.	`map[string]object`	`{}`
`users[name].password`	Password for the user.	`string`	`""`
`jetstream`	Jetstream configuration.	`object`	`{}`
`jetstream.enabled`	Enable or disable Jetstream for persistent messaging in NATS.	`bool`	`true`
`jetstream.size`	Jetstream persistent storage size.	`quantity`	`10Gi`
`config`	NATS configuration.	`object`	`{}`
`config.merge`	Additional configuration to merge into NATS config.	`*object`	`{}`
`config.resolver`	Additional resolver configuration to merge into NATS config.	`*object`	`{}`

Parameter examples and reference

resources and resourcesPreset

resources sets explicit CPU and memory configurations for each replica. Every resource it leaves unset is taken from the preset defined in resourcesPreset.

Managed OpenBAO Service

Mon, 01 Jan 0001 00:00:00 +0000

OpenBAO is an open-source secrets management solution forked from HashiCorp Vault. It provides identity-based secrets and encryption management for cloud infrastructure.

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

Auto-unseal

By default OpenBAO uses Shamir key shares, so after every pod restart an operator has to unseal each replica by hand. Setting seal.type: static switches the instance to OpenBAO’s seal "static", which unseals the barrier from a 32-byte key read from a Secret in the tenant namespace. The chart never generates, stores or rotates the key. It only mounts the Secret you name.

Managed OpenSearch Service

Mon, 01 Jan 0001 00:00:00 +0000

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

TLS and client verification

The HTTP listener and Dashboards always serve TLS. tls.issuer selects who signs the certificate: cert-manager mints a private CA per release, operator leaves it to the CA the opster operator manages itself. Left unset, the field follows external, so a release published outside the cluster gets cert-manager and a cluster-internal one gets operator. Only cert-manager requires OpenSearch 2.0.0 or later: below that, choosing it explicitly fails the release, and a release that only set external falls back to the operator issuer so it keeps working. Under cert-manager the chart issues the certificate for the OpenSearch API and, when Dashboards is enabled, a separate one for Dashboards, both from that per-release CA. Transport mTLS between nodes stays operator-managed under either issuer.

Managed PostgreSQL Service

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL is currently the leading choice among relational databases, known for its robust features and performance. The Managed PostgreSQL Service takes advantage of platform-side implementation to provide a self-healing replicated cluster. This cluster is efficiently managed using the highly acclaimed CloudNativePG operator, which has gained popularity within the community.

Deployment Details

This managed service is controlled by the CloudNativePG operator, ensuring efficient management and seamless operation.

Managed Qdrant Service

Mon, 01 Jan 0001 00:00:00 +0000

Qdrant is a high-performance vector database and similarity search engine designed for AI and machine learning applications. It provides efficient storage and retrieval of high-dimensional vectors with advanced filtering capabilities, making it ideal for recommendation systems, semantic search, and RAG (Retrieval-Augmented Generation) applications.

Deployment Details

Service deploys Qdrant as a StatefulSet with automatic cluster mode when multiple replicas are configured.

Managed RabbitMQ Service

Mon, 01 Jan 0001 00:00:00 +0000

RabbitMQ is a robust message broker that plays a crucial role in modern distributed systems. Our Managed RabbitMQ Service simplifies the deployment and management of RabbitMQ clusters, ensuring reliability and scalability for your messaging needs.

Deployment Details

The service utilizes official RabbitMQ operator. This ensures the reliability and seamless operation of your RabbitMQ instances.

Managed Redis Service

Mon, 01 Jan 0001 00:00:00 +0000

Redis is a highly versatile and blazing-fast in-memory data store and cache that can significantly boost the performance of your applications. Managed Redis Service offers a hassle-free solution for deploying and managing Redis clusters, ensuring that your data is always available and responsive.

Deployment Details

Service utilizes the freshworks-oss Redis Operator (a maintained fork of the archived Spotahome operator) for efficient management and orchestration of Redis clusters.

Tenant Application Reference

Mon, 01 Jan 0001 00:00:00 +0000

A tenant is the main unit of security on the platform. The closest analogy would be Linux kernel namespaces.

Tenants can be created recursively and are subject to the following rules:

Tenant naming

Tenant names must be alphanumeric:

Lowercase letters (a-z) and digits (0-9) only
Must start with a lowercase letter
Dashes (-) are not allowed, unlike with other services
Maximum length depends on the cluster configuration (Helm release prefix and root domain)

This restriction exists to keep consistent naming in tenants, nested tenants, and services deployed in them. A tenant cannot be named foo-bar because parsing internal resource names like tenant-foo-bar would be ambiguous.

Managed Valkey Service

Mon, 01 Jan 0001 00:00:00 +0000

Valkey is a highly versatile and blazing-fast in-memory data store and cache that can significantly boost the performance of your applications. It is the BSD-3-Clause licensed, Linux Foundation-governed fork of Redis 7.2 and a drop-in replacement for it. Managed Valkey Service offers a hassle-free solution for deploying and managing Valkey clusters, ensuring that your data is always available and responsive.