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 imageethere-docsbuilt 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 inethere-docs, non-root, read-only but its builds'/tmp(anemptyDir), 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 groupdocs), for each revision: ethere'sdocs/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 andk8s_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, nocluster.md, a name of ethere's) leaves the site before it, its error in/statusand anX-Docs-Errorheader;etherectl docs checkrenders 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 ConfigMapdocs-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 ofk8s/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 inkube-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.