Customizer — Declarative Cluster Customizations on Cozystack

Setup Guide

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

This guide walks through enabling the customizer on a fresh cluster and getting your first commit reconciled. It assumes Cozystack is already installed and healthy, and you have admin access (you can patch the cozystack.cozystack-platform Package CR).

Prerequisites

A running Cozystack cluster on version ≥ 1.5 (the customizer package landed in 1.5).
kubectl configured against the cluster, in the cozy-system namespace.
A git repo you own that the cluster’s Flux can reach over HTTPS (or SSH — see the Flux GitRepository secret docs for transport options). The repo doesn’t need to exist with content yet — an empty main branch is fine for the first reconcile.
Credentials with read access to that repo. For GitHub HTTPS that’s a fine-grained Personal Access Token with Contents: Read scope on the repo.

Step 1 — Create the git auth Secret

The customizer chart does not generate the git credentials Secret. You create it in cozy-system before enabling the package, so the platform never owns admin credentials.

Repo Layout and Worked Examples

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

This page covers what to put inside the customizer repo once the loop is wired up (see Setup if you haven’t enabled the package yet).

Recommended layout

cozystack-customizer/
 README.md
 clusters/
 prod/
 kustomization.yaml
 platform.yaml # patch for cozystack.cozystack-platform
 packages/
 metallb.yaml # patch — spec.components.metallb.values
 ingress-nginx.yaml
 sources/
 myorg-charts.yaml # extra OCIRepository
 packagesources/
 myorg-internal-portal.yaml # extra PackageSource using myorg-charts
 keycloak/
 realm-cozy.yaml
 apps/ # admin-owned HelmReleases
 ns-platform-tools.yaml
 my-monitoring-stack.yaml
 rbac/
 readonly-engineers.yaml
 networkpolicies/
 default-deny.yaml

The corresponding entry-point clusters/prod/kustomization.yaml:

Field Ownership, RBAC, Limitations

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

The customizer Kustomization applies its manifests via Server-Side Apply through a dedicated ServiceAccount with a curated ClusterRole. This page documents what’s granted, what isn’t, and which fields on Package CRs the customizer is supposed to write.

RBAC granted to `cozystack-customizer`

Cluster-scoped:

Resource	Verbs	Notes
`packages.cozystack.io`	get, list, watch, patch, update	No `delete` — disable a Package by adding it to `bundles.disabledPackages` on `cozystack.cozystack-platform` instead.
`packagesources.cozystack.io`	full	Customizer authors its own PackageSources.
`helmreleases.helm.toolkit.fluxcd.io` (cluster-wide)	get, list, watch	Read-only — chart-managed HelmReleases are off-limits to the customizer.
`keycloakrealmimports`, `keycloaks`, `keycloakusers` (`k8s.keycloak.org`)	full	Declarative Keycloak realm management.
`*.source.toolkit.fluxcd.io`	full	Additional `GitRepository` / `OCIRepository` / `HelmRepository` / `Bucket` sources.

Namespace-scoped (inside customizer.rbac.ownedNamespaces, default cozy-customizer):

Customizer — Declarative Cluster Customizations on Cozystack

Setup Guide

Prerequisites

Step 1 — Create the git auth Secret

Repo Layout and Worked Examples

Recommended layout

Field Ownership, RBAC, Limitations

RBAC granted to cozystack-customizer

RBAC granted to `cozystack-customizer`