perses-datasource-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Perses Datasource Management

Perses 数据源管理

Create, update, and manage datasources across scopes.

跨范围创建、更新和管理数据源。

Operator Context

操作上下文

This skill operates as the lifecycle manager for Perses datasources, handling creation, updates, and deletion across global, project, and dashboard scopes.

该技能作为 Perses 数据源的生命周期管理器，负责在全局、项目和仪表板范围内处理数据源的创建、更新和删除操作。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Scope-aware: Always clarify scope — global (all projects), project, or dashboard — because scope determines resource kind and override priority
MCP-first: Use Perses MCP tools when available, percli as fallback
Proxy configuration: Always configure allowedEndpoints for HTTP proxy datasources — without them, queries will be blocked by the proxy

感知范围：始终明确范围——全局（所有项目）、项目或仪表板——因为范围决定了资源类型和覆盖优先级
优先MCP：若 Perses MCP 工具可用则优先使用，否则使用 percli 作为备选
代理配置：始终为 HTTP 代理数据源配置 allowedEndpoints——若未配置，查询将被代理阻止

Default Behaviors (ON unless disabled)

默认行为（默认开启，可禁用）

Global scope: Default to global datasource unless project is specified
Default flag: Set first datasource of each type as default

全局范围：除非指定项目，否则默认创建全局数据源
默认标记：将每种类型的第一个数据源设置为默认数据源

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需启用）

Multi-backend: Configure multiple datasources of the same type with different names
Dashboard-scoped: Embed datasource config directly in dashboard spec

多后端：配置多个同类型但不同名称的数据源
仪表板范围：将数据源配置直接嵌入仪表板规格中

What This Skill CAN Do

该技能可执行的操作

Create/update/delete datasources at any scope
Configure HTTP proxy with allowed endpoints
Manage datasource priority (global vs project vs dashboard)
Support all 6 datasource types: Prometheus, Tempo, Loki, Pyroscope, ClickHouse, VictoriaLogs

在任意范围创建/更新/删除数据源
配置带允许端点的 HTTP 代理
管理数据源优先级（全局 vs 项目 vs 仪表板）
支持全部6种数据源类型：Prometheus、Tempo、Loki、Pyroscope、ClickHouse、VictoriaLogs

What This Skill CANNOT Do

该技能不可执行的操作

Create the datasource backends themselves (Prometheus, Loki, etc.)
Manage Perses server configuration (use perses-deploy)
Create dashboards (use perses-dashboard-create)

无法创建数据源后端本身（如 Prometheus、Loki 等）
无法管理 Perses 服务器配置（请使用 perses-deploy）
无法创建仪表板（请使用 perses-dashboard-create）

Instructions

操作说明

Phase 1: IDENTIFY

阶段1：确定需求

Goal: Determine datasource type, scope, and connection details.

Supported types:

Plugin Kind	Backend	Common Endpoints
PrometheusDatasource	Prometheus	`/api/v1/.*`
TempoDatasource	Tempo	`/api/traces/.*` , `/api/search`
LokiDatasource	Loki	`/loki/api/v1/.*`
PyroscopeDatasource	Pyroscope	`/pyroscope/.*`
ClickHouseDatasource	ClickHouse	N/A (direct connection)
VictoriaLogsDatasource	VictoriaLogs	`/select/.*`

Scopes (priority order, highest first): Dashboard > Project > Global

A dashboard-scoped datasource overrides a project-scoped one of the same name, which overrides a global one. Use global for organization-wide defaults, project for team-specific overrides, dashboard for one-off configurations.

Gate: Type, scope, and connection URL identified. Proceed to Phase 2.

目标：确定数据源类型、范围和连接详情。

支持的类型：

插件类型	后端	常用端点
PrometheusDatasource	Prometheus	`/api/v1/.*`
TempoDatasource	Tempo	`/api/traces/.*` , `/api/search`
LokiDatasource	Loki	`/loki/api/v1/.*`
PyroscopeDatasource	Pyroscope	`/pyroscope/.*`
ClickHouseDatasource	ClickHouse	N/A (direct connection)
VictoriaLogsDatasource	VictoriaLogs	`/select/.*`

范围（优先级从高到低）：仪表板 > 项目 > 全局

