Cozystack Package Configuration (v1.x)

Configuration reference for Cozystack v1.x using Package-based architecture

This page explains the Package-based configuration system introduced in Cozystack v1.x and provides a complete reference for configuring your Cozystack installation.

Overview

Cozystack v1.x introduces a unified Package-based architecture managed by cozystack-operator. Instead of multiple ConfigMaps for different aspects of configuration, v1.x uses a single Package resource that defines all platform settings.

Key Changes from v0.x

v0.x Approachv1.x Approach
ConfigMap cozystack in cozy-systemPackage cozystack.cozystack-platform in cozy-system
Bundle names: paas-full, paas-hostedBundle variants: isp-full, isp-hosted, distro-full
Separate ConfigMaps for branding/schedulingUnified Package with all configuration
Multiple values-<component> entriesNested components.platform.values structure

Minimal Configuration Example

The simplest Package configuration for a new Cozystack installation:

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

Replace example.org with your actual domain and adjust network CIDRs if needed.

Full Configuration Example

Complete Package configuration showing all available options:

apiVersion: cozystack.io/v1alpha1
kind: Package
metadata:
  name: cozystack.cozystack-platform
  namespace: cozy-system
spec:
  variant: isp-full
  components:
    platform:
      values:
        bundles:
          system:
            enabled: true
            variant: "isp-full"
          iaas:
            enabled: true
          paas:
            enabled: true
          naas:
            enabled: true
          disabledPackages: []
          enabledPackages: []

        networking:
          clusterDomain: "cozy.local"
          podCIDR: "10.244.0.0/16"
          podGateway: "10.244.0.1"
          serviceCIDR: "10.96.0.0/16"
          joinCIDR: "100.64.0.0/16"
          kubeovn:
            MASTER_NODES: ""

        publishing:
          host: "example.org"
          ingressName: tenant-root
          exposedServices:
            - api
            - dashboard
            - vm-exportproxy
            - cdi-uploadproxy
          apiServerEndpoint: "https://api.example.org:6443"
          externalIPs: []
          certificates:
            issuerType: http01  # or "cloudflare"

        authentication:
          oidc:
            enabled: false
            keycloakExtraRedirectUri: ""

        scheduling:
          globalAppTopologySpreadConstraints: ""

        branding: {}

        registries: {}

        resources:
          cpuAllocationRatio: 10
          memoryAllocationRatio: 1
          ephemeralStorageAllocationRatio: 40

Configuration Reference

Package Variants

The spec.variant field determines which bundle of components to install:

VariantDescriptionUse Case
isp-fullFull platform with all system componentsProduction ISP/hosting deployments
isp-full-genericFull platform with generic settingsTesting and development
isp-hostedHosted variant without system componentsMulti-tenant hosted environments
distro-fullDistribution variantCustom distributions

bundles

Controls which functional bundles are enabled:

FieldTypeDefaultDescription
system.enabledbooleantrueEnable system bundle
system.variantstringisp-fullSystem bundle variant
iaas.enabledbooleantrueEnable IaaS bundle (virtualization, storage)
paas.enabledbooleantrueEnable PaaS bundle (databases, message queues)
naas.enabledbooleantrueEnable NaaS bundle (networking services)
disabledPackagesarray[]List of packages to disable
enabledPackagesarray[]List of additional packages to enable

networking

Defines cluster networking configuration:

FieldTypeDefaultDescription
clusterDomainstringcozy.localKubernetes cluster DNS domain
podCIDRstring10.244.0.0/16Pod network CIDR
podGatewaystring10.244.0.1Pod network gateway IP
serviceCIDRstring10.96.0.0/16Service network CIDR
joinCIDRstring100.64.0.0/16Join network CIDR for tenant isolation
kubeovn.MASTER_NODESstring""KubeOVN master nodes (auto-detected if empty)

publishing

Controls service exposure and certificates:

FieldTypeDefaultDescription
hoststringexample.orgRoot domain for all Cozystack services
ingressNamestringtenant-rootIngress class name
exposedServicesarray[api, dashboard, vm-exportproxy, cdi-uploadproxy]Services to expose via ingress
apiServerEndpointstring""Kubernetes API endpoint for kubeconfig generation
externalIPsarray[]External IPs for service exposure (when not using MetalLB)
certificates.issuerTypestringhttp01Certificate issuer: http01 or cloudflare

