|
|
|
|
@@ -0,0 +1,449 @@
|
|
|
|
|
# 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:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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.)
|
|
|
|
|
|
|
|
|
|
1. Create directory: `packages/system/<component-name>/`
|
|
|
|
|
2. Create `Chart.yaml` with component metadata
|
|
|
|
|
3. Add upstream chart to `charts/` directory
|
|
|
|
|
4. Create `values.yaml` with overrides
|
|
|
|
|
5. Generate `values.schema.json` using `readme-generator`
|
|
|
|
|
6. Add `Makefile` using `scripts/package.mk`
|
|
|
|
|
7. Create `images/` directory if custom images needed
|
|
|
|
|
8. Add to bundle configuration in `packages/core/platform/`
|
|
|
|
|
9. Write tests in `hack/e2e-apps/`
|
|
|
|
|
10. Update documentation
|
|
|
|
|
|
|
|
|
|
### For User Applications (apps catalog)
|
|
|
|
|
|
|
|
|
|
1. Create directory: `packages/apps/<app-name>/`
|
|
|
|
|
2. Define minimal user-facing parameters in `values.schema.json`
|
|
|
|
|
3. Use Cozystack API for high-level resources
|
|
|
|
|
4. Add `templates/dashboard-resourcemap.yaml` for UI display
|
|
|
|
|
5. Keep business logic in system operators, not in app charts
|
|
|
|
|
6. Test deployment through dashboard
|
|
|
|
|
7. Document usage in README
|
|
|
|
|
|
|
|
|
|
### For Extra/Tenant Applications
|
|
|
|
|
|
|
|
|
|
1. Create in `packages/extra/<app-name>/`
|
|
|
|
|
2. Follow same structure as apps
|
|
|
|
|
3. Not shown in catalog
|
|
|
|
|
4. Installable only as tenant component
|
|
|
|
|
5. 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
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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):
|
|
|
|
|
|
|
|
|
|
1. **Activation**: Automatic when user mentions "changelog" or works in `docs/changelogs/`
|
|
|
|
|
2. **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
|
|
|
|
|
3. **Process**:
|
|
|
|
|
- Extract version and range
|
|
|
|
|
- Run git log between versions
|
|
|
|
|
- Categorize by BMAD framework
|
|
|
|
|
- Generate structured output
|
|
|
|
|
- Validate against checklist
|
|
|
|
|
4. **Templates**: Use `patch-template.md` or `template.md`
|
|
|
|
|
|
|
|
|
|
### Building Cozystack Container
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# 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
|
|
|
|
|
|
|
|
|
|
- [Cozystack Documentation](https://cozystack.io/docs/)
|
|
|
|
|
- [Developer Guide](https://cozystack.io/docs/development/)
|
|
|
|
|
- [GitHub Repository](https://github.com/cozystack/cozystack)
|
|
|
|
|
- [Helm Documentation](https://helm.sh/docs/)
|
|
|
|
|
- [FluxCD Documentation](https://fluxcd.io/flux/)
|
|
|
|
|
- [cozypkg Tool](https://github.com/cozystack/cozypkg)
|
|
|
|
|
- [Kubernetes Operator Patterns](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
|
|
|
|
|
- [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime)
|
|
|
|
|
|
|
|
|
|
## Community
|
|
|
|
|
|
|
|
|
|
- [Telegram](https://t.me/cozystack)
|
|
|
|
|
- [Slack](https://kubernetes.slack.com/archives/C06L3CPRVN1)
|
|
|
|
|
- [Community Calendar](https://calendar.google.com/calendar?cid=ZTQzZDIxZTVjOWI0NWE5NWYyOGM1ZDY0OWMyY2IxZTFmNDMzZTJlNjUzYjU2ZGJiZGE3NGNhMzA2ZjBkMGY2OEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Machine-Readable Summary
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
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]
|
|
|
|
|
```
|
|
|
|
|
|