同名称的仪表板范围数据源会覆盖项目范围数据源，而项目范围数据源会覆盖全局范围数据源。全局范围适用于组织级默认配置，项目范围适用于团队专属的覆盖配置，仪表板范围适用于一次性配置。

准入条件：已确定类型、范围和连接URL。进入阶段2。

Phase 2: CREATE

阶段2：创建数据源

Goal: Create the datasource resource.

Via MCP (preferred):

perses_create_global_datasource(name="prometheus", type="PrometheusDatasource", url="http://prometheus:9090")

Via percli (GlobalDatasource):

bash

percli apply -f - <<EOF
kind: GlobalDatasource
metadata:
  name: prometheus
spec:
  default: true
  plugin:
    kind: PrometheusDatasource
    spec:
      proxy:
        kind: HTTPProxy
        spec:
          url: http://prometheus:9090
          allowedEndpoints:
            - endpointPattern: /api/v1/.*
              method: POST
            - endpointPattern: /api/v1/.*
              method: GET
EOF

Via percli (Project-scoped Datasource):

bash

percli apply -f - <<EOF
kind: Datasource
metadata:
  name: prometheus
  project: <project-name>
spec:
  default: true
  plugin:
    kind: PrometheusDatasource
    spec:
      proxy:
        kind: HTTPProxy
        spec:
          url: http://prometheus:9090
          allowedEndpoints:
            - endpointPattern: /api/v1/.*
              method: POST
            - endpointPattern: /api/v1/.*
              method: GET
EOF

Gate: Datasource created without errors. Proceed to Phase 3.

目标：创建数据源资源。

通过MCP（优先方式）：

perses_create_global_datasource(name="prometheus", type="PrometheusDatasource", url="http://prometheus:9090")

通过percli（全局数据源）：

bash

percli apply -f - <<EOF
kind: GlobalDatasource
metadata:
  name: prometheus
spec:
  default: true
  plugin:
    kind: PrometheusDatasource
    spec:
      proxy:
        kind: HTTPProxy
        spec:
          url: http://prometheus:9090
          allowedEndpoints:
            - endpointPattern: /api/v1/.*
              method: POST
            - endpointPattern: /api/v1/.*
              method: GET
EOF

通过percli（项目范围数据源）：

bash

percli apply -f - <<EOF
kind: Datasource
metadata:
  name: prometheus
  project: <project-name>
spec:
  default: true
  plugin:
    kind: PrometheusDatasource
    spec:
      proxy:
        kind: HTTPProxy
        spec:
          url: http://prometheus:9090
          allowedEndpoints:
            - endpointPattern: /api/v1/.*
              method: POST
            - endpointPattern: /api/v1/.*
              method: GET
EOF

准入条件：数据源创建无错误。进入阶段3。

Phase 3: VERIFY

阶段3：验证

Goal: Confirm the datasource exists and is accessible.

bash

undefined

目标：确认数据源已存在且可访问。

bash

undefined

Global datasources

全局数据源

percli get globaldatasource

Project datasources

项目数据源

percli get datasource --project <project>

Describe specific datasource

查看具体数据源详情

percli describe globaldatasource <name>

Test proxy connectivity (global)

测试代理连通性（全局）

curl -s http://localhost:8080/proxy/globaldatasources/<name>/api/v1/query?query=up

Test proxy connectivity (project-scoped)

测试代理连通性（项目范围）

curl -s http://localhost:8080/proxy/projects/<project>/datasources/<name>/api/v1/query?query=up


Or via MCP:

perses_list_global_datasources() perses_list_datasources(project="<project>")


**Gate**: Datasource listed and configuration confirmed. Task complete.

---

curl -s http://localhost:8080/proxy/projects/<project>/datasources/<name>/api/v1/query?query=up


或通过MCP：

perses_list_global_datasources() perses_list_datasources(project="<project>")


**准入条件**：数据源已列出且配置确认无误。任务完成。

---

Error Handling

错误处理