Available exposed services:

  • api - Kubernetes API proxy
  • dashboard - Cozystack web UI
  • keycloak - OIDC authentication
  • grafana - Monitoring dashboards
  • vm-exportproxy - VM export service
  • cdi-uploadproxy - VM image upload service

authentication

OIDC and authentication settings:

FieldTypeDefaultDescription
oidc.enabledbooleanfalseEnable Keycloak OIDC authentication
oidc.keycloakExtraRedirectUristring""Additional redirect URI for Keycloak

scheduling

Cluster scheduling configuration:

FieldTypeDefaultDescription
globalAppTopologySpreadConstraintsstring""Global topology spread constraints for applications

resources

Resource allocation and overcommit ratios:

FieldTypeDefaultDescription
cpuAllocationRationumber10CPU overcommit ratio (10 = 10:1)
memoryAllocationRationumber1Memory overcommit ratio (1 = 1:1, no overcommit)
ephemeralStorageAllocationRationumber40Ephemeral storage overcommit ratio

Runtime Configuration Changes

Update configuration without reinstalling Cozystack by patching the Package resource.

Enable OIDC Authentication

kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p '{
  "spec": {
    "components": {
      "platform": {
        "values": {
          "authentication": {
            "oidc": {
              "enabled": true
            }
          }
        }
      }
    }
  }
}'

Expose Additional Services

Add Keycloak to exposed services:

kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p '{
  "spec": {
    "components": {
      "platform": {
        "values": {
          "publishing": {
            "exposedServices": ["api", "dashboard", "keycloak"]
          }
        }
      }
    }
  }
}'

Change Resource Allocation Ratios

Adjust CPU overcommit ratio:

kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p '{
  "spec": {
    "components": {
      "platform": {
        "values": {
          "resources": {
            "cpuAllocationRatio": 5
          }
        }
      }
    }
  }
}'

Disable Specific Packages

Disable a package (e.g., clickhouse):

kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p '{
  "spec": {
    "components": {
      "platform": {
        "values": {
          "bundles": {
            "disabledPackages": ["clickhouse"]
          }
        }
      }
    }
  }
}'

Viewing Current Configuration

Get the current Package configuration:

kubectl get package cozystack.cozystack-platform -n cozy-system -o yaml

View specific configuration values:

kubectl get package cozystack.cozystack-platform -n cozy-system \
  -o jsonpath='{.spec.components.platform.values}' | yq

Migration from v0.x

To migrate from v0.x ConfigMap to v1.x Package:

  1. Export existing configuration:

    kubectl get cm cozystack -n cozy-system -o yaml > cozystack-v0-config.yaml

  2. Create equivalent Package resource using the mapping table below

  3. Apply the new Package:

    kubectl apply -f cozystack-v1-package.yaml

Configuration Mapping

v0.x ConfigMap Keyv1.x Package Path
bundle-name: paas-fullspec.variant: isp-full
root-hostspec.components.platform.values.publishing.host
api-server-endpointspec.components.platform.values.publishing.apiServerEndpoint
expose-servicesspec.components.platform.values.publishing.exposedServices
ipv4-pod-cidrspec.components.platform.values.networking.podCIDR
ipv4-pod-gatewayspec.components.platform.values.networking.podGateway
ipv4-svc-cidrspec.components.platform.values.networking.serviceCIDR
ipv4-join-cidrspec.components.platform.values.networking.joinCIDR
bundle-enablespec.components.platform.values.bundles.enabledPackages
bundle-disablespec.components.platform.values.bundles.disabledPackages

Troubleshooting

Package Not Reconciling

Check Package status:

kubectl describe package cozystack.cozystack-platform -n cozy-system

Check operator logs:

kubectl logs -n cozy-system deploy/cozystack-operator -f

Configuration Not Applied

Verify Package is being watched:

kubectl get package -A

Check HelmRelease status:

kubectl get hr -A | grep -v True

Invalid Configuration

Validate Package syntax:

kubectl apply --dry-run=server -f cozystack-package.yaml
Last modified 2026-02-05: docs: add Cozystack v1.x Package-based configuration (1b41d32)