diff --git a/docs/sources/developers/plugins/metadata.md b/docs/sources/developers/plugins/metadata.md index 787ebfc168f..2b2b343499f 100644 --- a/docs/sources/developers/plugins/metadata.md +++ b/docs/sources/developers/plugins/metadata.md @@ -16,12 +16,12 @@ The plugin.json file is required for all plugins. When Grafana starts, it scans | Property | Type | Required | Description | | -------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dependencies` | [object](#dependencies) | **Yes** | Dependencies needed by the plugin. | -| `id` | string | **Yes** | Unique name of the plugin. If the plugin is published on grafana.com, then the plugin id has to follow the naming conventions. | -| `info` | [object](#info) | **Yes** | Metadata for the plugin. Some fields are used on the plugins page in Grafana and others on grafana.com if the plugin is published. | +| `id` | string | **Yes** | Unique name of the plugin. If the plugin is published on grafana.com, then the plugin `id` should follow the Grafana naming convention. | | `name` | string | **Yes** | Human-readable name of the plugin that is shown to the user in the UI. | -| `type` | string | **Yes** | Plugin type. Possible values are: `app`, `datasource`, `panel`. | -| `$schema` | string | No | Schema definition for the plugin.json file. | +| `type` | string | **Yes** | Plugin type. Possible values are: `app`, `datasource`, `panel`, `renderer`, `secretsmanager`. | +| `info` | [object](#info) | **Yes** | Metadata for the plugin. Some fields are used on the plugins page in Grafana and others on grafana.com if the plugin is published. | +| `dependencies` | [object](#dependencies) | **Yes** | Dependency information related to Grafana and other plugins. | +| `$schema` | string | No | Schema definition for the plugin.json file. Used primarily for schema validation. | | `alerting` | boolean | No | For data source plugins, if the plugin supports alerting. | | `annotations` | boolean | No | For data source plugins, if the plugin supports annotation queries. | | `autoEnabled` | boolean | No | Set to true for app plugins that should be enabled by default in all orgs | diff --git a/docs/sources/developers/plugins/plugin.schema.json b/docs/sources/developers/plugins/plugin.schema.json index bc8af5e8784..374d11028af 100644 --- a/docs/sources/developers/plugins/plugin.schema.json +++ b/docs/sources/developers/plugins/plugin.schema.json @@ -7,24 +7,68 @@ "required": ["type", "name", "id", "info", "dependencies"], "additionalProperties": false, "properties": { - "$schema": { - "type": "string", - "description": "Schema definition for the plugin.json file." - }, "id": { "type": "string", - "description": "Unique name of the plugin. If the plugin is published on grafana.com, then the plugin id has to follow the naming conventions.", + "description": "Unique name of the plugin. If the plugin is published on grafana.com, then the plugin `id` has to follow the naming conventions.", "pattern": "^[0-9a-z]+\\-([0-9a-z]+\\-)?(app|panel|datasource|secretsmanager)$" }, "type": { "type": "string", "description": "Plugin type.", - "enum": ["app", "datasource", "panel", "secretsmanager"] + "enum": ["app", "datasource", "panel", "renderer", "secretsmanager"] }, "name": { "type": "string", "description": "Human-readable name of the plugin that is shown to the user in the UI." }, + "dependencies": { + "type": "object", + "description": "Dependency information related to Grafana and other plugins.", + "required": ["grafanaDependency"], + "additionalProperties": false, + "properties": { + "grafanaVersion": { + "type": "string", + "description": "(Deprecated) Required Grafana version for this plugin, e.g. `6.x.x 7.x.x` to denote plugin requires Grafana v6.x.x or v7.x.x.", + "pattern": "^([0-9]+)(\\.[0-9x]+)?(\\.[0-9x])?$" + }, + "grafanaDependency": { + "type": "string", + "description": "Required Grafana version for this plugin. Validated using https://github.com/npm/node-semver.", + "pattern": "^(<=|>=|<|>|=|~|\\^)?([0-9]+)(\\.[0-9x\\*]+)(\\.[0-9x\\*]+)?(\\s(<=|>=|<|=>)?([0-9]+)(\\.[0-9x]+)(\\.[0-9x]+))?$" + }, + "plugins": { + "type": "array", + "description": "An array of required plugins on which this plugin depends.", + "additionalItems": false, + "items": { + "type": "object", + "description": "Plugin dependency. Used to display information about plugin dependencies in the Grafana UI.", + "required": ["id", "name", "type", "version"], + "properties": { + "id": { + "type": "string", + "pattern": "^[0-9a-z]+\\-([0-9a-z]+\\-)?(app|panel|datasource|secretsmanager)$" + }, + "type": { + "type": "string", + "enum": ["app", "datasource", "panel", "secretsmanager"] + }, + "name": { + "type": "string" + }, + "version": { + "type": "string" + } + } + } + } + } + }, + "$schema": { + "type": "string", + "description": "Schema definition for the plugin.json file. Used primarily for schema validation." + }, "category": { "type": "string", "description": "Plugin category used on the Add data source page.", @@ -133,50 +177,6 @@ "type": "boolean", "description": "Set to true for app plugins that should be enabled by default in all orgs" }, - "dependencies": { - "type": "object", - "description": "Dependencies needed by the plugin.", - "required": ["grafanaDependency"], - "additionalProperties": false, - "properties": { - "grafanaVersion": { - "type": "string", - "description": "(Deprecated) Required Grafana version for this plugin, e.g. `6.x.x 7.x.x` to denote plugin requires Grafana v6.x.x or v7.x.x.", - "pattern": "^([0-9]+)(\\.[0-9x]+)?(\\.[0-9x])?$" - }, - "grafanaDependency": { - "type": "string", - "description": "Required Grafana version for this plugin. Validated using https://github.com/npm/node-semver.", - "pattern": "^(<=|>=|<|>|=|~|\\^)?([0-9]+)(\\.[0-9x\\*]+)(\\.[0-9x\\*]+)?(\\s(<=|>=|<|=>)?([0-9]+)(\\.[0-9x]+)(\\.[0-9x]+))?$" - }, - "plugins": { - "type": "array", - "description": "An array of required plugins on which this plugin depends.", - "additionalItems": false, - "items": { - "type": "object", - "description": "Plugin dependency. Used to display information about plugin dependencies in the Grafana UI.", - "required": ["id", "name", "type", "version"], - "properties": { - "id": { - "type": "string", - "pattern": "^[0-9a-z]+\\-([0-9a-z]+\\-)?(app|panel|datasource|secretsmanager)$" - }, - "type": { - "type": "string", - "enum": ["app", "datasource", "panel", "secretsmanager"] - }, - "name": { - "type": "string" - }, - "version": { - "type": "string" - } - } - } - } - } - }, "info": { "type": "object", "description": "Metadata for the plugin. Some fields are used on the plugins page in Grafana and others on grafana.com if the plugin is published.", diff --git a/pkg/plugins/plugindef/plugindef.cue b/pkg/plugins/plugindef/plugindef.cue index c9cfe4a951b..550a8d447ed 100644 --- a/pkg/plugins/plugindef/plugindef.cue +++ b/pkg/plugins/plugindef/plugindef.cue @@ -14,11 +14,15 @@ seqs: [ schemas: [ { // Unique name of the plugin. If the plugin is published on - // grafana.com, then the plugin id has to follow the naming + // grafana.com, then the plugin `id` has to follow the naming // conventions. id: string & strings.MinRunes(1) id: =~"^([0-9a-z]+\\-([0-9a-z]+\\-)?(\(strings.Join([ for t in _types {t}], "|"))))|(alertGroups|alertlist|annolist|barchart|bargauge|candlestick|canvas|dashlist|debug|gauge|geomap|gettingstarted|graph|heatmap|histogram|icon|live|logs|news|nodeGraph|piechart|pluginlist|stat|state-timeline|status-history|table|table-old|text|timeseries|traces|welcome|xychart|alertmanager|cloudwatch|dashboard|elasticsearch|grafana|grafana-azure-monitor-datasource|graphite|influxdb|jaeger|loki|mixed|mssql|mysql|opentsdb|postgres|prometheus|stackdriver|tempo|testdata|zipkin|phlare|parca)$" + // Human-readable name of the plugin that is shown to the user in + // the UI. + name: string + // The set of all plugin types. This hidden field exists solely // so that the set can be string-interpolated into other fields. _types: ["app", "datasource", "panel", "renderer", "secretsmanager"] @@ -31,9 +35,116 @@ seqs: [ // a superset of plugin types. #IncludeType: type | "dashboard" | "page" - // Human-readable name of the plugin that is shown to the user in - // the UI. - name: string + // Metadata about the plugin + info: #Info + + // Metadata about a Grafana plugin. Some fields are used on the plugins + // page in Grafana and others on grafana.com, if the plugin is published. + #Info: { + // Information about the plugin author + author?: { + // Author's name + name?: string + + // Author's name + email?: string + + // Link to author's website + url?: string + } + + // Build information + build?: #BuildInfo + + // Description of plugin. Used on the plugins page in Grafana and + // for search on grafana.com. + description?: string + + // Array of plugin keywords. Used for search on grafana.com. + keywords: [...string] + // should be this, but CUE to openapi converter screws this up + // by inserting a non-concrete default. + // keywords: [string, ...string] + + // An array of link objects to be displayed on this plugin's + // project page in the form `{name: 'foo', url: + // 'http://example.com'}` + links?: [...{ + name?: string + url?: string + }] + + // SVG images that are used as plugin icons + logos?: { + // Link to the "small" version of the plugin logo, which must be + // an SVG image. "Large" and "small" logos can be the same image. + small: string + + // Link to the "large" version of the plugin logo, which must be + // an SVG image. "Large" and "small" logos can be the same image. + large: string + } + + // An array of screenshot objects in the form `{name: 'bar', path: + // 'img/screenshot.png'}` + screenshots?: [...{ + name?: string + path?: string + }] + + // Date when this plugin was built + updated?: =~"^(\\d{4}-\\d{2}-\\d{2}|\\%TODAY\\%)$" + + // Project version of this commit, e.g. `6.7.x` + version?: =~"^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)|(\\%VERSION\\%)$" + } + + #BuildInfo: { + // Time when the plugin was built, as a Unix timestamp + time?: int64 + repo?: string + + // Git branch the plugin was built from + branch?: string + + // Git hash of the commit the plugin was built from + hash?: string + "number"?: int64 + + // GitHub pull request the plugin was built from + pr?: int32 + } + + // Dependency information related to Grafana and other plugins + dependencies: #Dependencies + + #Dependencies: { + // (Deprecated) Required Grafana version for this plugin, e.g. + // `6.x.x 7.x.x` to denote plugin requires Grafana v6.x.x or + // v7.x.x. + grafanaVersion?: =~"^([0-9]+)(\\.[0-9x]+)?(\\.[0-9x])?$" + + // Required Grafana version for this plugin. Validated using + // https://github.com/npm/node-semver. + grafanaDependency: =~"^(<=|>=|<|>|=|~|\\^)?([0-9]+)(\\.[0-9x\\*]+)(\\.[0-9x\\*]+)?(\\s(<=|>=|<|=>)?([0-9]+)(\\.[0-9x]+)(\\.[0-9x]+))?$" + + // An array of required plugins on which this plugin depends + plugins?: [...#Dependency] + } + + // Dependency describes another plugin on which a plugin depends. + // The id refers to the plugin package identifier, as given on + // the grafana.com plugin marketplace. + #Dependency: { + id: =~"^[0-9a-z]+\\-([0-9a-z]+\\-)?(app|panel|datasource)$" + type: "app" | "datasource" | "panel" + name: string + version: string + ... + } + + // Schema definition for the plugin.json file. Used primarily for schema validation. + $schema?: string // FIXME there appears to be a bug in thema that prevents this from working. Maybe it'd // help to refer to it with an alias, but thema can't support using current list syntax. @@ -194,114 +305,6 @@ seqs: [ // in turn inherits them from the Viewer basic role. #BasicRole: "Grafana Admin" | "Admin" | "Editor" | "Viewer" - // Dependencies needed by the plugin. - dependencies: #Dependencies - - #Dependencies: { - // (Deprecated) Required Grafana version for this plugin, e.g. - // `6.x.x 7.x.x` to denote plugin requires Grafana v6.x.x or - // v7.x.x. - grafanaVersion?: =~"^([0-9]+)(\\.[0-9x]+)?(\\.[0-9x])?$" - - // Required Grafana version for this plugin. Validated using - // https://github.com/npm/node-semver. - grafanaDependency: =~"^(<=|>=|<|>|=|~|\\^)?([0-9]+)(\\.[0-9x\\*]+)(\\.[0-9x\\*]+)?(\\s(<=|>=|<|=>)?([0-9]+)(\\.[0-9x]+)(\\.[0-9x]+))?$" - - // An array of required plugins on which this plugin depends. - plugins?: [...#Dependency] - } - - // Dependency describes another plugin on which a plugin depends. - // The id refers to the plugin package identifier, as given on - // the grafana.com plugin marketplace. - #Dependency: { - id: =~"^[0-9a-z]+\\-([0-9a-z]+\\-)?(app|panel|datasource)$" - type: "app" | "datasource" | "panel" - name: string - version: string - ... - } - - // Metadata about the plugin. - info: #Info - - // Metadata about a Grafana plugin. Some fields are used on the plugins - // page in Grafana and others on grafana.com, if the plugin is published. - #Info: { - // Information about the plugin author. - author?: { - // Author's name. - name?: string - - // Author's name. - email?: string - - // Link to author's website. - url?: string - } - - // Build information - build?: #BuildInfo - - // Description of plugin. Used on the plugins page in Grafana and - // for search on grafana.com. - description?: string - - // Array of plugin keywords. Used for search on grafana.com. - keywords: [...string] - // should be this, but CUE to openapi converter screws this up - // by inserting a non-concrete default. - // keywords: [string, ...string] - - // An array of link objects to be displayed on this plugin's - // project page in the form `{name: 'foo', url: - // 'http://example.com'}` - links?: [...{ - name?: string - url?: string - }] - - // SVG images that are used as plugin icons. - logos?: { - // Link to the "small" version of the plugin logo, which must be - // an SVG image. "Large" and "small" logos can be the same image. - small: string - - // Link to the "large" version of the plugin logo, which must be - // an SVG image. "Large" and "small" logos can be the same image. - large: string - } - - // An array of screenshot objects in the form `{name: 'bar', path: - // 'img/screenshot.png'}` - screenshots?: [...{ - name?: string - path?: string - }] - - // Date when this plugin was built. - updated?: =~"^(\\d{4}-\\d{2}-\\d{2}|\\%TODAY\\%)$" - - // Project version of this commit, e.g. `6.7.x`. - version?: =~"^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)|(\\%VERSION\\%)$" - } - - #BuildInfo: { - // Time when the plugin was built, as a Unix timestamp. - time?: int64 - repo?: string - - // Git branch the plugin was built from. - branch?: string - - // Git hash of the commit the plugin was built from - hash?: string - "number"?: int64 - - // GitHub pull request the plugin was built from - pr?: int32 - } - // For data source plugins. There is a query options section in // the plugin's query editor and these options can be turned on // if needed. diff --git a/pkg/plugins/plugindef/plugindef_types_gen.go b/pkg/plugins/plugindef/plugindef_types_gen.go index 6074c2db4ee..6a19e32a452 100644 --- a/pkg/plugins/plugindef/plugindef_types_gen.go +++ b/pkg/plugins/plugindef/plugindef_types_gen.go @@ -78,7 +78,7 @@ type BasicRole string // BuildInfo defines model for BuildInfo. type BuildInfo struct { - // Git branch the plugin was built from. + // Git branch the plugin was built from Branch *string `json:"branch,omitempty"` // Git hash of the commit the plugin was built from @@ -89,7 +89,7 @@ type BuildInfo struct { Pr *int32 `json:"pr,omitempty"` Repo *string `json:"repo,omitempty"` - // Time when the plugin was built, as a Unix timestamp. + // Time when the plugin was built, as a Unix timestamp Time *int64 `json:"time,omitempty"` } @@ -104,7 +104,7 @@ type Dependencies struct { // v7.x.x. GrafanaVersion *string `json:"grafanaVersion,omitempty"` - // An array of required plugins on which this plugin depends. + // An array of required plugins on which this plugin depends Plugins []Dependency `json:"plugins,omitempty"` } @@ -172,15 +172,15 @@ type IncludeType string // Metadata about a Grafana plugin. Some fields are used on the plugins // page in Grafana and others on grafana.com, if the plugin is published. type Info struct { - // Information about the plugin author. + // Information about the plugin author Author *struct { - // Author's name. + // Author's name Email *string `json:"email,omitempty"` - // Author's name. + // Author's name Name *string `json:"name,omitempty"` - // Link to author's website. + // Link to author's website Url *string `json:"url,omitempty"` } `json:"author,omitempty"` Build *BuildInfo `json:"build,omitempty"` @@ -200,7 +200,7 @@ type Info struct { Url *string `json:"url,omitempty"` } `json:"links,omitempty"` - // SVG images that are used as plugin icons. + // SVG images that are used as plugin icons Logos *struct { // Link to the "large" version of the plugin logo, which must be // an SVG image. "Large" and "small" logos can be the same image. @@ -218,10 +218,10 @@ type Info struct { Path *string `json:"path,omitempty"` } `json:"screenshots,omitempty"` - // Date when this plugin was built. + // Date when this plugin was built Updated *string `json:"updated,omitempty"` - // Project version of this commit, e.g. `6.7.x`. + // Project version of this commit, e.g. `6.7.x` Version *string `json:"version,omitempty"` } @@ -249,6 +249,9 @@ type Permission struct { // PluginDef defines model for PluginDef. type PluginDef struct { + // Schema definition for the plugin.json file. Used primarily for schema validation. + Schema *string `json:"$schema,omitempty"` + // For data source plugins, if the plugin supports alerting. Alerting *bool `json:"alerting,omitempty"` @@ -296,7 +299,7 @@ type PluginDef struct { HideFromList bool `json:"hideFromList"` // Unique name of the plugin. If the plugin is published on - // grafana.com, then the plugin id has to follow the naming + // grafana.com, then the plugin `id` has to follow the naming // conventions. Id string `json:"id"`