Symptom	Cause	Solution
Datasource proxy returns 403 Forbidden	`allowedEndpoints` not configured, or the HTTP method in the endpoint pattern does not match the request method (e.g., only GET defined but query uses POST)	Add the missing endpoint patterns to `spec.plugin.spec.proxy.spec.allowedEndpoints` . Prometheus needs both GET and POST for `/api/v1/.` . Tempo needs GET for `/api/traces/.` and POST for `/api/search`
MCP tool `perses_create_global_datasource` fails with conflict/already exists	A GlobalDatasource with that name already exists	Use `perses_update_global_datasource` instead, or delete the existing one first with `percli delete globaldatasource <name>` . To check: `perses_list_global_datasources()`
MCP tool fails with invalid plugin kind	The `type` parameter does not match a registered plugin kind exactly	Use the exact casing: `PrometheusDatasource` , `TempoDatasource` , `LokiDatasource` , `PyroscopeDatasource` , `ClickHouseDatasource` , `VictoriaLogsDatasource` . These are case-sensitive
Datasource connectivity test fails (proxy returns 502/504)	Backend URL is unreachable from the Perses server. The server cannot connect to the datasource backend at the configured URL	Verify the backend URL is reachable from the Perses server's network context. For Docker, use `host.docker.internal` or the container network name instead of `localhost` . For K8s, use the service DNS name (e.g., `http://prometheus.monitoring.svc:9090` )
Proxy returns TLS handshake error	Backend uses HTTPS but Perses cannot verify the certificate (self-signed or missing CA)	For self-signed certs, configure the CA in the Perses server's trust store or set the `PERSES_DATASOURCE_SKIP_TLS_VERIFY` environment variable if available. Prefer fixing the cert chain over disabling verification
Project datasource does not override global datasource	The project datasource `metadata.name` does not match the global datasource name exactly. Override only works when names are identical	Ensure the project-scoped `Datasource` has the exact same `metadata.name` as the `GlobalDatasource` it should override. Names are case-sensitive

症状	原因	解决方案
数据源代理返回 403 Forbidden	未配置 `allowedEndpoints` ，或端点模式中的HTTP方法与请求方法不匹配（例如仅定义了GET但查询使用POST）	向 `spec.plugin.spec.proxy.spec.allowedEndpoints` 添加缺失的端点模式。Prometheus的 `/api/v1/.` 需要同时配置GET和POST方法。Tempo的 `/api/traces/.` 需要GET方法， `/api/search` 需要POST方法
MCP工具 `perses_create_global_datasource` 返回conflict/already exists错误	同名全局数据源已存在	改用 `perses_update_global_datasource` ，或先使用 `percli delete globaldatasource <name>` 删除现有数据源。可通过 `perses_list_global_datasources()` 查询现有数据源
MCP工具返回invalid plugin kind错误	`type` 参数与已注册的插件类型不完全匹配	使用精确的大小写格式： `PrometheusDatasource` 、 `TempoDatasource` 、 `LokiDatasource` 、 `PyroscopeDatasource` 、 `ClickHouseDatasource` 、 `VictoriaLogsDatasource` 。这些类型区分大小写
数据源连通性测试失败（代理返回502/504）	Perses服务器无法访问配置的后端URL	验证后端URL在Perses服务器的网络环境中是否可达。对于Docker环境，使用 `host.docker.internal` 或容器网络名称代替 `localhost` ；对于K8s环境，使用服务DNS名称（例如 `http://prometheus.monitoring.svc:9090` ）
代理返回TLS handshake error	后端使用HTTPS但Perses无法验证证书（自签名证书或缺少CA证书）	对于自签名证书，可在Perses服务器的信任存储中配置CA证书，或在允许的情况下设置 `PERSES_DATASOURCE_SKIP_TLS_VERIFY` 环境变量。优先修复证书链而非禁用验证
项目范围数据源未覆盖全局数据源	项目数据源的 `metadata.name` 与全局数据源名称不完全一致。仅当名称完全相同时，覆盖才会生效	确保项目范围 `Datasource` 的 `metadata.name` 与要覆盖的 `GlobalDatasource` 名称完全一致。名称区分大小写

Anti-Patterns

反模式

