Signed-off-by: Andrei Kvapil <kvapss@gmail.com>

2025-11-08 00:18:44 +01:00

14 KiB

Raw Permalink Blame History

AGENTS.md

This file provides structured guidance for AI coding assistants and agents working with the Cozystack project.

Project Overview

Cozystack is an open-source Kubernetes-based platform and framework for building cloud infrastructure. It provides:

Managed Services: Databases, VMs, Kubernetes clusters, object storage, and more
Multi-tenancy: Full isolation and self-service for tenants
GitOps-driven: FluxCD-based continuous delivery
Modular Architecture: Extensible with custom packages and services
Developer Experience: Simplified local development with cozypkg tool

The platform exposes infrastructure services via the Kubernetes API with ready-made configs, built-in monitoring, and alerts.

Code Layout

.
├── packages/               # Main directory for cozystack packages
│   ├── core/              # Core platform logic charts (installer, platform)
│   ├── system/            # System charts (CSI, CNI, operators, etc.)
│   ├── apps/              # User-facing charts shown in dashboard catalog
│   └── extra/             # Tenant-specific applications
├── dashboards/            # Grafana dashboards for monitoring
├── hack/                  # Helper scripts for local development
│   └── e2e-apps/         # End-to-end application tests
├── scripts/               # Scripts used by cozystack container
│   └── migrations/       # Version migration scripts
├── docs/                  # Documentation
│   └── changelogs/       # Release changelogs
├── cmd/                   # Go command entry points
│   ├── cozystack-api/
│   ├── cozystack-controller/
│   └── cozystack-assets-server/
├── internal/              # Internal Go packages
│   ├── controller/       # Controller implementations
│   └── lineagecontrollerwebhook/
├── pkg/                   # Public Go packages
│   ├── apis/
│   ├── apiserver/
│   └── registry/
└── api/                   # Kubernetes API definitions (CRDs)
    └── v1alpha1/

Package Structure

Every package is a Helm chart following the umbrella chart pattern:

packages/<category>/<package-name>/
├── Chart.yaml                           # Chart definition and parameter docs
├── Makefile                             # Development workflow targets
├── charts/                              # Vendored upstream charts
├── images/                              # Dockerfiles and image build context
├── patches/                             # Optional upstream chart patches
├── templates/                           # Additional manifests
├── templates/dashboard-resourcemap.yaml # Dashboard resource mapping
├── values.yaml                          # Override values for upstream
└── values.schema.json                   # JSON schema for validation and UI

Conventions

Helm Charts

Follow umbrella chart pattern for system components
Include upstream charts in charts/ directory (vendored, not referenced)
Override configuration in root values.yaml
Use values.schema.json for input validation and dashboard UI rendering

Go Code

