Skip to content

docs: redesign README with hero graphic and zh-CN version #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rcyw merged 2 commits into from
Aug 13, 2026
Merged

docs: redesign README with hero graphic and zh-CN version #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0b67fb
fix: support OpenTelemetry log 0.21
rcyw Aug 10, 2026
f6b281f
docs: redesign README with hero graphic and zh-CN version
rcyw Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 17 additions & 21 deletions .x/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,19 @@
# Development Conventions

- Prefer putting non-trivial shell logic in `scripts/`; keep `Makefile`
targets as thin wrappers.
- Keep behavior stable unless the user explicitly asks for behavior changes.
- Preserve the CLI surface and daemon API paths unless a migration is planned.
- Do not put environment-specific registry addresses in chart templates.
- Be careful with dirty worktrees. Do not revert user changes unless asked.
- Prefer existing package boundaries and helper APIs over introducing new
abstractions.
- Keep `kova` a CGO-free, cross-platform Kubernetes client. Linux-only build
execution, LMDB state, and daemon APIs belong to `kovad` and its runtime
image.
- Keep official upstream sources as Dockerfile defaults. Generic proxy,
download-base, base-image, and `GOPROXY` overrides may be exposed for
consuming environments; provider-specific values belong in those
environments rather than this repository.
- Keep examples aligned with the documented local registry addresses:
`localhost:5002` on the host and `host.docker.internal:5002` from Pods or
build outputs.
- Wrap English Markdown prose at about 80 columns. Keep link labels concise and
descriptive; do not force-wrap code blocks, tables, URLs, or other structures
whose meaning or readability depends on staying intact.
Stability rules (behavior, CLI surface, worktrees) live in [AGENTS.md](../AGENTS.md); this file covers only day-to-day conventions.

## Code

- Non-trivial shell logic lives in `scripts/`; `Makefile` targets stay thin wrappers.
- Prefer existing package boundaries and helper APIs over new abstractions.
- `kova` stays a CGO-free, cross-platform client. Linux build execution, LMDB state, and daemon APIs belong to `kovad` and its runtime image.

## Charts and Examples

- Chart templates contain no environment-specific registry addresses. Dockerfile defaults use official upstream sources; generic proxy, download-base, base-image, and `GOPROXY` overrides belong to consuming environments.
- Examples use the documented local registry addresses: `localhost:5002` on the host, `host.docker.internal:5002` from Pods and build outputs.

## Markdown

- English prose: one sentence per line. Chinese prose: one paragraph per line with fullwidth punctuation; never wrap CJK text at a fixed column.
- Link syntax, code blocks, tables, and URLs stay intact on one line.
129 changes: 52 additions & 77 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,34 @@
# Kova
<p align="center">
<img src="./assets/readme/hero.svg" width="100%" alt="Kova — a Kubernetes-native image build service: the CLI submits jobs to the controller's KovaBuild API, a per-job runner drives shared rootless BuildKit workers, and images are pushed to an OCI registry and preheated over Dragonfly P2P.">
</p>

