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.ingressNameAdmin`	`""`	Name of a separate admin ingress that system components attach their admin routes to (currently only Keycloak) — for example one bound to a private IP and unreachable from the internet. On the Gateway path the value is a namespace (of a `Gateway` named `cozystack`); on the ingress-nginx path it is an `ingressClassName`. The two coincide because Cozystack names each ingressClass after its tenant namespace. Empty (the default) keeps admin endpoints on `publishing.ingressName`. Two caveats: Cozystack does not create the admin Gateway — provision it out of band first, or the admin routes attach to nothing; and the admin routes render only when Keycloak’s `ingress.adminHost` is set, so setting this key alone is a no-op.
`publishing.exposureClass.name`	`""`	Logical name of the cluster-scoped `ExposureClass` to render. Empty (the default) leaves the `publishing.externalIPs` path untouched. When set, the host ingress — with `publishing.externalIPs` empty — publishes its Service as `type: LoadBalancer`, and `cozystack-controller` translates the class into the chosen backend’s VIP pool and announcer. This is the migration path off `Service.spec.externalIPs`, deprecated in Kubernetes v1.36 (KEP-5707). The removal is phased: the `AllowServiceExternalIPs` feature gate ships enabled in v1.36, then defaults to false (KEP target: v1.40), at which point kube-proxy stops programming rules for the field — the API still accepts it, so the Service looks healthy while no traffic arrives. Later phases lock the gate off and strip kube-proxy’s support outright, and finally drop the gate and the `DenyServiceExternalIPs` admission controller. The KEP gives those later releases as approximate and the v1.36 announcement commits only to “a future minor release”, so treat the default flipping to false as the deadline and migrate onto a class before that upgrade rather than planning against a specific version.
`publishing.exposureClass.backend`	`"externalIPs"`	LoadBalancer mechanism behind the class. `externalIPs` pins node IPs with no pool or announcer (the historical behaviour); `metallb` renders an `IPAddressPool` + `L2Advertisement`; `cilium` renders a `CiliumLoadBalancerIPPool` + `CiliumL2AnnouncementPolicy`; `robotlb` uses a cloud (Hetzner) load balancer, where allocation and announcement happen off-cluster. Once `publishing.exposureClass.name` is set, a pool or cloud backend (`metallb`, `cilium`, `robotlb`) is mutually exclusive with a non-empty `publishing.externalIPs` — the platform render fails with an explicit error rather than shipping the dead end, because the host ingress Service would stay `ClusterIP` + `externalIPs`, never become `type: LoadBalancer`, and the allocated pool would go unused.
`publishing.exposureClass.addresses`	`[]`	VIP CIDRs or `start-end` ranges for the pool-backed backends (`metallb`, `cilium`).
`publishing.exposureClass.l2`	`true`	L2 (ARP / NDP) announcement for the bare-metal backends.
`publishing.exposureClass.isDefault`	`true`	Make this the class used by any `ServiceExposure` that names none. A `ServiceExposure` is the cluster-internal resource `cozystack-controller` reconciles to publish a Service through the class’s backend; workloads do not create one directly. Because this defaults to `true`, hand-creating a second `ExposureClass` without clearing its default flag leaves two default classes, and the controller then fails every unnamed `ServiceExposure` with `AmbiguousDefaultClass` — keep exactly one 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.
`publishing.certificates.wildcard`	`false`	Opt-in shared wildcard certificate on the default ingress-nginx path (`gateway.enabled=false`). When `true` with `solver=dns01` and no `publishing.certificates.wildcardSecretName`, the platform issues one `.<root-host>` + `<root-host>` `Certificate` via the DNS-01 `ClusterIssuer` and serves it as the ingress controller’s default SSL certificate, so system services stop minting a per-host ACME certificate each — avoiding Let’s Encrypt rate limits at scale, at parity with the Gateway API path. Ignored on `http01` (cannot issue wildcards) and when `gateway.enabled=true` (the `TenantGateway` controller issues the wildcard there). Enabling it feeds the issued Secret name into the same cluster values channel as `publishing.certificates.wildcardSecretName`, so it carries the same child-tenant hazard and the same open bug ( cozystack/cozystack#3296): every tenant’s system ingresses drop their per-host ACME certificate cluster-wide, but the wildcard is served only by the publishing controller. A child tenant running its own ingress controller (`ingress: true`) is then left with no certificate and serves ingress-nginx’s built-in self-signed one; an inheriting child on the shared controller instead gets a hostname mismatch, because a single-label `.<root-host>` wildcard does not cover a nested `<service>.<tenant>.<root-host>` host or a custom `ingress.host` on another domain. Only enable it when every exposed host is covered and no child tenant runs its own ingress controller. Off by default so a `dns01` cluster is never switched silently on upgrade.
`publishing.certificates.wildcardSecretName`	`""`	Operator-provided wildcard TLS Secret. When set, platform services and the root tenant’s ingress/Gateway serve this pre-existing Secret instead of minting per-host ACME certificates (only the NAME travels the values channel — never the key material), and takes precedence over `publishing.certificates.wildcard`. The Secret must exist in the publishing namespace (`tenant-root` by default), hold valid PEM under `tls.crt` / `tls.key` (created as `kubernetes.io/tls`, though only the material is validated), and cover the served hosts. Scoped to the root tenant but not enforced — the name reaches every tenant, so a child running its own ingress controller can be left serving a self-signed certificate ( cozystack/cozystack#3296). See Gateway API → Certificates for the full behaviour and the three child-tenant cases. Leave empty to keep ACME issuance.
`publishing.certificates.dns01.provider`	`"cloudflare"`	DNS-01 provider when `solver=dns01`. Possible values: `cloudflare`, `route53`, `digitalocean`, `rfc2136`. Both the per-tenant Issuer (rendered by `cozystack-controller` from the `TenantGateway` CR) and the cluster-wide `letsencrypt-prod` / `letsencrypt-stage` `ClusterIssuer`s used by the legacy ingress flow read this.
`publishing.certificates.dns01.cloudflare.secretName`	`"cloudflare-api-token-secret"`	Secret name holding a Cloudflare API token with `Zone:Read` + `Zone:DNS:Edit` on the apex zone.
`publishing.certificates.dns01.cloudflare.secretKey`	`"api-token"`	Key inside the Secret holding the API token.
`publishing.certificates.dns01.route53.region`	`""`	AWS region of the Route53 hosted zone. Required when `provider=route53`.
`publishing.certificates.dns01.route53.accessKeyID`	`""`	IAM access key ID. Optional when running with IRSA / instance profile.
`publishing.certificates.dns01.route53.secretName`	`""`	Secret name holding the IAM secret access key. Optional when running with IRSA / instance profile.
`publishing.certificates.dns01.route53.secretKey`	`"secret-access-key"`	Key inside the Route53 Secret holding the secret access key.
`publishing.certificates.dns01.digitalocean.secretName`	`"digitalocean-api-token-secret"`	Secret name holding a DigitalOcean API token with write access to the apex domain.
`publishing.certificates.dns01.digitalocean.secretKey`	`"access-token"`	Key inside the Secret holding the DigitalOcean token.
`publishing.certificates.dns01.rfc2136.nameserver`	`""`	`host:port` of the authoritative nameserver accepting RFC 2136 dynamic updates. Required when `provider=rfc2136`.
`publishing.certificates.dns01.rfc2136.tsigKeyName`	`""`	TSIG key name authorising the dynamic updates. Required when `provider=rfc2136`.
`publishing.certificates.dns01.rfc2136.tsigAlgorithm`	`"HMACSHA256"`	TSIG HMAC algorithm.
`publishing.certificates.dns01.rfc2136.secretName`	`""`	Secret name holding the TSIG key material. Required when `provider=rfc2136`.
`publishing.certificates.dns01.rfc2136.secretKey`	`"tsig-secret-key"`	Key inside the Secret holding the TSIG key.
`publishing.proxyProtocol`	`false`	Enables PROXY-protocol on the host ingress-nginx and auto-deploys ouroboros to fix the resulting hairpin-NAT problem. The upstream L4 LB in front of ingress-nginx must already be injecting PROXY-v1 headers before this flag flips on; see the linked page for verification recipes and the disable path.
`publishing.proxyProtocolAcknowledgeUnclean`	`false`	Acknowledgement gate for the `helm.sh/resource-policy: keep` asymmetry on the host disable path. Flipping `publishing.proxyProtocol` from `true` back to `false` stops emitting the `cozystack.ouroboros` Package CR but does not uninstall the existing one — the platform render fails until either the Package CR is deleted (which triggers the chart’s pre-delete cleanup hook) or this flag is set to `true` to confirm the operator has handled the asymmetry. See hairpin-proxy-protocol → Disable path for the full sequence.

publishing.exposure is not listed above on purpose: the key existed in v1.4 only and was removed before v1.5 shipped. It still works on a v1.4 cluster, but has no effect from v1.5 onward — publishing.exposureClass is its successor. Drop the key when upgrading from v1.4 — and check what the host ingress Service becomes. A v1.4 cluster running publishing.exposure: loadBalancer had a LoadBalancer Service with externalTrafficPolicy: Local; from v1.5 the key is ignored, so a cluster with publishing.externalIPs set silently falls back to a ClusterIP Service with externalTrafficPolicy: Cluster and stops preserving client source IPs.

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 open-source components Cozystack ships, grouped by their role in the platform. Cozystack-maintained charts, CRDs, controllers, and application APIs are licensed under Apache-2.0 and are not listed individually below. For each upstream component, the card links to the upstream license file.

This reference is hand-curated against the current next set of components. Container images can include additional operating-system packages and library dependencies with their own licenses. Pinned upstream versions of managed runtimes (PostgreSQL, MariaDB, Kafka, etc.) may change between Cozystack minor releases — check the version of Cozystack you run.

Operating system and Kubernetes runtime

Talos Linux

Immutable Linux distribution built for Kubernetes nodes.

The Lineage Controller Webhook

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

The lineage controller webhook is a mutating admission webhook shipped as part of the cozystack.cozystack-engine Package. On every CREATE and UPDATE of a tenant Pod, Secret, Service, PersistentVolumeClaim, Ingress, or WorkloadMonitor it walks up the ownership graph and stamps the owning Cozystack Application’s identity onto the resource as labels (apps.cozystack.io/application.{group,kind,name}). The Cozystack dashboard, the aggregated API server, and the SchedulingClass mechanism all rely on those labels.

The webhook is registered with failurePolicy: Fail, so the kube-apiserver must be able to reach a healthy webhook pod for tenant CREATE/UPDATE traffic to succeed.

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

Cozystack Variants: Overview and Comparison

Introduction

Cozystack Components Reference

Overwriting Component Parameters

Enabling and Disabling Components

Licenses

Operating system and Kubernetes runtime

The Lineage Controller Webhook

White Labeling

Overview

Configuration

Telemetry

Why We Collect Telemetry

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