This repository is the single source of truth for all Krateo documentation. It powers docs.krateo.io via Docusaurus and is the only place where guides, images, architecture diagrams, and tutorials should live.
If you're looking for a quick install or API reference, individual repositories have minimal READMEs with a direct link to the relevant docs page. Everything else is here.
- Repository structure
- How versioning works
- Compatibility table
- Migrating a repository
- README template for individual repositories
- Writing and contributing docs
- Running docs locally
krateo-v2-docs/
├── docs/ # Current (next) documentation
│ ├── 10-overview.md
│ ├── 25-quickstart.md
│ ├── 85-krateo-autopilot.md
│ ├── 20-key-concepts/
│ │ ├── 10-kco/ # Krateo Composable Operations
│ │ │ ├── 10-core-provider.md
│ │ │ ├── 11-core-provider-cheatsheet.md
│ │ │ ├── 20-composition-dynamic-controller.md
│ │ │ └── 30-provider-runtime.md
│ │ ├── 20-kcp/ # Krateo Composable Portal
│ │ │ ├── 10-frontend.md
│ │ │ ├── 20-snowplow.md
│ │ │ ├── 21-snowplow-RESTAction.md
│ │ │ ├── 22-snowplow-endpoints.md
│ │ │ ├── 23-snowplow-widgets.md
│ │ │ ├── 40-authn.md
│ │ │ ├── 50-events-presenter.md
│ │ │ └── 60-resources-presenter.md
│ │ ├── 30-kcf/ # Krateo Composable FinOps
│ │ │ ├── 10-finops-introduction.md
│ │ │ ├── 20-how-it-works.md
│ │ │ └── 30-finops-components/
│ │ │ ├── 10-finops-operator-exporter.md
│ │ │ ├── 20-finops-operator-scraper.md
│ │ │ ├── 30-finops-operator-focus.md
│ │ │ ├── 40-finops-database-handler.md
│ │ │ ├── 50-finops-database-handler-uploader.md
│ │ │ ├── 60-finops-prometheus-exporter-generic.md
│ │ │ └── 70-finops-prometheus-scraper-generic.md
│ │ └── 40-kog/ # Krateo Operator Generator
│ │ ├── 10-oasgen-provider.md
│ │ ├── 11-oasgen-provider-cheatsheet.md
│ │ ├── 12-oasgen-provider-real-examples.md
│ │ └── 20-rest-dynamic-controller.md
│ ├── 30-how-to-guides/
│ │ ├── 10-install-krateo/
│ │ │ ├── 10-installing-krateo.md
│ │ │ ├── 80-faq.md
│ │ │ └── 99-secrets.md
│ │ ├── 20-migrate-krateo/
│ │ │ ├── 10-installation-migration.md
│ │ │ ├── 10-migrate-from-2-7-0-to-3-0-0.md
│ │ │ ├── 30-migrate-restactions.md
│ │ │ └── 40-eventlist-migration.md
│ │ ├── 40-write-frontend/
│ │ │ ├── 10-theme.md
│ │ │ ├── 11-simple-page-guide.md
│ │ │ ├── 12-action-button-guide.md
│ │ │ ├── 13-table-actions.md
│ │ │ ├── 14-autocomplete.md
│ │ │ ├── 15-form-values.md
│ │ │ ├── 16-filters.md
│ │ │ └── 20-widgets-api-reference.md
│ │ ├── 50-manage-postgresql/
│ │ │ ├── 10-intro.md
│ │ │ ├── 20-deviser.md
│ │ │ ├── 30-cnpg-configuration.md
│ │ │ └── 40-bring-your-own-postgresql.md
│ │ ├── 60-otel-configuration/
│ │ │ ├── 10-supported-components.md
│ │ │ └── 20-otel-configuration.md
│ │ └── 70-write-finops/
│ │ └── 10-finops-guide.md
│ ├── 60-core-crd-reference/
│ │ ├── 10-core-provider-crd.md
│ │ ├── 20-authn-crd.md
│ │ ├── 30-oasgen-provider-crd.md
│ │ └── 40-snowplow-crd.md
│ ├── 70-provider-crd-reference/
│ │ ├── 10-azuredevops-provider-crd.md
│ │ └── 30-git-provider-crd.md
│ ├── 80-provider-reference/
│ │ └── 10-github-provider-kog.md
│ └── 90-release-notes/
│ └── 10-release-note-3.0.0.md
├── versioned_docs/ # Auto-generated by Docusaurus on tag
│ └── .../
├── versioned_sidebars/ # Auto-generated by Docusaurus on tag
│ └── ...-sidebars.json
├── static/
│ ├── img/ # All images referenced in docs
│ │ ├── action-button-guide/
│ │ ├── frontend/
│ │ ├── kcf/
│ │ ├── kco/
│ │ ├── kcp/
│ │ ├── kog/
│ │ ├── migrating/
│ │ ├── quickstart/
│ │ └── simple-page-guide/
│ └── pdf/
├── src/ # Docusaurus theme and custom pages
├── scripts/
│ └── kind.sh
├── versions.json
├── sidebars.js
├── docusaurus.config.js
└── babel.config.js
The numeric prefixes on files and folders (e.g., 10-, 20-) control the order in which Docusaurus renders items in the sidebar. They are part of the filename convention and should be kept consistent when adding new content. The sidebar is fully auto-generated, so no manual configuration is required.
Every image used in any guide must live under static/img/. Every Markdown file must reference images using absolute paths relative to static/ (e.g., /img/kco/core-provider-architecture.png), never relative paths. This is what allows Docusaurus to resolve assets correctly across versions.
Documentation versioning is automated and tied to Git tags on this repository. When a tag is pushed (e.g., v3.0.0), the following pipeline runs:
- Docusaurus snapshots the current
docs/directory intoversioned_docs/version-3.0.0/. - The versioned sidebar is frozen in
versioned_sidebars/version-3.0.0-sidebars.json. - The compatibility table (see below) is regenerated from
krateoplatformops/releasesand committed todocs/90-release-notes/. - The Docusaurus site is built and deployed to docs.krateo.io.
You do not need to run any versioning commands manually. Pushing a tag is sufficient. If you are re-tagging an already published version, delete the old tag and push the tag again; the release workflow will clear the stale Docusaurus snapshot and any existing GitHub Release before recreating them.
Tag format: vMAJOR.MINOR.PATCH -> must match the Krateo platform release in krateoplatformops/releases.
- Delete the specific release (e.g.,
3.0.0) in the repo from the Github UI - Delete the specific tag (e.g.,
3.0.0) in the repo from the Github UI - Push the new changes to main
- Push the same tag (e.g.,
3.0.0) to be updated
The compatibility table is automatically generated by the tag pipeline. It is sourced from krateoplatformops/releases and maps each Krateo platform version to the correct release of every component.
Do not edit this file manually. Changes will be overwritten on the next tag.
Example of the generated table:
| Name | Version |
|---|---|
| authn | 0.22.2 |
| snowplow | 0.20.6 |
| cloudnative-pg | 0.27.1 |
| cluster | 0.5.0 |
| deviser | 0.5.1 |
| resources-ingester | 1.1.0 |
| ... | ... |
Follow these four steps to migrate an existing repository's documentation into krateo-v2-docs.
Identify all documentation content in the source repository:
docs/orwiki/folders- Guides in Markdown (
.md) anywhere in the repo - Images (
.png,.svg,.gif,.jpg) referenced by documentation - Any
CONTRIBUTING.md, architecture docs, or tutorial files
Place Markdown files in the most appropriate section under docs/. The top-level sections and their scope are:
| Folder | Purpose |
|---|---|
docs/20-key-concepts/10-kco/ |
Krateo Composable Operations components (core-provider, composition-dynamic-controller, provider-runtime) |
docs/20-key-concepts/20-kcp/ |
Krateo Composable Portal components (frontend, snowplow, authn, events-presenter, resources-presenter) |
docs/20-key-concepts/30-kcf/ |
Krateo Composable FinOps components |
docs/20-key-concepts/40-kog/ |
Krateo Operator Generator components (oasgen-provider, rest-dynamic-controller) |
docs/30-how-to-guides/10-install-krateo/ |
Installation guides and FAQs |
docs/30-how-to-guides/20-migrate-krateo/ |
Migration guides between versions |
docs/30-how-to-guides/40-write-frontend/ |
Frontend development guides |
docs/30-how-to-guides/50-manage-postgresql/ |
PostgreSQL setup and configuration |
docs/30-how-to-guides/60-otel-configuration/ |
OpenTelemetry configuration |
docs/60-core-crd-reference/ |
CRD reference for core Krateo components |
docs/70-provider-crd-reference/ |
CRD reference for providers |
docs/80-provider-reference/ |
Provider usage reference |
docs/90-release-notes/ |
Release notes per version |
Move all images to the matching subfolder under static/img/. Use the component or section name as the subfolder (e.g., images for a KCO component go in static/img/kco/).
When adding a new file, pick a numeric prefix that fits logically between existing entries. Leave gaps (e.g., 35-, 45-) to allow future insertions without renumbering.
Each folder must contain a _category_.json to set its sidebar label and position. Copy an existing one and adjust the label and position fields.
All links and image references must use absolute paths understood by Docusaurus. Replace every relative reference with its absolute counterpart.
| Before (relative, from source repo) | After (absolute, for Docusaurus) |
|---|---|
 |
 |