[![CI](https://github.com/cofy-x/kova/actions/workflows/ci.yml/badge.svg)](https://github.com/cofy-x/kova/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
<p align="center">
<a href="https://github.com/cofy-x/kova/actions/workflows/ci.yml"><img src="https://github.com/cofy-x/kova/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache-2.0"></a>
</p>

Kova is a Kubernetes-native, cloud-provider-neutral image build service powered
by BuildKit. It builds batches of Dockerfile contexts into OCI or Nydus images,
pushes them to OCI registries, and can preheat successful results through a
Dragonfly P2P cluster.
<p align="center">
English | <a href="README.zh-CN.md">中文</a>
</p>

## Install the CLI
Kova turns batches of Dockerfile contexts into OCI or Nydus images on your own Kubernetes cluster.
Powered by BuildKit, it pushes results to any OCI registry and can preheat them across a Dragonfly P2P cluster — without tying you to a cloud provider.

Download a provenance-attested archive for Linux, macOS, or Windows from the
[GitHub releases](https://github.com/cofy-x/kova/releases), verify it with the
published `checksums.txt`, and place `kova` on `PATH`. Linux and macOS builds
are available for `amd64` and `arm64`; Windows builds are available as `.zip`
archives for both architectures.
## Quick start

Go users can install the latest tagged client directly:
You need a Kubernetes cluster, Helm with OCI support, and `kubectl`.
Choose a tag from [GitHub releases](https://github.com/cofy-x/kova/releases) so the chart, CLI, and runtime images stay aligned.
Provenance-attested CLI archives for Linux, macOS, and Windows are published there as well.

```bash
go install github.com/cofy-x/kova/cmd/kova@latest
kova version
```

Use an explicit release tag instead of `@latest` when the installed version
must be reproducible. Contributors can install the current checkout with:
Install the CLI:

```bash
make install
go install github.com/cofy-x/kova/cmd/kova@latest
kova version
```

The client is CGO-free and runs on the workstation. Linux runtime images are
split into controller, runner, and rootless BuildKit worker roles.

## Install Kova

Choose a tag from [GitHub releases](https://github.com/cofy-x/kova/releases),
then install that exact OCI Helm chart without cloning the repository. The
quick-start profile uses a generated static token and filesystem PVC; shared
environments should use TokenReview and S3-compatible storage instead:
Install the service.
The quick-start profile uses a generated static token and a filesystem PVC; shared environments should use TokenReview and S3-compatible storage instead:

```bash
export KOVA_VERSION=vX.Y.Z
Expand Down Expand Up @@ -67,72 +56,58 @@ kubectl -n kova create rolebinding kova-quickstart \
--user=kova:quickstart
```

Applying the release CRD before every Helm upgrade is required because Helm
does not upgrade files from a chart's `crds/` directory.
Applying the release CRD before every Helm upgrade is required because Helm does not upgrade files from a chart's `crds/` directory.

The chart selects matching controller, runner, and worker images automatically.
Continue with the [installation and first-build guide](docs/quickstart.md),
create a Service context, and verify it before the first job:
Run your first build:

```bash
kubectl -n kova port-forward service/kova-service 8080:8080 &

kova ctx set --mode service --service-url http://127.0.0.1:8080 --use quickstart
kova doctor
kova job submit ./image --target registry.example.com/team/image:dev
kova job list
kova job wait <job-id>
kova job results <job-id>
```

The [Service security and CLI guide](docs/service.md) covers identity, RBAC,
contexts, artifact storage, and job operations. Direct runner commands remain
available for local development and low-level debugging.
Registry credentials, Nydus output, and batch archives are covered in the [installation and first-build guide](docs/quickstart.md).

## Why Kova

- **Batch in, images out** — one job builds many Dockerfile targets into OCI or Nydus images; typed per-target results and logs persist in the artifact store after the short-lived runner Pod is gone.
- **A real job model** — the `KovaBuild` CRD has an immutable spec, SHA-256-pinned source artifacts, and caller-scoped idempotency keys.
- **Fair, work-conserving scheduling** — queued jobs interleave by authenticated requester; admission reserves actual BuildKit worker slots.
- **Isolated execution** — one runner Pod per job drives shared upstream rootless BuildKit workers; controller and runner run as non-root with all capabilities dropped.
- **Kubernetes-native auth** — TokenReview and SubjectAccessReview by default; submitters never touch Pods, Secrets, or other users' jobs.
- **Cloud-provider-neutral** — registry, artifact, and API credentials are external Secret inputs. The chart creates no clusters, cloud accounts, or registries.
- **Observable** — stable OpenTelemetry metrics for queue delay, job duration, and capacity waits.

## Documentation

- [Documentation map](docs/README.md): choose the guide for a task.
- [Installation and first build](docs/quickstart.md): install the public OCI
Helm chart and matching CLI, then verify a build.
- [CLI workflow](docs/cli-workflow.md): contexts, prepare,
direct runner builds, logs, export, and cleanup.
- [Service job workflow](docs/service.md): authenticated shared builds,
authorization, storage, and native CLI operations.
- [Runtime design](docs/architecture.md): roles, topology, build/export,
preheat, and scaling flows.
- [Kubernetes deployment](docs/deployment/kubernetes.md): Helm installation,
registry credentials, worker sizing, and production configuration.
- [Validation matrix](docs/testing.md): static checks, E2E targets, and runtime
smoke expectations.
- [Release process](docs/releases.md): CLI archives, OCI Helm charts, runtime
images, SBOMs, provenance, and version tags.
- [Examples](examples/README.md): build input examples and runtime smoke
service details.

## Develop Kova

The repository requires the Go version declared in `go.mod`, Docker, kind,
Helm, kubectl, curl, zip, and LMDB development headers. Run the fast checks
with:
- [Installation and first build](docs/quickstart.md): OCI chart, matching CLI, and a verified build.
- [Service job workflow](docs/service.md): identity, RBAC, contexts, artifact storage, and job operations.
- [CLI workflow](docs/cli-workflow.md): direct runner builds for development and low-level debugging.
- [Runtime design](docs/architecture.md): roles, topology, build/export, preheat, and scaling flows.
- [Kubernetes deployment](docs/deployment/kubernetes.md): registry credentials, worker sizing, and production configuration.
- [Release process](docs/releases.md): CLI archives, OCI charts, runtime images, SBOMs, and provenance.
- [Examples](examples/README.md): build input examples and runtime smoke services.

## Develop

The repository requires the Go version declared in `go.mod`, Docker, kind, Helm, kubectl, curl, zip, and LMDB development headers.

```bash
make test
make lint-scripts
make helm-template
make e2e-helm-quickstart # released-chart install path on kind
```

Run the released-chart installation path locally with:

```bash
make e2e-helm-quickstart
```

Validate an already published release with:

```bash
make e2e-release KOVA_VERSION=vX.Y.Z
```
Use the [validation matrix](docs/testing.md) to choose broader E2E coverage.
Contributions are welcome; the [contribution workflow](CONTRIBUTING.md) covers the full setup and pull request process.
Report vulnerabilities through the private process in the [security policy](SECURITY.md).

Use the [validation guide](docs/testing.md) to choose broader E2E coverage.
Contributions are welcome; the [contribution workflow](CONTRIBUTING.md) covers
the full setup and pull request process. Report vulnerabilities through the
private process in the [security policy](SECURITY.md).
## License

Kova is licensed under the [Apache License 2.0](LICENSE).
107 changes: 107 additions & 0 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
<p align="center">
<img src="./assets/readme/hero.svg" width="100%" alt="Kova — Kubernetes 原生镜像构建服务：CLI 将任务提交给 controller 的 KovaBuild API，每个任务由独立的 runner 驱动共享的 rootless BuildKit worker，镜像推送到 OCI registry 并通过 Dragonfly P2P 预热。">
</p>

<p align="center">
<a href="https://github.com/cofy-x/kova/actions/workflows/ci.yml"><img src="https://github.com/cofy-x/kova/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache-2.0"></a>
</p>

<p align="center">
<a href="README.md">English</a> | 中文
</p>

Kova 在你自己的 Kubernetes 集群上，把成批的 Dockerfile context 构建成 OCI 或 Nydus 镜像。它由 BuildKit 驱动，将产物推送到任意 OCI registry，并可通过 Dragonfly P2P 集群预热，且不绑定任何云厂商。

## 快速开始

你需要一个 Kubernetes 集群、支持 OCI 的 Helm，以及 `kubectl`。从 [GitHub releases](https://github.com/cofy-x/kova/releases) 选择一个 tag，保证 chart、CLI 和运行时镜像版本对齐。Linux、macOS 和 Windows 的 CLI 归档（附 provenance 证明）也发布在同一页面。

安装 CLI：

```bash
go install github.com/cofy-x/kova/cmd/kova@latest
kova version
```

安装服务。快速开始配置使用生成的静态 token 和 filesystem PVC；共享环境应改用 TokenReview 和 S3 兼容存储：

```bash
export KOVA_VERSION=vX.Y.Z
export KOVA_SERVICE_TOKEN=$(openssl rand -hex 32)

kubectl create namespace kova --dry-run=client -o yaml | kubectl apply -f -
kubectl -n kova create secret generic kova-service-auth \
--from-literal=token="${KOVA_SERVICE_TOKEN}"

helm show crds oci://ghcr.io/cofy-x/charts/kova \
--version "${KOVA_VERSION#v}" | kubectl apply -f -
helm upgrade --install kova oci://ghcr.io/cofy-x/charts/kova \
--version "${KOVA_VERSION#v}" \
--namespace kova \
--create-namespace \
--set serviceDaemon.enabled=true \
--set serviceDaemon.authentication.mode=static \
--set serviceDaemon.authentication.staticPrincipal=kova:quickstart \
--set serviceDaemon.authentication.staticTokenSecret.name=kova-service-auth \
--set artifactStore.filesystem.pvc.create=true \
--wait

kubectl -n kova create rolebinding kova-quickstart \
--role=kova-service-submitter \
--user=kova:quickstart
```

每次 Helm 升级前都必须先 apply 对应 release 的 CRD，因为 Helm 不会升级 chart `crds/` 目录下的文件。

运行第一个构建：

```bash
kubectl -n kova port-forward service/kova-service 8080:8080 &

kova ctx set --mode service --service-url http://127.0.0.1:8080 --use quickstart
kova doctor
kova job submit ./image --target registry.example.com/team/image:dev
kova job wait <job-id>
kova job results <job-id>
```

registry 凭证、Nydus 输出和批量归档见[安装与首次构建指南](docs/quickstart.md)。

## 为什么选择 Kova

- **批量输入，镜像产出** — 一个任务可构建多个 Dockerfile target，输出 OCI 或 Nydus 镜像；每个 target 的类型化结果和日志在 runner Pod 消失后仍保留在 artifact store 中。
- **真实的任务模型** — `KovaBuild` CRD 拥有不可变 spec、以 SHA-256 钉住的源 artifact，以及按调用方隔离的幂等键。
- **公平且不浪费算力的调度** — 排队任务按认证身份交错；准入控制为任务预留真实的 BuildKit worker 槽位。
- **隔离执行** — 每个任务一个 runner Pod，驱动共享的上游 rootless BuildKit worker；controller 和 runner 以非 root 运行并丢弃全部 capabilities。
- **Kubernetes 原生认证** — 默认使用 TokenReview 和 SubjectAccessReview；提交者无法接触 Pod、Secret 或其他用户的任务。
- **云厂商中立** — registry、artifact 和 API 凭证都是外部 Secret 输入；chart 不创建集群、云账号或 registry。
- **可观测** — 稳定的 OpenTelemetry 指标覆盖排队延迟、任务时长和容量等待。

## 文档

- [文档地图](docs/README.md)：按任务选择指南。
- [安装与首次构建](docs/quickstart.md)：OCI chart、匹配版本的 CLI 和一次验证过的构建。
- [Service 任务工作流](docs/service.md)：身份、RBAC、context、artifact 存储和任务操作。
- [CLI 工作流](docs/cli-workflow.md)：面向开发和底层调试的直连 runner 构建。
- [运行时设计](docs/architecture.md)：角色、拓扑、构建/导出、预热和扩缩容流程。
- [Kubernetes 部署](docs/deployment/kubernetes.md)：registry 凭证、worker 规格和生产配置。
- [发布流程](docs/releases.md)：CLI 归档、OCI chart、运行时镜像、SBOM 和 provenance。
- [示例](examples/README.md)：构建输入示例和运行时冒烟服务。

## 参与开发

仓库要求 `go.mod` 声明的 Go 版本，以及 Docker、kind、Helm、kubectl、curl、zip 和 LMDB 开发头文件。

```bash
make test
make lint-scripts
make helm-template
make e2e-helm-quickstart # 在 kind 上验证已发布 chart 的安装路径
```

更大范围的 E2E 覆盖见[验证矩阵](docs/testing.md)。欢迎贡献，完整的环境搭建和 PR 流程见[贡献指南](CONTRIBUTING.md)。漏洞请通过[安全策略](SECURITY.md)中的私有流程报告。

## 许可证

Kova 基于 [Apache License 2.0](LICENSE) 发布。
Loading