Skip to content

The cluster's documentation

ethere's documentation is one site, served by every cluster at the version of ethere its configuration pins, on <zone> through the Gateway, public (ethere is open source: how a cluster works is no secret). docs/ is that site's tree, a tab per audience (mkdocs.yml's nav):

Tab In docs/ On <zone> For
Users *.md /<page>.html whoever deploys into the cluster, a person or an agent
Admins admin/*.md /admin/<page>.html the cluster's admins: how it works, how to run it
Developers dev/*.md (todo.md: TODO.md) /dev/<page>.html ethere's developers: designs, the roadmap

The users' tab starts from nothing: an application that has never run on ethere is handed one URL, https://<zone>/ (or its llms.txt), which leads to a namespace, a kubeconfig, a deployment.

What is served where

Who reads it Where
ethere's site (mkdocs.yml, docs/) anyone https://<zone>/; the users' pages (k8s_docs_pages) as Markdown too (<page>.md), /llms.txt, /version.txt, and in the ConfigMap ethere-docs of kube-public (every authenticated user)
the cluster's public pages (its docs/cluster/*.md, cluster.md their entry) anyone next to the users' pages (/cluster.html, the users' tab's section "This cluster"), from its repository at the revision Flux has
the cluster's admin pages (front matter audience: admin) the cluster's admins the cluster's configuration repository: never served
a tenant's namespace (its names, quota, members, Flux objects) its members the ConfigMap ethere-docs of the namespace (the ethere-tenants chart)

What a reader's rights add is read through the API: RBAC decides, the server holds no identity. Secrets are never in a page: a page names the Secret, which only those allowed read.

How

  • A server of ethere's own (libexec/docs-server.py: the Python standard library and Zensical), its image ethere-docs built like the operator's (playbooks/containers.yml, containers/_docs.yml), tagged with the version of ethere it serves (ethere_version), pushed with the operator's (registry/push.yml). Two replicas in ethere-docs, non-root, read-only but its builds' /tmp (an emptyDir), every capability dropped. It holds the whole site in memory and serves its keys alone (a URL is never a path on disk): the built site (its pages, assets, search.json), the users' and the cluster's pages as Markdown, /llms.txt, /version.txt, /status (the revision built, the last error), /healthz, /readyz. Its Content-Security-Policy: the site's own files, the theme's inline scripts by their hashes; nothing loaded from elsewhere (font: false: the system's fonts).
  • Built by Zensical (mkdocs.yml, the format MkDocs 1.6 with Material 9 reads too), pinned (a 0.x: pyproject.toml's group docs), for each revision: ethere's docs/ and the cluster's pages assembled in a directory of their own (the users' pages' placeholders replaced, the cluster's under "This cluster", the site's name the cluster's), zensical build --clean --strict (a broken link or anchor refuses it), read back. About 2 s and 80 MiB for the whole site.
  • ethere's site (mkdocs.yml, docs/) is in its image: it is the version's.
  • The cluster's are read from the git repository Flux already follows (the GitRepository tenants, its artifact limited to the declaration and k8s_docs_cluster_path, docs/cluster): the server reads the object's status (a Role on it alone), downloads the revision's tarball from source-controller (a NetworkPolicy of Flux's namespace lets it, alone, in), checks its digest and renders it. A commit pushed is a page served (Flux's interval, then the server's: 30 s), nothing to run. A revision that fails to render (a broken link, an unknown placeholder, no cluster.md, a name of ethere's) leaves the site before it, its error in /status and an X-Docs-Error header; etherectl docs check renders them as the server will, before the commit.
  • Beside the site (plugins/filter/docs.py, the server's and Ansible's): the users' pages as Markdown, llms.txt (https://llmstxt.org: the users' pages and the cluster's, an agent's entry), version.txt. Their @NAME@ placeholders: k8s_docs_values (the version, the registry's name, the StorageClass, the zone, the documentation's URL), the server's configuration (the ConfigMap docs-server); never Jinja, the pages show Helm and Flux templates. Only the users' and the cluster's pages have them.
  • playbooks/k8s/docs.yml (part of k8s/configure.yml, which the operator runs): the server's objects (inventory/group_vars/all/docs.yml), its route (k8s_docs_hostname: docs. + the cluster's zone), ethere's Markdown in kube-public. Its policy: the Gateway in; out, the API and source-controller (DNS: the default policies').
  • Admission refusals name the page (k8s_docs_names_ref, the names policy: docs/admin/tenants.md).

Images up to 1e2a8ab held a static server as an addon (docs, applied again at the boot of such an image's servers): k8s/docs.yml deletes it and its pages; nothing routes to it.

Adding a page

ethere's: in the tab's directory of docs/ (a # title; a users' page: a first paragraph, its summary in llms.txt, linked from index.md, for deployers, never an admin's internals: no etherectl, no sops), its place in mkdocs.yml's nav (the users' tab is k8s_docs_pages). Python-Markdown's rules (Zensical's): a nested list, or a block in a list item, indented by 4 spaces; a blank line before a list. etherectl docs serve previews the site, etherectl docs check builds it as the server will and compares each page with CommonMark's reading; tests/docs/ check every page is in nav, once. They reach a cluster with the server's image (a new version of ethere). A cluster's: docs/cluster/<name>.md in its configuration, etherectl docs serve and check, a commit pushed.

Not yet

A personalised view (the caller's token: TokenReview, SubjectAccessReview, its namespaces' pages) and an MCP server, both with the members' identities (Dex): TODO.md.