Managed Applications: Guides and Reference on Cozystack

Adding External Applications to Cozystack Catalog

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

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

This guide explains how to define a managed application package and how to add it to Cozystack.

1. Create an Application Package Repository

Create a repository with the application package sources. For a reference, see github.com/cozystack/external-apps-example.

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

How to restore backup from S3

Find the snapshot:

restic -r s3:s3.example.org/clickhouse-backups/table_name snapshots

Restore it:

restic -r s3:s3.example.org/clickhouse-backups/table_name restore latest --target /tmp/

For more details, read Restic: Effective Backup from Stdin.

Parameters

Common parameters

Name	Description	Type	Value
`replicas`	Number of ClickHouse replicas.	`int`	`2`
`shards`	Number of ClickHouse shards.	`int`	`1`
`resources`	Explicit CPU and memory configuration for each ClickHouse 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`	`small`
`size`	Persistent Volume Claim size available for application data.	`quantity`	`10Gi`
`storageClass`	StorageClass used to store the data.	`string`	`""`

Application-specific parameters

Name	Description	Type	Value
`logStorageSize`	Size of Persistent Volume for logs.	`quantity`	`2Gi`
`logTTL`	TTL (expiration time) for `query_log` and `query_thread_log`.	`int`	`15`
`users`	Users configuration map.	`map[string]object`	`{}`
`users[name].password`	Password for the user.	`string`	`""`
`users[name].readonly`	User is readonly (default: false).	`bool`	`false`

Backup parameters

Name	Description	Type	Value
`backup`	Backup configuration.	`object`	`{}`
`backup.enabled`	Enable regular backups (default: false).	`bool`	`false`
`backup.s3Region`	AWS S3 region where backups are stored.	`string`	`us-east-1`
`backup.s3Bucket`	S3 bucket used for storing backups.	`string`	`s3.example.org/clickhouse-backups`
`backup.schedule`	Cron schedule for automated backups.	`string`	`0 2 * * *`
`backup.cleanupStrategy`	Retention strategy for cleaning up old backups.	`string`	`--keep-last=3 --keep-daily=3 --keep-within-weekly=1m`
`backup.s3AccessKey`	Access key for S3 authentication.	`string`	`<your-access-key>`
`backup.s3SecretKey`	Secret key for S3 authentication.	`string`	`<your-secret-key>`
`backup.resticPassword`	Password for Restic backup encryption.	`string`	`<password>`

ClickHouse Keeper parameters

Name	Description	Type	Value
`clickhouseKeeper`	ClickHouse Keeper configuration.	`object`	`{}`
`clickhouseKeeper.enabled`	Deploy ClickHouse Keeper for cluster coordination.	`bool`	`true`
`clickhouseKeeper.size`	Persistent Volume Claim size available for application data.	`quantity`	`1Gi`
`clickhouseKeeper.resourcesPreset`	Default sizing preset.	`string`	`micro`
`clickhouseKeeper.replicas`	Number of Keeper replicas.	`int`	`3`

Parameter examples and reference

resources and resourcesPreset

resources sets explicit CPU and memory configurations for each replica. When left empty, the preset defined in resourcesPreset is applied.

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

# Cluster process configuration
cluster:
 version: "7.3.63"
 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"

Backup (Optional)

backup:
 enabled: true
 s3:
 bucket: "my-fdb-backups"
 endpoint: "https://s3.amazonaws.com"
 region: "us-east-1"
 credentials:
 accessKeyId: "AKIA..."
 secretAccessKey: "..."
 retentionPolicy: "7d"

Advanced Configuration

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

# Image type (unified is default and recommended for new deployments)
imageType: "unified"

# 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

Install the FoundationDB operator (system package)
Deploy this application package with your desired configuration
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:

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.

Parameters

Common parameters

Name	Description	Type	Value
`host`	Hostname for external access to Harbor (defaults to ‘harbor’ subdomain for the tenant host).	`string`	`""`
`storageClass`	StorageClass used to store the data.	`string`	`""`

Component configuration

Name	Description	Type	Value
`core`	Core API server configuration.	`object`	`{}`
`core.resources`	Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied.	`object`	`{}`
`core.resources.cpu`	Number of CPU cores allocated.	`quantity`	`""`
`core.resources.memory`	Amount of memory allocated.	`quantity`	`""`
`core.resourcesPreset`	Default sizing preset used when `resources` is omitted.	`string`	`small`
`registry`	Container image registry configuration.	`object`	`{}`
`registry.resources`	Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied.	`object`	`{}`
`registry.resources.cpu`	Number of CPU cores allocated.	`quantity`	`""`
`registry.resources.memory`	Amount of memory allocated.	`quantity`	`""`
`registry.resourcesPreset`	Default sizing preset used when `resources` is omitted.	`string`	`small`
`jobservice`	Background job service configuration.	`object`	`{}`
`jobservice.resources`	Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied.	`object`	`{}`
`jobservice.resources.cpu`	Number of CPU cores allocated.	`quantity`	`""`
`jobservice.resources.memory`	Amount of memory allocated.	`quantity`	`""`
`jobservice.resourcesPreset`	Default sizing preset used when `resources` is omitted.	`string`	`nano`
`trivy`	Trivy vulnerability scanner configuration.	`object`	`{}`
`trivy.enabled`	Enable or disable the vulnerability scanner.	`bool`	`true`
`trivy.size`	Persistent Volume size for vulnerability database cache.	`quantity`	`5Gi`
`trivy.resources`	Explicit CPU and memory configuration. When omitted, the preset defined in `resourcesPreset` is applied.	`object`	`{}`
`trivy.resources.cpu`	Number of CPU cores allocated.	`quantity`	`""`
`trivy.resources.memory`	Amount of memory allocated.	`quantity`	`""`
`trivy.resourcesPreset`	Default sizing preset used when `resources` is omitted.	`string`	`nano`
`database`	PostgreSQL database configuration.	`object`	`{}`
`database.size`	Persistent Volume size for database storage.	`quantity`	`5Gi`
`database.replicas`	Number of database instances.	`int`	`2`
`redis`	Redis cache configuration.	`object`	`{}`
`redis.size`	Persistent Volume size for cache storage.	`quantity`	`1Gi`
`redis.replicas`	Number of Redis replicas.	`int`	`2`

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`

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`	`{}`

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`	`small`
`kafka.size`	Persistent Volume size for Kafka.	`quantity`	`10Gi`
`kafka.storageClass`	StorageClass used to store the Kafka data.	`string`	`""`

