Run prettier on apps/example/README.md
CodeQL checks / Detect whether code changed (push) Waiting to run Details
CodeQL checks / Analyze (actions) (push) Blocked by required conditions Details
CodeQL checks / Analyze (go) (push) Blocked by required conditions Details
CodeQL checks / Analyze (javascript) (push) Blocked by required conditions Details

This commit is contained in:
Austin Pond 2025-10-06 11:53:23 -04:00
parent 51cb0931a2
commit 1ad75a4335
No known key found for this signature in database
GPG Key ID: E96F015B40A49C32
1 changed files with 25 additions and 18 deletions

View File

@ -1,10 +1,11 @@
# Example App
This App is an example of general app capabilities when developing on the grafana app platform.
This App is an example of general app capabilities when developing on the grafana app platform.
## Enabling the App
By default, the example app is disabled. To enable this App, add the following to your `conf/custom.ini`:
By default, the example app is disabled. To enable this App, add the following to your `conf/custom.ini`:
```
[grafana-apiserver]
runtime_config = example.grafana.app/v0alpha1=true,example.grafana.app/v1alpha1=true
@ -12,33 +13,34 @@ runtime_config = example.grafana.app/v0alpha1=true,example.grafana.app/v1alpha1=
## Manifest
The source of the app's schemas and list of capabilities is the manifest, which is generated from [kinds/manifest.cue](./kinds/manifest.cue).
The `Example` kind is defined for [v0alpha1 here](./kinds/example_v0alpha1) and [v1alpha1 (default) here](./kinds/example_v1alpha1.cue).
The source of the app's schemas and list of capabilities is the manifest, which is generated from [kinds/manifest.cue](./kinds/manifest.cue).
The `Example` kind is defined for [v0alpha1 here](./kinds/example_v0alpha1) and [v1alpha1 (default) here](./kinds/example_v1alpha1.cue).
The root definition of the `Example` kind that both versions share is defined [here](./kinds/example.cue).
The CUE is used to generate code (and the AppManifest) when `make generate` is run.
## Code
All of the app's code is located in [pkg/app](./pkg/app/). The [New() function](./pkg/app/app.go#20) in `pkg/app/app.go` is the entry point of the app,
All of the app's code is located in [pkg/app](./pkg/app/). The [New() function](./pkg/app/app.go#20) in `pkg/app/app.go` is the entry point of the app,
and everything should be discoverable from there.
The code to register the app with the grafana API server (including inserting the app-specific config [ExampleConfig](./pkg/app/config.go))
The code to register the app with the grafana API server (including inserting the app-specific config [ExampleConfig](./pkg/app/config.go))
is located in [/pkg/registry/apps/example/register.go](../../pkg/registry/apps/example/register.go).
Any app must also have its installer listed in [WireSet](../../pkg/registry/apps/wireset.go) and added to `installers` in [ProvideAppInstallers](../../pkg/registry/apps/apps.go). When building a new app, make to to regerate wire (`make build` in the root of the repo does this).
### Generated Code
The [pkg/apis](./pkg/apis/) package, and all its subdirectories, contain code generated by `make generate`.
The [pkg/apis](./pkg/apis/) package, and all its subdirectories, contain code generated by `make generate`.
This code should not be edited, but it can be useful to look at when working through the flow of the app.
## Sample Swagger Payloads
Navigate to [localhost:3000/swagger?api=example.grafana.app-v1alpha1](http://localhost:3000/swagger?api=example.grafana.app-v1alpha1) to view the swagger for the app's `v1alpha1` version
Navigate to [localhost:3000/swagger?api=example.grafana.app-v1alpha1](http://localhost:3000/swagger?api=example.grafana.app-v1alpha1) to view the swagger for the app's `v1alpha1` version
(this version has the most capabilities/endpoints). You can use the `Execute` button to make requests via the swagger UI.
Create a new `Example` resource with via swagger with:
```json
{
"apiVersion": "example.grafana.app/v1alpha1",
@ -51,16 +53,17 @@ Create a new `Example` resource with via swagger with:
"firstField": "test",
"secondField": 0,
"list": {
"info": "foo",
"next": {
"info": "bar"
}
"info": "foo",
"next": {
"info": "bar"
}
}
}
}
```
Create an invalid object which will be rejected by validation:
```json
{
"apiVersion": "example.grafana.app/v1alpha1",
@ -73,16 +76,17 @@ Create an invalid object which will be rejected by validation:
"firstField": "test",
"secondField": 0,
"list": {
"info": "foo",
"next": {
"info": "bar"
}
"info": "foo",
"next": {
"info": "bar"
}
}
}
}
```
Update `custom` subresource:
```json
{
"apiVersion": "example.grafana.app/v1alpha1",
@ -98,16 +102,19 @@ Update `custom` subresource:
}
}
```
(`metadata.resourceVersion` is required for an update, use the value you get from a GET request)
## cURL
You can also interact with the grafana API server via a kubeconfig set up for it, or via `curl` using the `-u <username>:<password>` flag.
You can also interact with the grafana API server via a kubeconfig set up for it, or via `curl` using the `-u <username>:<password>` flag.
Currently, cluster-scoped custom routes are erased from the swagger as part of grafana's APIServer code, but can still be called via `curl`, like so:
```bash
curl -u admin:admin http://localhost:3000/apis/example.grafana.app/v1alpha1/other
```
```
% curl -u admin:admin http://localhost:3000/apis/example.grafana.app/v1alpha1/other
{"message":"This is a cluster route"}
```
```