Apps: Add Example App to ./apps (#112069)

* [API Server] Add Example App for reference use. * Remove Printlns. * Upgrade app-sdk to v0.46.0, update apps to handle breaking changes. * Only start the reconciler for the example app if the v1alpha1 API version is enabled. * Some comment doc updates. * Run make update-workspace * Set codeowner for /apps/example * Run make gofmt and make update-workspace * Run prettier on apps/example/README.md * Add COPY apps/example to Dockerfile * Add an authorizer to the example app. * Fix import ordering. * Update apps/example/kinds/manifest.cue Co-authored-by: Owen Diehl <ow.diehl@gmail.com> * Run make update-workspace * Re-run make gen-go for enterprise import updates * Run make update-workspace --------- Co-authored-by: Owen Diehl <ow.diehl@gmail.com>
2025-10-27 12:01:10 -04:00
parent d25f5199c7
commit bf65c43783
71 changed files with 3744 additions and 4 deletions
@@ -0,0 +1,120 @@
+# Example App
+
+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`:
+
+```
+[grafana-apiserver]
+runtime_config = example.grafana.app/v0alpha1=true,example.grafana.app/v1alpha1=true
+```
+
+## 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 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,
+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))
+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`.
+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
+(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",
+  "kind": "Example",
+  "metadata": {
+    "name": "test",
+    "namespace": "default"
+  },
+  "spec": {
+    "firstField": "test",
+    "secondField": 0,
+    "list": {
+      "info": "foo",
+      "next": {
+        "info": "bar"
+      }
+    }
+  }
+}
+```
+
+Create an invalid object which will be rejected by validation:
+
+```json
+{
+  "apiVersion": "example.grafana.app/v1alpha1",
+  "kind": "Example",
+  "metadata": {
+    "name": "invalid",
+    "namespace": "default"
+  },
+  "spec": {
+    "firstField": "test",
+    "secondField": 0,
+    "list": {
+      "info": "foo",
+      "next": {
+        "info": "bar"
+      }
+    }
+  }
+}
+```
+
+Update `custom` subresource:
+
+```json
+{
+  "apiVersion": "example.grafana.app/v1alpha1",
+  "kind": "Example",
+  "metadata": {
+    "namespace": "default",
+    "name": "test",
+    "resourceVersion": "<REPLACEME>"
+  },
+  "custom": {
+    "myField": "foo",
+    "otherField": "bar"
+  }
+}
+```
+
+(`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.
+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"}
+```