Follow standard Go conventions and idioms
Use controller-runtime patterns for Kubernetes controllers
Namespaces follow pattern: github.com/cozystack/cozystack/<path>
Add proper error handling and structured logging
Use declare(strict_types=1) equivalent (Go's type safety)

Git Commits

Use format: [component] Description
Reference PR numbers when available
Keep commits atomic and focused
Follow conventional commit format for changelogs

Documentation

Keep README files current
Document breaking changes clearly
Update relevant docs when making changes
Use clear, concise language with code examples

Development Workflow

Standard Make Targets

Every package includes a Makefile with these targets:

make update  # Update Helm chart and versions from upstream
make image   # Build Docker images used in the package
make show    # Show rendered Helm templates
make diff    # Diff Helm release against live cluster objects
make apply   # Apply Helm release to Kubernetes cluster

Using cozypkg

The cozypkg tool wraps Helm and Flux for local development:

cozypkg show       # Render manifests (helm template)
cozypkg diff       # Show live vs desired manifests
cozypkg apply      # Upgrade/install HelmRelease and sync
cozypkg suspend    # Suspend Flux reconciliation
cozypkg resume     # Resume Flux reconciliation
cozypkg get        # Get HelmRelease resources
cozypkg list       # List all HelmReleases
cozypkg delete     # Uninstall release
cozypkg reconcile  # Trigger Flux reconciliation

Example: Updating a Component

cd packages/system/cilium    # Navigate to package
make update                  # Pull latest upstream
make image                   # Build images
git diff .                   # Review manifest changes
make diff                    # Compare with cluster
make apply                   # Deploy to cluster
kubectl get pod -n cozy-cilium  # Verify deployment
git commit -m "[cilium] Update to vX.Y.Z"

Adding New Packages

For System Components (operators, CNI, CSI, etc.)

Create directory: packages/system/<component-name>/
Create Chart.yaml with component metadata
Add upstream chart to charts/ directory
Create values.yaml with overrides
Generate values.schema.json using readme-generator
Add Makefile using scripts/package.mk
Create images/ directory if custom images needed
Add to bundle configuration in packages/core/platform/
Write tests in hack/e2e-apps/
Update documentation

For User Applications (apps catalog)

Create directory: packages/apps/<app-name>/
Define minimal user-facing parameters in values.schema.json
Use Cozystack API for high-level resources
Add templates/dashboard-resourcemap.yaml for UI display
Keep business logic in system operators, not in app charts
Test deployment through dashboard
Document usage in README

For Extra/Tenant Applications

Create in packages/extra/<app-name>/
Follow same structure as apps
Not shown in catalog
Installable only as tenant component
One application type per tenant namespace

Tests and CI

Local Testing

Unit tests: Go tests in *_test.go files
Integration tests: BATS scripts in hack/e2e-apps/
E2E tests: Full platform tests via hack/e2e.sh

Running E2E Tests

cd packages/core/testing
make apply    # Create testing sandbox in cluster
make test     # Run end-to-end tests
make delete   # Remove testing sandbox

# Or locally with QEMU VMs:
./hack/e2e.sh

CI Pipeline

Automated tests run on every PR
Image builds for changed packages
Manifest diff generation
E2E tests on full platform
Release packaging and publishing

Testing Environment Commands

make exec     # Interactive shell in sandbox
make login    # Download kubeconfig (requires mirrord)
make proxy    # Enable SOCKS5 proxy (requires mirrord + gost)

Things Agents Should Not Do

Never Edit These

Do not modify files in /vendor/ (Go dependencies)
Do not edit generated files: zz_generated.*.go
Do not change go.mod/go.sum manually (use go get)
Do not edit upstream charts in packages/*/charts/ directly (use patches)
Do not modify image digests in values.yaml (generated by build)

Version Control

Do not commit built artifacts from packages/*/build/
Do not commit generated dashboards
Do not commit test artifacts or temporary files

Git Operations

Do not force push to main/master
Do not skip hooks (--no-verify, --no-gpg-sign)
Do not update git config
Do not perform destructive operations without explicit request

Changelogs

Do not manually edit docs/changelogs/*.md outside of changelog workflow
Follow changelog agent rules in .cursor/changelog-agent.md
Use structured format from templates

Core Components

Do not modify packages/core/installer/installer.sh without understanding migration impact
Do not change packages/core/platform/ logic without testing full bootstrap
Do not alter FluxCD configurations without considering reconciliation loops

Special Workflows

Changelog Generation

When working with changelogs (see .cursor/changelog-agent.md for details):

Activation: Automatic when user mentions "changelog" or works in docs/changelogs/
Commands:
- "Create changelog for vX.Y.Z" → Generate from git history
- "Review changelog vX.Y.Z" → Analyze quality
- "Update changelog with PR #XXXX" → Add entry
Process:
- Extract version and range
- Run git log between versions
- Categorize by BMAD framework
- Generate structured output
- Validate against checklist
Templates: Use patch-template.md or template.md

Building Cozystack Container

cd packages/core/installer
make image-cozystack    # Build cozystack image
make apply              # Apply to cluster
kubectl get pod -n cozy-system
kubectl get hr -A       # Check HelmRelease objects

Building with Custom Registry

export REGISTRY=my-registry.example.com/cozystack
cd packages/system/component-name
make image
make apply

Buildx Configuration

Install and configure Docker buildx for multi-arch builds:

# Kubernetes driver (build in cluster)
docker buildx create \
  --bootstrap \
  --name=buildkit \
  --driver=kubernetes \
  --driver-opt=namespace=tenant-kvaps,replicas=2 \
  --platform=linux/amd64 \
  --platform=linux/arm64 \
  --use

# Or use local Docker (omit --driver* options)
docker buildx create --bootstrap --name=local --use

References

Community

Machine-Readable Summary

project: Cozystack
type: kubernetes-platform
description: Open-source platform for building cloud infrastructure
architecture: kubernetes-based, gitops-driven, multi-tenant

layout:
  packages/:
    core/: platform bootstrap and configuration
    system/: cluster-wide components (CSI, CNI, operators)
    apps/: user-facing applications (catalog)
    extra/: tenant-specific applications
  dashboards/: grafana monitoring dashboards
  hack/: development scripts and e2e tests
  scripts/: runtime scripts and migrations
  cmd/: go command entry points
  internal/: internal go packages
  pkg/: public go packages
  api/: kubernetes api definitions (CRDs)
  docs/: documentation and changelogs

package_structure:
  Chart.yaml: helm chart definition
  Makefile: development workflow targets
  charts/: vendored upstream charts
  images/: docker image sources
  patches/: upstream chart patches
  templates/: additional manifests
  values.yaml: configuration overrides
  values.schema.json: validation schema and UI hints

workflow:
  development_tool: cozypkg
  commands:
    - update: pull upstream charts
    - image: build docker images
    - show: render manifests
    - diff: compare with cluster
    - apply: deploy to cluster
  gitops_engine: FluxCD
  package_manager: Helm

conventions:
  helm:
    pattern: umbrella chart
    upstream: vendored in charts/
    overrides: root values.yaml
  go:
    style: standard go conventions
    framework: controller-runtime
    namespace: github.com/cozystack/cozystack
  git:
    commit_format: "[component] Description"
    reference_prs: true
    atomic_commits: true

testing:
  unit: go test
  integration: bats scripts (hack/e2e-apps/)
  e2e: hack/e2e.sh
  sandbox:
    location: packages/core/testing
    commands: [apply, test, delete, exec, login, proxy]

ci:
  triggers: every PR
  checks:
    - automated tests
    - image builds
    - manifest diffs
    - e2e tests
    - packaging

special_agents:
  changelog:
    activation:
      - files in docs/changelogs/
      - user mentions "changelog"
      - changelog-related requests
    config_file: .cursor/changelog-agent.md
    templates:
      - docs/changelogs/patch-template.md
      - docs/changelogs/template.md
    framework: BMAD categorization

do_not_edit:
  - vendor/
  - zz_generated.*.go
  - packages/*/charts/* (use patches)
  - go.mod manually
  - go.sum manually
  - image digests in values.yaml
  - built artifacts

tools:
  required:
    - kubectl
    - helm
    - docker buildx
    - make
    - go
  recommended:
    - cozypkg
    - mirrord
    - gost
    - readme-generator

core_components:
  bootstrap:
    - packages/core/installer (installer.sh, assets server)
    - packages/core/platform (flux config, reconciliation)
  api:
    - cmd/cozystack-api (api server)
    - cmd/cozystack-controller (main controller)
    - api/v1alpha1 (CRD definitions)
  delivery:
    - FluxCD Helm Controller
    - HelmRelease custom resources

bundle_system:
  definition: packages/core/platform/
  components_from: packages/system/
  user_applications: packages/apps/ + packages/extra/
  tenant_isolation: namespace-based
  one_app_type_per_tenant: true

image_management:
  location: packages/*/images/
  build: make image
  injection: automatic to values.yaml
  format: path + digest
  registry: configurable via REGISTRY env var

multi_arch:
  tool: docker buildx
  platforms: [linux/amd64, linux/arm64]
  driver_options: [kubernetes, docker]

14 KiB Raw Permalink Blame History