docs: architecture: Add new architecture.md doc #2760
Conversation
This contains the beginnings of an architecture.md doc which provides a high level map to people new to the project. Signed-off-by: René Dudfield <renedudfield@microsoft.com>
dosubot
bot
added
the
size:L
illume
changed the title
|
|
||
| ## Introduction | ||
|
|
||
| Headlamp is a user-friendly and extensible Kubernetes UI designed to provide a seamless experience for managing Kubernetes clusters. It can connect to one or multiple Kubernetes clusters and can be deployed as a web app in-cluster or as a desktop app. Headlamp can be customized and |
There was a problem hiding this comment.
Unintended trailing sentence?
There was a problem hiding this comment.
Maybe mention what this section is about instead of mentioning what Headlamp is (because the intro to Headlamp should is given in a different section of the docs)?
| ## High-Level Architecture | ||
|
|
||
| ### Headlamp running as a Desktop App (on MacOS, Windows, Linux etc) | ||
| ```mermaid |
There was a problem hiding this comment.
This is not displaying in the website.
There was a problem hiding this comment.
docusaurus can support it with a plugin https://docusaurus.io/docs/markdown-features/diagrams
|
|
||
| Headlamp can use websockets to get soft-realtime UI updates from Kubernetes when things change. | ||
|
|
||
| Because web browsers limit the number of websockets that can be created, the headlamp-server |
| - See the [Backend Documentation](https://headlamp.dev/docs/latest/development/backend/) for more information including a Quickstart. | ||
|
|
||
| A few key dependencies: | ||
| - **Golang**: Written using the [golang]() language. |
| - **Gorilla**: is the web framework we use | ||
| - **Kubernetes and Helm**: Uses Kubernetes and Helm golang packages. | ||
|
|
||
| Packages are stored in the [backend/pkg](https://github.com/headlamp-k8s/headlamp/blob/main/backend/pkg/) folder. The packages available are cache, config, helm, kubeconfig, logger, plugins, portforward, and utils. Future code should be organized in packages. There is still some code inside cmd/ folder that probably should be migrated to separate packages. |
There was a problem hiding this comment.
I would not list the actual packages, since then we need to keep this up to date.
| - See the [Plugin Development Documentation](https://headlamp.dev/docs/latest/development/plugins/) for more information about developing plugins. | ||
|
|
||
| A few key dependencies: | ||
| **TypeScript**: Written in TypeScript. |
There was a problem hiding this comment.
TypeScript: Written in TypeScript. -> TypeScript: Language in which the plugins are written.
| - **Go for Backend**: Selected because Kubernetes APIs and ecosystem APIs use golang. Also for its performance and concurrency capabilities. | ||
| - **React for Frontend**: Chosen for its component-based architecture and strong community support. |
There was a problem hiding this comment.
These are technological decisions, not design ones IMO.
| - **React for Frontend**: Chosen for its component-based architecture and strong community support. | ||
| - **Extensibility**: Designed with a plugin system to allow easy customization and extension. | ||
| - **Multi-Cluster Support**: Designed to manage multiple Kubernetes clusters from a single interface. | ||
| - **Realtime**: Designed to react in real time to changes in clusters. |
There was a problem hiding this comment.
Maybe add:
- **Adaptive UI**: The UI should adapt to the user's permissions in the cluster, e.g. if the user cannot edit a resource, then a view button is shown instead of the edit button.| - **Multi-Cluster Support**: Designed to manage multiple Kubernetes clusters from a single interface. | ||
| - **Realtime**: Designed to react in real time to changes in clusters. | ||
|
|
||
| We ask that people write issues proposing large changes. See more in the [contribution guide](https://headlamp.dev/docs/latest/contributing). |
There was a problem hiding this comment.
This seems out of context in this subsection or even section. Belongs to contributing.
| ```mermaid | ||
| graph TD | ||
| F[Plugins] -->|Can be| I[Private and Self Hosted] | ||
| F -->|Or| J[Public and Hosted on Artifact Hub] |
There was a problem hiding this comment.
Not really hosted but indexed. Hosted in Github, Gitlab, or BitBucket, and indexed in ArtifactHub.
This contains the beginnings of an architecture.md doc
which provides a high level map to people new to the project.
An architecture doc is a requirement for CNCF incubating projects.