Cozystack Cluster Configuration on Cozystack

Platform Package Reference

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

This page explains the role of the Cozystack Platform Package and provides a full reference for its values.

Cozystack’s main configuration is defined by a Package custom resource. This Package includes the Cozystack variant and component settings, key network settings, exposed services, and other options.

Example

Here’s an example of configuration for installing Cozystack with variant isp-full, with root host “example.org”, and Cozystack Dashboard and API exposed and available to users:

apiVersion: cozystack.io/v1alpha1
kind: Package
metadata:
 name: cozystack.cozystack-platform
spec:
 variant: isp-full
 components:
 platform:
 values:
 publishing:
 host: "example.org"
 apiServerEndpoint: "https://api.example.org:443"
 exposedServices:
 - dashboard
 - api
 networking:
 podCIDR: "10.244.0.0/16"
 podGateway: "10.244.0.1"
 serviceCIDR: "10.96.0.0/16"
 joinCIDR: "100.64.0.0/16"

Reference

Package-level fields

Field	Description
`spec.variant`	Variant to use for installation (e.g., `isp-full`, `isp-full-generic`, `isp-hosted`, `distro-full`).

Platform values (`spec.components.platform.values.*`)

Publishing

Value	Default	Description
`publishing.host`	`"example.org"`	The main domain for all services created under Cozystack, such as the dashboard, Grafana, Keycloak, etc.
`publishing.apiServerEndpoint`	`""`	Used for generating kubeconfig files for your users. It is recommended to use a routable FQDN or IP address instead of local-only addresses. Example: `"https://api.example.org"`.
`publishing.exposedServices`	`[api, dashboard, vm-exportproxy, cdi-uploadproxy]`	List of services to expose. Possible values: `api`, `dashboard`, `cdi-uploadproxy`, `vm-exportproxy`.
`publishing.ingressName`	`"tenant-root"`	Ingress controller to use for exposing services.
`publishing.externalIPs`	`[]`	List of external IPs used for the specified ingress controller. If not specified, a LoadBalancer service is used by default.
`publishing.certificates.solver`	`"http01"`	ACME challenge solver type for default letsencrypt issuer. Possible values: `http01`, `dns01`.
`publishing.certificates.issuerName`	`"letsencrypt-prod"`	`ClusterIssuer` name for TLS certificates used in system Helm releases.

Networking

Value	Default	Description
`networking.clusterDomain`	`"cozy.local"`	Internal cluster domain name.
`networking.podCIDR`	`"10.244.0.0/16"`	The pod subnet used by Pods to assign IPs.
`networking.podGateway`	`"10.244.0.1"`	The gateway address for the pod subnet.
`networking.serviceCIDR`	`"10.96.0.0/16"`	The service subnet used by Services to assign IPs.
`networking.joinCIDR`	`"100.64.0.0/16"`	The `join` subnet for network communication between the Node and Pod. Follow the kube-ovn documentation to learn more.
`networking.kubeovn.MASTER_NODES`	`""`	Comma-separated list of KubeOVN master node IPs. By default, KubeOVN uses `lookup` to find control-plane nodes by label `node-role.kubernetes.io/control-plane`. On fresh clusters, lookup may return empty results. Set this to override.

Bundles

Value	Default	Description
`bundles.system.enabled`	`false`	Enable the system bundle. Managed by the operator based on `spec.variant`.
`bundles.system.variant`	`"isp-full"`	System bundle variant. Options: `isp-full`, `isp-full-generic`, `isp-hosted`. Managed by the operator based on `spec.variant`.
`bundles.iaas.enabled`	`false`	Enable the IaaS bundle. Managed by the operator based on `spec.variant`.
`bundles.paas.enabled`	`false`	Enable the PaaS bundle. Managed by the operator based on `spec.variant`.
`bundles.naas.enabled`	`false`	Enable the NaaS bundle. Managed by the operator based on `spec.variant`.
`bundles.enabledPackages`	`[]`	List of optional bundle components to include in the installation. Read more in “How to enable and disable bundle components”.
`bundles.disabledPackages`	`[]`	List of bundle components to exclude from the installation. Read more in “How to enable and disable bundle components”.

