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.

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

White Labeling

Overview

Configuration

Telemetry

Why We Collect Telemetry

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