public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: k8s backend contrib docs minor fixes (#106174)

Browse Source 
* docs: minor k8s inspired doc changes

* docs: revert to v1 as recommended first major

* Update contribute/architecture/k8s-inspired-backend-arch.md

Co-authored-by: Igor Suleymanov <radiohead@users.noreply.github.com>

---------

Co-authored-by: Igor Suleymanov <radiohead@users.noreply.github.com>
This commit is contained in:
Costa Alexoglou
2025-06-17 15:12:49 +02:00
committed by GitHub
co-authored by Igor Suleymanov
parent 94013a341c
commit 9ce207b472
1 changed files with 8 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
contribute/architecture/k8s-inspired-backend-arch.md
+8 -8
View File
@@ -43,9 +43,9 @@ The end goal is for the Resource APIs to become the only interface for managing
- **API implementation approaches:**
- **Registry Approach (`pkg/registry/apis/...`):** Original method using Go code (`.../register.go` files). While newer resources are primarily defined using CUE in `apps/`, this path is still used for things such as legacy fallbacks for App-defined resources when data for that resource exists outside of unified storage.
- **Apps Approach (`apps/...`):** The newer, more modular implementation where APIs are defined using CUE in self-contained modules. Each app defines resources in `kinds/*.cue` files and resources are registered via the App SDK. This is the direction Grafana is moving toward for all resources.
- **Apps Approach (`apps/...`):** The newer, more modular implementation where APIs are defined using CUE in self-contained modules. Each app defines resources in `kinds/*.cue` files and resources are registered via the App SDK. This is the direction Grafana is moving towards for all resources.
- **Unified Storage (`pkg/storage/unified/...`):** Internal abstraction handling resource persistence. It handles the conversion between the Resource API and the underlying storage backend.
- **`K8sHandler` (`pkg/services/apiserver/client/client.go`):** Internal client facade used by Grafana services. Provides a Kubernetes-like client interface (`Get`, `Create`, etc.) for the Resource API. Acts as an adapter during migration, enabling legacy services to use the Resource API. Does not interact with external systems - it interact only with Grafana's own APIs.
- **`K8sHandler` (`pkg/services/apiserver/client/client.go`):** Internal client facade used by Grafana services. Provides a Kubernetes-like client interface (`Get`, `Create`, etc.) for the Resource API. Acts as an adapter during migration, enabling legacy services to use the Resource API. Does not interact with external systems - it interacts only with Grafana's own APIs.
- **Configured SQL database:** Grafana's primary persistence layer (PostgreSQL, MySQL, SQLite). The persistence target for actions initiated within Grafana's UI/Legacy API. It's the default backend for Unified Storage
- **App SDK (`github.com/grafana/grafana-app-sdk`):** SDK for the Apps Approach. Provides tools for defining resources (CUE) and generating code.
@@ -75,11 +75,11 @@ The `apps` directory structure is Grafana's intended future for defining APIs an
**Example: Playlist App (`apps/playlist/`)**
- `kinds/playlist.cue`: CUE schema for the `Playlist` resource kind and its `spec`.
- `kinds/manifest.cue`: App and resource kind metadata.
- `pkg/apis/playlist/v0alpha1/`: Generated Go types from the CUE schema.
- `pkg/app/reconciler_playlist.go`: Reconciler acting on `Playlist` resources.
- `pkg/registry/apps/playlist/register.go`: Registers the `Playlist` kind and API endpoints using the App SDK.
- `(plugin)/kinds/playlist.cue`: CUE schema for the `Playlist` resource kind and its `spec`.
- `(plugin)/kinds/manifest.cue`: App and resource kind metadata.
- `(plugin)/pkg/apis/playlist/v0alpha1/`: Generated Go types from the CUE schema.
- `(plugin)/pkg/reconcilers/reconciler_playlist.go`: Reconciler acting on `Playlist` resources.
- `(root)/pkg/registry/apps/playlist/register.go`: Registers the `Playlist` kind and API endpoints using the App SDK.
The Apps Approach creates the same Resource API endpoints (`/apis/...`) as the Registry Approach, but with a cleaner implementation and improved developer experience. It's the standard pattern for all future Grafana resources.
@@ -89,7 +89,7 @@ Grafana's Resource APIs adopts many Kubernetes API conventions but is **not stri
In other words, even when the URLs / resources look Kubernetes-like, some API Server guarantees might not hold. We are adopting Kubernetes API patterns, general structure, and declarative style. A strict, byte-for-byte conformance to the API spec is currently not a goal.
The list of major architectural changes include:
The list of major architectural changes includes:
- **Persistence:** Uses Grafana's configured SQL database (PostgreSQL, MySQL, SQLite) via Unified Storage, not `etcd`.
- **Auth:** Uses Grafana's standard auth (API keys, sessions, RBAC/Permissions), not Kubernetes ServiceAccounts or RBAC.