Authentication

Value	Default	Description
`authentication.oidc.enabled`	`false`	Enable OIDC feature in Cozystack.
`authentication.oidc.insecureSkipVerify`	`false`	Skip TLS certificate verification for the OIDC provider.
`authentication.oidc.keycloakExtraRedirectUri`	`""`	Additional redirect URI for Keycloak OIDC client.
`authentication.oidc.keycloakInternalUrl`	`""`	Internal URL for backend-to-backend requests to Keycloak. When set, the dashboard’s oauth2-proxy skips OIDC discovery and routes token, JWKS, userinfo, and logout requests through this URL while keeping browser redirects on the external URL. Example: `http://keycloak-http.cozy-keycloak.svc:8080/realms/cozy`.

Scheduling

Value	Default	Description
`scheduling.globalAppTopologySpreadConstraints`	`""`	Global pod topology spread constraints applied to all managed applications.

Branding

Value	Default	Description
`branding`	`{}`	UI branding configuration object. See the White Labeling guide for available fields and usage. Individual fields (e.g., `titleText`, `logoSvg`) have their own defaults when not specified.

Registries

Container registry mirrors configuration. Allows routing image pulls through local mirrors.

Cozystack Variants: Overview and Comparison

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

Introduction

Variants are pre-defined configurations of Cozystack that determine which bundles and components are enabled. Each variant is tested, versioned, and guaranteed to work as a unit. They simplify installation, reduce the risk of misconfiguration, and make it easier to choose the right set of features for your deployment.

This guide is for infrastructure engineers, DevOps teams, and platform architects planning to deploy Cozystack in different environments. It explains how Cozystack variants help tailor the installation to specific needs—whether you’re building a fully featured platform-as-a-service or need full manual control over installed packages.

Cozystack Components Reference

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

Overwriting Component Parameters

You might want to override specific options for the components. To achieve this, modify the corresponding Package resource and specify values in the spec.components section. The values structure follows the values.yaml of the respective system chart in the Cozystack repository.

For example, if you want to enable FRR-K8s mode for MetalLB, look at its values.yaml to understand the available parameters, then modify the cozystack.metallb Package:

apiVersion: cozystack.io/v1alpha1
kind: Package
metadata:
 name: cozystack.metallb
 namespace: cozy-system
spec:
 variant: default
 components:
 metallb:
 values:
 metallb:
 frrk8s:
 enabled: true

Enabling and Disabling Components

Bundles have optional components that need to be explicitly enabled (included) in the installation. Regular bundle components can, on the other hand, be disabled (excluded) from the installation, when you don’t need them.

Licenses

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

This page lists the licenses for the primary components packaged with Cozystack. Cozystack-maintained charts, CRDs, controllers, and application APIs are licensed under Apache-2.0. When a package vendors or deploys an upstream component, the table shows the upstream component license.

This reference covers top-level Cozystack packages from packages/core, packages/system, packages/apps, and packages/extra, plus the primary managed workload runtimes. Container images can include additional operating-system packages and library dependencies with their own licenses.

Core Packages

Package	Component	License	Source
`core/flux-aio`	Cozystack Flux AIO manifests	Apache-2.0	source
`core/installer`	Cozystack installer chart	Apache-2.0	source
`core/platform`	Cozystack Platform Package chart	Apache-2.0	source
`core/talos`	Cozystack Talos assets	Apache-2.0	source
`core/testing`	Cozystack test chart	Apache-2.0	source

System Packages

