Gentian OS documentation
Gentian OS turns a Kubernetes cluster into a cloud operating system: tenants, identity, routing, storage, mail and an app catalog, installed and upgraded as one. These documents describe the system as it is. The past is in git, the future in the issues.
Start with this page: it lists every document by section and says who it is for. GETTING-STARTED.md installs a cluster. Agents read AGENTS.md first.
Overview
For readers who know software but not cloud-native systems.
| Document | What it answers |
|---|---|
| introduction.md | What Gentian OS is and how it is run, in plain terms, with a glossary |
| architecture.md | What Gentian OS is, the OS analogy, the architecture at a glance, the kinds, how it scales |
| why-a-cloud-os.md | Why open-source business software needs an operating system around it |
| faq.md | Frequently asked questions |
Guides
How to do one thing, for operators, tenant administrators and app authors.
| Document | What it covers |
|---|---|
| deployment.md | Deployment environments, promotion and release numbering |
| app-customization.md | Customizing an installed app along the customization ladder |
| custom-catalogs.md | Publishing a catalog of your own |
| identity-brokering.md | People of another realm signing in to a tenant |
| tenant-backup.md | Backing up and recovering a workspace, as a tenant administrator |
| recovery.md | Recovering after a loss of a cluster, a tenant or a key |
| node-pool-migration.md | Moving a cluster to a new node flavor |
Reference
Complete and exact: every flag, command and field.
| Document | What it lists |
|---|---|
| install.md | The installer: steps, flags, configuration surfaces, tenancy modes |
| commands.md | The kubectl gentian commands |
| store-api/ | The App Store API: contract, OpenAPI documents, schema |
| crds.md | Every gentianos.io kind with all of its fields, generated from the CRDs |
| commands-synopsis.md | The kubectl gentian synopsis, generated from the plugin |
| install-steps.md | The installer's flags and steps, generated from install.sh and scripts/steps/ |
| versions.md | The pinned component versions, generated from versions.yaml |
| namespaces.md | The namespace layout by tier, generated from kernel/namespaces.yaml |
The generated pages are written by scripts/gen/gen-docs.py (make gen-docs), which also writes llms.txt for language models.
Concepts
How each part is designed and why, for architects, operators and app authors.
| Document | Topic |
|---|---|
| kernel.md | Kernel functions, the default install, namespaces, system engines |
| control-plane.md | The programs of the control plane: what each holds and refuses |
| multi-tenancy.md | Tenants, isolation, domains, tenancy modes |
| routing.md | The edge, routes, sign-in sessions, embedding |
| networking.md | Network layers, policies, exposure, certificates, TURN |
| iam.md | Identity and access management, realms, roles, sign-in |
| authorization.md | The authorization model: relations, roles, projections |
| app-authorization.md | Authorization stores for apps and the arbiter |
| partners.md | Identity across clusters |
| app-catalog.md | Profiles, classes, integrations, tiers, the component model |
| store-contract.md | What a cluster accepts from an App Store |
| versioning.md | Versions, floors, update modes, the guarded move |
| admin-console.md | The administration console and the desktop |
| branding.md | One brand on every page: tokens, identity, publishing |
| resource-plans.md | Resource plans, quotas and usage |
| mail.md | The mail kernel extension |
| operations.md | Backup, disaster recovery, observability, image updates |
| data-lifecycle.md | What each operation does with a tenant's and an app's data |
| data-ownership.md | What a tenant owns, the commitments, the bundle that carries it all, and where the OS ends |
| agentic-ai.md | The agentic AI layer and MCP |
| llms.md | LLM serving |
Decisions
The architectural decisions, numbered AD-1 onward, each with its reason: decisions/index.md.
Security
| Document | For |
|---|---|
| principles.md | The normative rules every change is held to |
| design.md | Identity, authorization, isolation, secrets, TLS: the security design |
| audit-events.md | Audit events, log forwarding and monitoring |
| controls.md | The controls, as an auditor reads them |
Reporting a vulnerability: SECURITY.md.
Releases
One page per release in releases/, the one place that records what changed.
Contributing
| Document | What it covers |
|---|---|
| CONTRIBUTING.md | How to contribute, the sign-off |
| folder-structure.md | What lives where in this repository |
| documentation.md | How these documents are written |
| LICENSING.md | What license covers what |
Other repositories
| Repository | Holds |
|---|---|
| gentian-apps | The open-source catalog, the profile guide, the custom app guide |
| gentian-ui | The desktop, the administration console, the App Store app, the sign-in page |
| gentian-deployments | Cluster-specific GitOps manifests |
| gentian-sidecars | Sidecar templates |