Anti-Pattern	Why It Fails	Do This Instead
Creating all datasources at global scope	Pollutes the namespace, makes per-team access control impossible, and forces every project to see every datasource	Use global scope only for organization-wide defaults. Use project-scoped datasources for team-specific backends
Omitting `allowedEndpoints` on HTTP proxy datasources	Queries are blocked silently — the proxy returns 403 with no useful error message in dashboards, making debugging difficult	Always define `allowedEndpoints` with both the `endpointPattern` regex and `method` for every HTTP proxy datasource
Not setting `default: true` on the primary datasource	Dashboard panels cannot auto-discover the datasource. Users must manually select it in every panel, and panel YAML must hardcode the datasource name	Set `default: true` on exactly one datasource per plugin kind per scope. If you have multiple Prometheus datasources, designate one as default
Using dashboard-scoped datasources when project scope would enable reuse	Dashboard-scoped datasource config is embedded in the dashboard JSON and cannot be shared. Every dashboard that needs it must duplicate the config	Use project-scoped datasources for any datasource used by more than one dashboard. Reserve dashboard scope for true one-off test configurations
Hardcoding `localhost` URLs in non-local deployments	Breaks when Perses runs in Docker or Kubernetes because `localhost` refers to the container, not the host	Use container/service names: Docker network names for Compose, K8s service DNS for Helm deployments

反模式	失败原因	正确做法
所有数据源都创建在全局范围	会污染命名空间，无法实现按团队的访问控制，且每个项目都会看到所有数据源	仅将全局范围用于组织级默认配置，为团队专属后端使用项目范围数据源
HTTP代理数据源省略 `allowedEndpoints`	查询会被静默阻止——代理返回403错误，但仪表板中无有用错误信息，调试难度大	始终为每个HTTP代理数据源定义包含 `endpointPattern` 正则表达式和 `method` 的 `allowedEndpoints`
未为主数据源设置 `default: true`	仪表板面板无法自动发现数据源。用户必须在每个面板中手动选择，且面板YAML必须硬编码数据源名称	在每个范围的每种插件类型中，为恰好一个数据源设置 `default: true` 。若有多个Prometheus数据源，指定其中一个为默认
当项目范围可实现复用仍使用仪表板范围数据源	仪表板范围数据源配置嵌入在仪表板JSON中，无法共享。每个需要该数据源的仪表板都必须重复配置	对于被多个仪表板使用的数据源，使用项目范围数据源。仅将仪表板范围用于真正的一次性测试配置
在非本地部署中硬编码 `localhost` URL	当Perses运行在Docker或Kubernetes中时会失效，因为 `localhost` 指的是容器而非主机	使用容器/服务名称：Compose环境使用Docker网络名称，Helm部署使用K8s服务DNS

Anti-Rationalization

错误认知纠正

Rationalization	Why It's Wrong	Required Action
"The datasource was created successfully, so it must be working"	Creation succeeding only means the API accepted the resource definition. It does not validate that the backend URL is reachable or that allowedEndpoints are correct	Test the proxy endpoint with a real query: `curl` the `/proxy/globaldatasources/<name>/...` path and verify a non-error response
"I don't need allowedEndpoints because I'm only doing GET requests"	Prometheus `/api/v1/query_range` and `/api/v1/labels` use POST for large payloads. Loki and Tempo also mix methods. A GET-only config breaks silently on certain queries	Always configure both GET and POST for the relevant endpoint patterns unless the datasource documentation explicitly states only one method is used
"Global scope is fine — we can always move it later"	Moving from global to project scope requires deleting the global datasource and recreating it as project-scoped. All dashboards referencing it by name will keep working only if the project datasource name matches exactly. This is a disruptive migration	Choose scope deliberately at creation time. Ask: "Does every project need this, or just one team?"
"The datasource type name is probably case-insensitive"	Plugin kind names are case-sensitive Go type identifiers. `prometheusdatasource` or `prometheus` will fail with an unhelpful "invalid plugin kind" error	Use exact casing: `PrometheusDatasource` , `TempoDatasource` , etc. Copy from the supported types table