[see config](../config.md) |
[see config](/docs/20-key-concepts/10-kco/10-core-provider) |
[install guide](./INSTALL.md) |
[install guide](/docs/30-how-to-guides/10-install-krateo/10-installing-krateo) |
Search for ](./ and ](../ in all moved Markdown files to catch remaining relative references before opening a PR.
Once content is live on docs.krateo.io, replace the source repository's README with the minimal template below. The README should answer "what is this and how do I install it?" — nothing more. All extended documentation lives at the linked docs page.
See the README template in the next section.
Remove from the source repository:
- Any
docs/orwiki/folder - Standalone guide Markdown files
- Images used only by documentation (not by the code itself)
ARCHITECTURE.md,TUTORIAL.md, or equivalent standalone doc files
Open two pull requests:
- PR to
krateo-v2-docs— adds the migrated content under the appropriatedocs/subfolder and images understatic/img/. - PR to the source repository — replaces the README with the minimal version and removes migrated documentation files.
Before merging, verify:
- All images render correctly on the local Docusaurus preview (
npm run start). - No broken internal links (with
npm run build, Docusaurus will report broken links as errors). - The source repository README link points to the correct live page on
docs.krateo.io. - The new files appear correctly in the auto-generated sidebar.
- Each new folder has a
_category_.jsonwith a correctlabelandposition.
Merge the krateo-v2-docs PR first so the docs page is live before the source repository README points to it.
Use the following structure for every repository README after migration. Sections must appear in this order. Do not add additional top-level sections.
# <component-name>
<One or two sentences describing what this component does and its role in the Krateo platform.>
📖 **Full documentation**: [docs.krateo.io — <component-name>](<link-to-docs-page>)
---
## Key features
- <Feature one>
- <Feature two>
- <Feature three>
## Requirements
| Dependency | Minimum version |
|------------|----------------|
| Kubernetes | v1.26 |
| Krateo | v3.0.0 |
| <other> | <version> |
## Install
\```bash
helm repo add krateo https://charts.krateo.io
helm repo update
helm install <component-name> krateo/<component-name> --namespace krateo-system --create-namespace
\```
> For advanced installation options, custom values, and upgrade instructions, see the [installation guide](<link-to-docs-page>).
## Environment variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `VAR_NAME` | Yes | — | What it controls |
| `VAR_NAME` | No | `value` | What it controls |
- Write in plain, direct English. Assume the reader is a Kubernetes-literate engineer who is new to Krateo.
- One concept per page. If a page covers more than one distinct topic, split it.
- All code blocks must specify a language (
```bash,```yaml,```json). - Use admonitions (
:::note,:::warning,:::tip) for information that needs to stand out — don't bury warnings in body text. - Screenshots and diagrams are welcome and encouraged. Place images in the matching
static/img/<section>/subfolder and reference them with absolute paths.
- Create a
.mdfile in the appropriatedocs/subfolder, following the numeric prefix convention. - Add frontmatter at the top:
---
title: "Page title"
sidebar_label: "Short label"
sidebar_position: 3
---- If the page lives in a new folder, add a
_category_.jsonin that folder:
{
"label": "Section Name",
"position": 5
}- If the page includes images, add them to the corresponding
static/img/<section>/subfolder.
git clone https://github.com/krateoplatformops/krateo-v2-docs.git
cd krateo-v2-docs
npm install
npm run startThe site will be available at http://localhost:3000. Changes to Markdown files hot-reload automatically.
To verify the full build (including broken-link detection) before opening a PR:
npm run build
npm run serve