mirror of
https://github.com/outbackdingo/cozystack.git
synced 2026-01-28 02:18:36 +00:00
116 lines
4.7 KiB
Markdown
116 lines
4.7 KiB
Markdown
# Cozystack Project Overview
|
|
|
|
This document provides detailed information about Cozystack project structure and conventions for AI agents.
|
|
|
|
## About Cozystack
|
|
|
|
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 modules, singleton charts which are used as dependencies
|
|
├── 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
|
|
│ ├── agents/ # AI agent instructions
|
|
│ └── 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
|
|
- Prefer **kubebuilder** for API definitions and controllers
|
|
- Add proper error handling and structured logging
|
|
|
|
### Git Commits
|
|
- Use format: `[component] Description`
|
|
- Always use `--signoff` flag
|
|
- Reference PR numbers when available
|
|
- Keep commits atomic and focused
|
|
- Follow conventional commit format for changelogs
|
|
|
|
### Documentation
|
|
|
|
Documentation is organized as follows:
|
|
- `docs/` - General documentation
|
|
- `docs/agents/` - Instructions for AI agents
|
|
- `docs/changelogs/` - Release changelogs
|
|
- Main website: https://github.com/cozystack/website
|
|
|
|
## 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 `_out`
|
|
- Do not commit test artifacts or temporary files
|
|
|
|
### Git Operations
|
|
- Do not force push to main/master
|
|
- Do not update git config
|
|
- Do not perform destructive operations without explicit request
|
|
|
|
### Core Components
|
|
- Do not modify `packages/core/platform/` without understanding migration impact
|
|
|