Package	Component	License	Source
`system/application-definition-crd`	Cozystack ApplicationDefinition CRD	Apache-2.0	source
`system/backup-controller`	Cozystack backup controller	Apache-2.0	source
`system/backupstrategy-controller`	Cozystack backup strategy controller	Apache-2.0	source
`system/bootbox`	Tinkerbell Smee	Apache-2.0	source
`system/bootbox-rd`	Cozystack Bootbox resource definition	Apache-2.0	source
`system/bucket`	S3 Manager	Apache-2.0	source
`system/bucket-rd`	Cozystack Bucket resource definition	Apache-2.0	source
`system/capi-operator`	Cluster API Operator	Apache-2.0	source
`system/capi-providers-bootstrap`	Cluster API kubeadm bootstrap provider	Apache-2.0	source
`system/capi-providers-core`	Cluster API core provider	Apache-2.0	source
`system/capi-providers-cpprovider`	Kamaji Cluster API control-plane provider	Apache-2.0	source
`system/capi-providers-infraprovider`	KubeVirt Cluster API infrastructure provider	Apache-2.0	source
`system/cert-manager`	cert-manager	Apache-2.0	source
`system/cert-manager-crds`	cert-manager CRDs	Apache-2.0	source
`system/cert-manager-issuers`	Cozystack cert-manager issuers	Apache-2.0	source
`system/cilium`	Cilium	Apache-2.0	source
`system/cilium-networkpolicy`	Cozystack Cilium network policies	Apache-2.0	source
`system/clickhouse-operator`	Altinity ClickHouse Operator	Apache-2.0	source
`system/clickhouse-rd`	Cozystack ClickHouse resource definition	Apache-2.0	source
`system/cluster-autoscaler`	Kubernetes Cluster Autoscaler	Apache-2.0	source
`system/clustersecret-operator`	SAP ClusterSecret Operator	Apache-2.0	source
`system/coredns`	CoreDNS	Apache-2.0	source
`system/cozy-proxy`	cozy-proxy	Apache-2.0	source
`system/cozystack-api`	Cozystack API	Apache-2.0	source
`system/cozystack-basics`	Cozystack basics	Apache-2.0	source
`system/cozystack-controller`	Cozystack controller	Apache-2.0	source
`system/cozystack-scheduler`	Cozystack scheduler	Apache-2.0	source
`system/dashboard`	Cozystack dashboard	Apache-2.0	source
`system/etcd-operator`	Aenix etcd Operator	Apache-2.0	source
`system/etcd-rd`	Cozystack etcd resource definition	Apache-2.0	source
`system/external-dns`	ExternalDNS	Apache-2.0	source
`system/external-dns-rd`	Cozystack ExternalDNS resource definition	Apache-2.0	source
`system/external-secrets-operator`	External Secrets Operator	Apache-2.0	source
`system/flux-plunger`	Cozystack Flux plunger	Apache-2.0	source
`system/fluxcd`	ControlPlane Flux instance chart; Flux controllers	AGPL-3.0; Apache-2.0	charts, flux
`system/fluxcd-operator`	ControlPlane Flux Operator	AGPL-3.0	source
`system/foundationdb-operator`	FoundationDB Kubernetes Operator	Apache-2.0	source
`system/foundationdb-rd`	Cozystack FoundationDB resource definition	Apache-2.0	source
`system/gateway-api-crds`	Kubernetes Gateway API CRDs	Apache-2.0	source
`system/goldpinger`	Goldpinger	Apache-2.0	source
`system/gpu-operator`	NVIDIA GPU Operator	Apache-2.0	source
`system/grafana-operator`	Grafana Operator	Apache-2.0	source
`system/hami`	HAMi	Apache-2.0	source
`system/harbor`	Harbor Helm chart	Apache-2.0	source
`system/harbor-rd`	Cozystack Harbor resource definition	Apache-2.0	source
`system/hetzner-robotlb`	RobotLB	MIT	source
`system/http-cache-rd`	Cozystack HTTP cache resource definition	Apache-2.0	source
`system/info-rd`	Cozystack Info resource definition	Apache-2.0	source
`system/ingress-nginx`	ingress-nginx	Apache-2.0	source
`system/ingress-rd`	Cozystack Ingress resource definition	Apache-2.0	source
`system/kafka-operator`	Strimzi Kafka Operator	Apache-2.0	source
`system/kafka-rd`	Cozystack Kafka resource definition	Apache-2.0	source
`system/kamaji`	Kamaji	Apache-2.0	source
`system/keycloak`	Keycloak	Apache-2.0	source
`system/keycloak-configure`	Cozystack Keycloak configuration job	Apache-2.0	source
`system/keycloak-operator`	KubeRocketCI Keycloak Operator	Apache-2.0	source
`system/kilo`	Kilo	Apache-2.0	source
`system/kubeovn`	Kube-OVN chart	Apache-2.0	source
`system/kubeovn-plunger`	Cozystack Kube-OVN plunger	Apache-2.0	source
`system/kubeovn-webhook`	Cozystack Kube-OVN webhook	Apache-2.0	source
`system/kubernetes-rd`	Cozystack Kubernetes resource definition	Apache-2.0	source
`system/kubevirt`	KubeVirt	Apache-2.0	source
`system/kubevirt-cdi`	KubeVirt Containerized Data Importer	Apache-2.0	source
`system/kubevirt-cdi-operator`	KubeVirt CDI Operator	Apache-2.0	source
`system/kubevirt-csi-node`	KubeVirt CSI driver	Apache-2.0	source
`system/kubevirt-instancetypes`	KubeVirt common instancetypes	Apache-2.0	source
`system/kubevirt-operator`	KubeVirt Operator	Apache-2.0	source
`system/lineage-controller-webhook`	Cozystack lineage controller webhook	Apache-2.0	source
`system/linstor`	LINSTOR Server; LINSTOR CSI	GPL-3.0; Apache-2.0	server, csi
`system/linstor-gui`	LINSTOR GUI	GPL-3.0	source
`system/linstor-scheduler`	LINSTOR scheduler extender	Apache-2.0	source
`system/local-ccm`	Local Cloud Controller Manager	Apache-2.0	source
`system/mariadb-operator`	mariadb-operator	MIT	source
`system/mariadb-rd`	Cozystack MariaDB resource definition	Apache-2.0	source
`system/metallb`	MetalLB	Apache-2.0	source
`system/metrics-server`	Metrics Server	Apache-2.0	source
`system/mongodb-operator`	Percona Operator for MongoDB Helm chart	Apache-2.0	source
`system/mongodb-rd`	Cozystack MongoDB resource definition	Apache-2.0	source
`system/monitoring`	Cozystack monitoring package	Apache-2.0	source
`system/monitoring-agents`	Fluent Bit; kube-state-metrics; node-exporter	Apache-2.0	source
`system/monitoring-rd`	Cozystack Monitoring resource definition	Apache-2.0	source
`system/multus`	Multus CNI	Apache-2.0	source
`system/nats`	NATS Helm chart	Apache-2.0	source
`system/nats-rd`	Cozystack NATS resource definition	Apache-2.0	source
`system/nfs-driver`	CSI Driver NFS	Apache-2.0	source
`system/objectstorage-controller`	Container Object Storage Interface controller	Apache-2.0	source
`system/openbao`	OpenBao Helm chart	MPL-2.0	source
`system/openbao-rd`	Cozystack OpenBao resource definition	Apache-2.0	source
`system/opencost`	OpenCost Helm chart	Apache-2.0	source
`system/opensearch-operator`	OpenSearch Operator	Apache-2.0	source
`system/opensearch-rd`	Cozystack OpenSearch resource definition	Apache-2.0	source
`system/piraeus-operator`	Piraeus Operator	Apache-2.0	source
`system/piraeus-operator-crds`	Piraeus Operator CRDs	Apache-2.0	source
`system/postgres-operator`	CloudNativePG operator chart	Apache-2.0	source
`system/postgres-rd`	Cozystack PostgreSQL resource definition	Apache-2.0	source
`system/prometheus-operator-crds`	Prometheus Operator CRDs chart	Apache-2.0	source
`system/qdrant`	Qdrant Helm chart	Apache-2.0	source
`system/qdrant-rd`	Cozystack Qdrant resource definition	Apache-2.0	source
`system/rabbitmq-operator`	RabbitMQ cluster and topology operators	MPL-2.0	source
`system/rabbitmq-rd`	Cozystack RabbitMQ resource definition	Apache-2.0	source
`system/redis-operator`	Spotahome Redis Operator	Apache-2.0	source
`system/redis-rd`	Cozystack Redis resource definition	Apache-2.0	source
`system/reloader`	Stakater Reloader	Apache-2.0	source
`system/seaweedfs`	SeaweedFS Helm chart	Apache-2.0	source
`system/seaweedfs-rd`	Cozystack SeaweedFS resource definition	Apache-2.0	source
`system/snapshot-controller`	CSI external snapshotter	Apache-2.0	source
`system/tcp-balancer-rd`	Cozystack TCP balancer resource definition	Apache-2.0	source
`system/telepresence`	Telepresence Traffic Manager chart	Apache-2.0	source
`system/tenant-rd`	Cozystack Tenant resource definition	Apache-2.0	source
`system/velero`	Velero Helm chart	Apache-2.0	source
`system/vertical-pod-autoscaler`	Vertical Pod Autoscaler chart	MIT; Apache-2.0	source
`system/vertical-pod-autoscaler-crds`	Vertical Pod Autoscaler CRDs	Apache-2.0	source
`system/victoria-metrics-operator`	VictoriaMetrics Operator chart	Apache-2.0	source
`system/virtualprivatecloud-rd`	Cozystack VPC resource definition	Apache-2.0	source
`system/vm-default-images`	Cozystack VM default image catalog	Apache-2.0	source
`system/vm-disk-rd`	Cozystack VM disk resource definition	Apache-2.0	source
`system/vm-instance-rd`	Cozystack VM instance resource definition	Apache-2.0	source
`system/vpn-rd`	Cozystack VPN resource definition	Apache-2.0	source
`system/vsnap-crd`	CSI VolumeSnapshot CRDs	Apache-2.0	source

