k0rdent Documentation

The home of the consolidated documentation for k0rdent sponsored by Mirantis.

k0rdent Docs

This project utilises Mkdocs with the Material theme and Mermaid for diagrams. Currently the docs are published using github actions on github pages from the branch gh-pages.

Development is tracked under k0rdent on github.

The k0rdent org is:

• k0rdent

The related k0rdent repositories can be found as follows:

• k0rdent Cluster Manager (kcm)
• k0rdent Observability and FinOps (kof)
• k0rdent Documentation Source (docs)
• k0rdent Community Documentation

Project layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    stylesheets  # CSS stylesheets to control look and feel
    assets  # Images and other served material
    ...       # Other markdown pages, images and other files.

Setting up MKdocs and dependancies

1. Setup python Virtual Environment

  python3 -m venv ./mkdocs
  source ./mkdocs/bin/activate

2. Install MkDocs

  pip install mkdocs

3. Install plugins

  pip install mkdocs-mermaid2-plugin
  pip install mkdocs-material
  pip install markdown-callouts

Run MKdocs for dev

• Start the live-reloading docs server.

For full documentation visit mkdocs.org.

MKdocs Commands

• mkdocs new [dir-name] - Create a new project.
• mkdocs build - Build the documentation site.
• mkdocs -h - Print help message and exit.

Updating the API reference examples

docs/api-specification/index.md renders docs/openapi/openapi.yaml with Scalar. That spec is synced from k0rdent-apis and must stay byte-identical, so it has almost no response examples — most fields render as "string".

docs/openapi/openapi-sandbox.yaml is an enriched copy: the same contract with an example on every required parameter and a plausible response body on every 2xx that lacked one. It's a committed file, not a build artifact — regenerate it on demand, not on every build, whenever docs/openapi/openapi.yaml or mock/seed.yaml changes:

pip install -r requirements.txt   # only needed once; adds PyYAML
python scripts/generate-mock-data.py

or, to regenerate it and rebuild the site in one step:

scripts/build-with-sandbox.sh

The reference picks the enriched file up on its own — it lives under docs/openapi/, so mkdocs build/mkdocs serve copy it like any other static file, and docs/api-specification/index.md's own script checks for it and falls back to the pristine spec if it's absent. No mkdocs.yml change needed either way.

There's no live "Send" button here: this repo has no mock API backend behind the reference (see docs/api-specification/sandbox.md). Regenerating only changes the examples shown, not what the page can do.

Documentation Standards

By default, we follow the Kubernetes documentation style guide.

Header Capitalization

All header text should be capitalized.

Embedding videos

Videos and large animated gif files should not be stored in the repository. Instead, they should be stored in the Mirantis Docs shared drive. If you don't have access to this drive, add the asset file to the PR and note it in the description. To add the video to the page, use this format:

<iframe  src="https://drive.google.com/file/d/<FILE_ID>/preview" style="aspect-ratio: <HEIGHT> / <WIDTH>;"      allow="autoplay" allowfullscreen></iframe>

You can retrieve the FILE_ID of the video or gif by choosing Share-->Copy URL for the video on Google Drive and extracting it from the URL. For example, the FILE_ID for:

https://drive.google.com/file/d/1MrCs07LGN5LPD4stktwC5sv0PB8HclTa/view?usp=sharing

is

1MrCs07LGN5LPD4stktwC5sv0PB8HclTa

If necessary, you can get the HEIGHT and WIDTH values by previewing the video and choosing File-->Details-->Dimensions.

Referencing Kubernetes nested resources

Please use the dot notation. So in the following:

apiVersion: v1
kind: Secret
metadata:
  name: my-secret

To refer to the name field, please use .metadata.name and not name.