ZooKeeper configuration

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

Parameter examples and reference

resources and resourcesPreset

resources sets explicit CPU and memory configurations for each replica. When left empty, the preset defined in resourcesPreset is applied.

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.

HowTos

How to switch master/slave replica

kubectl edit mariadb <instance>

update:

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.

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`	`nano`
`storageClass`	StorageClass used to store the data.	`string`	`""`
`external`	Enable external access from outside the cluster.	`bool`	`false`

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. When left empty, the preset defined in resourcesPreset is applied.

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.

Parameters

Common parameters

Name	Description	Type	Value
`replicas`	Number of OpenBAO replicas. HA with Raft is automatically enabled when replicas > 1. Switching between standalone (file storage) and HA (Raft storage) modes requires data migration.	`int`	`1`
`resources`	Explicit CPU and memory configuration for each OpenBAO 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`	`small`
`size`	Persistent Volume Claim size for data storage.	`quantity`	`10Gi`
`storageClass`	StorageClass used to store the data.	`string`	`""`
`external`	Enable external access from outside the cluster.	`bool`	`false`

Application-specific parameters

Name	Description	Type	Value
`ui`	Enable the OpenBAO web UI.	`bool`	`true`

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 Spotahome Redis 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 follow DNS-1035 naming rules:

Must start with a lowercase letter (a-z)
Can only contain lowercase letters, numbers, and hyphens (a-z, 0-9, -)
Must end with a letter or number (not a hyphen)
Maximum length depends on the cluster configuration (Helm release prefix and root domain)

Note: Using dashes (-) in tenant names is allowed but discouraged, unlike with other services. This is to keep consistent naming in tenants, nested tenants, and services deployed in them. Names with dashes (e.g., foo-bar) may lead to ambiguous parsing of internal resource names like tenant-foo-bar.