Application and Extra Packages

The following packages define Cozystack application APIs and tenant-level extras. Their package source is Apache-2.0; runtime software licenses for managed services are listed in the next section.

White Labeling

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

White labeling allows you to replace default Cozystack branding with your own logos and text across the Dashboard UI and Keycloak authentication pages.

Overview

Branding is configured through the branding field in the Platform Package (spec.components.platform.values.branding). The configuration propagates automatically to:

Dashboard: logo, page title, footer text, favicon, and tenant identifier
Keycloak: realm display name on authentication pages

Configuration

Edit your Platform Package to add or update the branding section:

Telemetry

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

This document outlines the telemetry feature within the Cozystack project, detailing the rationale behind data collection, the nature of the data collected, data handling practices, and instructions for opting out.

Why We Collect Telemetry

Cozystack, as an open source project, thrives on community feedback and usage insights. Telemetry data allows maintainers to understand how Cozystack is being used in real-world scenarios. This data informs decisions related to feature prioritization, testing strategies, bug fixes, and overall project evolution. Without telemetry, decisions would rely on guesswork or limited feedback, which might slow down improvement cycles or introduce features that don’t align with users’ needs. Telemetry ensures that development is guided by actual usage patterns and community requirements, fostering a more robust and user-centric platform.

Cozystack Cluster Configuration on Cozystack

Platform Package Reference

Example

Reference

Package-level fields

Platform values (spec.components.platform.values.*)

Publishing

Networking

Bundles

Authentication

Scheduling

Branding

Registries

Cozystack Variants: Overview and Comparison

Introduction

Cozystack Components Reference

Overwriting Component Parameters

Enabling and Disabling Components

Licenses

Core Packages

System Packages

Application and Extra Packages

White Labeling

Overview

Configuration

Telemetry

Why We Collect Telemetry

Platform values (`spec.components.platform.values.*`)