diff --git a/apps/example/README.md b/apps/example/README.md index b8780ca0274..8a69389c3fa 100644 --- a/apps/example/README.md +++ b/apps/example/README.md @@ -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 :` flag. +You can also interact with the grafana API server via a kubeconfig set up for it, or via `curl` using the `-u :` 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"} -``` \ No newline at end of file +```