错误认知	错误原因	必要操作
"数据源创建成功，所以肯定能正常工作"	创建成功仅表示API接受了资源定义，不验证后端URL是否可达或 `allowedEndpoints` 是否配置正确	测试代理端点：使用真实查询调用 `/proxy/globaldatasources/<name>/...` 路径，验证返回非错误响应
"我不需要配置 `allowedEndpoints` ，因为只做GET请求"	Prometheus的 `/api/v1/query_range` 和 `/api/v1/labels` 会为大负载使用POST请求。Loki和Tempo也会混合使用方法。仅配置GET会导致某些查询静默失败	始终配置GET和POST相关端点模式，除非数据源文档明确说明仅使用一种方法
"全局范围没问题——以后可以再迁移"	从全局范围迁移到项目范围需要删除全局数据源并重新创建为项目范围数据源。所有引用该数据源的仪表板仅在名称完全相同时才能继续工作。这是一项破坏性迁移	创建时谨慎选择范围：询问自己「所有项目都需要这个数据源，还是只有一个团队需要？」
"数据源类型名称应该不区分大小写"	插件类型名称是区分大小写的Go类型标识符。 `prometheusdatasource` 或 `prometheus` 会返回无帮助的「invalid plugin kind」错误	使用精确的大小写： `PrometheusDatasource` 、 `TempoDatasource` 等。从支持类型表格中复制

FORBIDDEN Patterns

禁止模式

These patterns cause silent failures, data loss, or security issues. Never use them.

NEVER create a datasource without
```
allowedEndpoints
```
on HTTP proxy types — results in silent 403 on all queries
NEVER use
```
method: *
```
or omit the
```
method
```
field in allowedEndpoints — the Perses proxy requires explicit method matching
NEVER set
```
default: true
```
on multiple datasources of the same plugin kind at the same scope — behavior is undefined and varies between Perses versions
NEVER embed secrets (passwords, tokens) in datasource YAML committed to version control — use Perses native auth or external secret management
NEVER delete a global datasource without checking which projects and dashboards reference it — use
```
percli get datasource --project <project>
```
across all projects first

这些模式会导致静默失败、数据丢失或安全问题。切勿使用。

切勿创建未配置
```
allowedEndpoints
```
的HTTP代理类型数据源——会导致所有查询返回静默403错误
切勿在
```
allowedEndpoints
```
中使用
```
method: *
```
或省略
```
method
```
字段——Perses代理要求明确的方法匹配
切勿在同一范围的同类型插件数据源中设置多个
```
default: true
```
——行为未定义，且在不同Perses版本中表现不同
切勿将密钥（密码、令牌）嵌入提交到版本控制的数据源YAML中——使用Perses原生认证或外部密钥管理工具
切勿在未检查哪些项目和仪表板引用全局数据源的情况下删除它——先在所有项目中执行
```
percli get datasource --project <project>
```
查询

Blocker Criteria

阻塞条件

Stop and escalate to the user if ANY of these conditions are true:

Backend URL is unknown or unresolvable — cannot create a functional datasource without a reachable backend
Datasource type is not one of the 6 supported plugin kinds — Perses does not support arbitrary datasource plugins without custom plugin development
User requests a datasource plugin kind that is not installed on the Perses server — verify available plugins before attempting creation
Proxy test returns persistent 5xx errors after datasource creation — indicates infrastructure issues beyond datasource configuration
User wants to delete a global datasource used by multiple projects — requires explicit confirmation of the blast radius

如果满足以下任一条件，请停止操作并告知用户：

后端URL未知或无法解析——没有可达的后端无法创建可用的数据源
数据源类型不是6种支持的插件类型之一——Perses不支持自定义插件开发之外的任意数据源插件
用户请求的数据源插件类型未安装在Perses服务器上——创建前先验证可用插件
数据源创建后代理测试持续返回5xx错误——表示存在超出数据源配置范围的基础设施问题
用户想要删除被多个项目使用的全局数据源——需要明确确认影响范围

References

参考资料

Resource	URL
Perses datasource documentation	https://perses.dev/docs/user-guides/datasources/
Perses HTTP proxy configuration	https://perses.dev/docs/user-guides/datasources/#http-proxy
Perses API: GlobalDatasource	https://perses.dev/docs/api/datasource/
Perses MCP server (datasource tools)	https://github.com/perses/perses-mcp-server
percli reference	https://perses.dev/docs/user-guides/percli/
Perses GitHub repository	https://github.com/perses/perses

资源	链接
Perses 数据源文档	https://perses.dev/docs/user-guides/datasources/
Perses HTTP代理配置	https://perses.dev/docs/user-guides/datasources/#http-proxy
Perses API: GlobalDatasource	https://perses.dev/docs/api/datasource/
Perses MCP服务器（数据源工具）	https://github.com/perses/perses-mcp-server
percli 参考文档	https://perses.dev/docs/user-guides/percli/
Perses GitHub仓库	https://github.com/perses/perses