企业官网建设流程全解析

Grafana 如何将已废弃的 API keys 迁移为 service account tokens

【免费下载链接】grafanaThe open and composable observability and data visualization platform. Visualize metrics, logs, and traces from multiple sources like Prometheus, Loki, Elasticsearch, InfluxDB, Postgres and many more.项目地址: https://gitcode.com/GitHub_Trending/gr/grafana

Grafana 中的 API keys 已废弃，现在由 service accounts 取代，用于对HTTP APIs认证并与 Grafana 交互。如果你的自动化脚本、Terraform 配置或外部工具仍在通过 API key 访问 Grafana，就需要把这些 key 迁移为 service account token（SAT）。本文覆盖三条迁移路径：Grafana 用户界面、HTTP API 和 Terraform，并说明迁移后如何找到新 token、如何验证其可用。

迁移一个 API key 后，系统会创建一个带 service account token 的 service account，你原有的 API key 在迁移为 service account token 后仍按原方式继续工作。

迁移前的权限准备

无论走 UI 还是 HTTP API 路径，执行迁移的操作者需要具备以下权限之一：

• Administrator permissions
• Editor permissions
• Service account writer

关于权限的详细说明见 Roles and permissions。

通过 Grafana 用户界面迁移

UI 支持两种粒度：一次性迁移全部 API keys，或只迁移单个 API key。

前提说明：当你选择迁移全部 API keys 后，将不能再创建 API key，此后必须使用 service accounts。执行前请确认这一点可接受。

迁移所有 API keys

1. 登录 Grafana，指向Administration，进入Users and access，点击API Keys。
2. 在页面顶部找到Switch from API keys to service accounts区块。
3. 点击Migrate to service accounts now。
4. 弹出确认窗口要求确认迁移。若愿意继续，点击Yes, migrate now。
5. 迁移成功后，可以选择永久隐藏 API keys 页面。如需隐藏，点击Hide API keys page forever。

迁移单个 API key

1. 登录 Grafana，点击左侧菜单Administration，进入Users and access，选择API Keys。
2. 找到要迁移的 API Key。
3. 点击Migrate to service account。

找到迁移后的 token

迁移完成后，点击左侧菜单Administration，进入Users and access -> Service Accounts，选中对应的 service account，在Token处即可找到迁移后生成的 token。

通过 HTTP API 迁移

如果你的 key 是由程序创建的（例如通过POST /api/auth/keys），迁移动作也应通过 API 完成。整体流程：

1. 调用POST /api/serviceaccounts端点和POST /api/serviceaccounts/<id>/tokens。这会生成一个 service account token。
2. 保存系统返回的 ID 和 secret。
3. 在Authorizationheader 中传递 token，加Bearer前缀。这一步用于认证 API 请求。
4. 后续认证改用 SAT（service account token）。
5. 移除处理旧/api/auth/keys端点的代码。
6. 跟踪在用的 API keys 并逐一迁移为 SAT。

下面的示例来自官方文档，展示了旧设置与新设置的完整对照（响应均为文档示例，实际返回的id和key不同）：

旧设置——通过 Basic Auth 创建 API key：

curl -X POST -H "Content-Type: application/json" -d '{"name": "my-api-key", "role": "Viewer"}' http://admin:admin@localhost:3000/api/auth/keys # response from the api {"id":2,"name":"my-api-key","key":"eyJrIjoiTFRSN1RBOVc3SGhjblc0bWZodXZ3MnNDcU92Um5VZUIiLKJuIjoibXktYXBpLWtleSIsImlkIjoxfQ=="}%

新设置——创建 service account 并生成 token：

# create a service account curl -X POST -H "Content-Type: application/json" -d '{"name": "my-service-account", "role": "Viewer"}' http://admin:admin@localhost:3000/api/serviceaccounts # response with the created service account id,name, login {"id":1,"name":"my-service-account","login":"sa-my-service-account","orgId":1,"isDisabled":false,"role":"Viewer","tokens":0,"avatarUrl":""}% # create the service account token with the service account id 1 - /serviceaccounts/{id} returned from the previous step curl -X POST -H "Content-Type: application/json" -d '{"name": "my-service-account-token"}' http://admin:admin@localhost:3000/api/serviceaccounts/1/tokens # response with the created SAT id,name and key. {"id":2,"name":"my-service-account-token","key":"glsa_iNValIdinValiDinvalidinvalidinva_5b582697"}% # now you can authenticate the same way as you did with the API key curl --request GET --url http://localhost:3000/api/folders --header 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' # response [{"id":1,"uid":"a5261a84-eebc-4733-83a9-61f4713561d1","title":"gdev dashboards"}]%

示例中的admin:admin@localhost:3000是文档用的本地实例凭据，请替换为你自己的 Grafana 地址与认证凭据；/api/serviceaccounts/1/tokens中的1必须替换为上一步创建 service account 时返回的id。

通过 Terraform 迁移

如果你用 Terraform 管理 API key，需要先处理一个版本兼容问题：Grafana Terraform Provider 在 v3.0.0 中移除了api_key资源。在你完成迁移并移除该资源之前，应先将 Terraform provider 版本锁定为小于或等于 v2.19.0：

terraform { required_providers { grafana = { source = "grafana/grafana" version = "2.19.0" } } }

迁移步骤

1. 生成grafana_service_account和grafana_service_account_token资源。
2. 创建 service account 时指定所需的 scopes 和过期时间。
3. 使用grafana_service_account_token返回的 token 来认证 API 请求。
4. 移除创建grafana_api_key资源的 Terraform 配置。

现有的旧配置（文档示例）：

terraform { required_providers { grafana = { source = "grafana/grafana" } } } # configure the provider with basic auth provider "grafana" { url = "http://localhost:3000" auth = "admin:admin" } resource "grafana_api_key" "foo" { name = "key_foo" role = "Viewer" } resource "grafana_api_key" "bar" { name = "key_bar" role = "Admin" seconds_to_live = 30 }

迁移后的新配置（一个 service account 可以挂多个 token，文档示例）：

terraform { required_providers { grafana = { source = "grafana/grafana" } } } # configure the provider with basic auth provider "grafana" { url = "http://localhost:3000" auth = "admin:admin" } # Creating a service account in Grafana instance to be used as auth and attach tokens # notice we can attach multiple tokens to one service account resource "grafana_service_account" "sa-admin" { name = "sa-admin" role = "Admin" } # Creating a service account token in Grafana instance to be used for creating resources in Grafana instance resource "grafana_service_account_token" "sat-bar" { name = "sat-bar" service_account_id = grafana_service_account.sa-admin.id } # Creating a service account token in Grafana instance to be used for creating resources in Grafana instance resource "grafana_service_account_token" "sat-foo" { name = "sat-foo" service_account_id = grafana_service_account.sa-admin.id seconds_to_live = 30 }

Grafana Cloud Stack API keys 的 Terraform 迁移（可选分支）

如果你管理的是 Grafana CloudStack的 API key（grafana_cloud_stack_api_key），迁移方式与上面类似，改用grafana_cloud_stack_service_account和grafana_cloud_stack_service_account_token资源：

1. 生成上述两个资源。
2. 创建时指定 scopes 和过期时间。
3. 使用grafana_cloud_stack_service_account_token返回的 token 认证 API 请求。
4. 移除grafana_cloud_stack_api_key资源的 Terraform 配置。

注意：这只与 Grafana CloudStackAPI key 有关。Grafana Cloud API key 资源grafana_cloud_api_key并未废弃，仍应用于管理 Grafana Cloud 本身的认证，不要混淆两者。

迁移后的 Cloud Stack 配置（文档示例）：

terraform { required_providers { grafana = { source = "grafana/grafana" } } } # Declaring the first provider to be only used for creating the cloud-stack provider "grafana" { alias = "cloud" cloud_api_key = "<API-Key>" } resource "grafana_cloud_stack" "my_stack" { provider = grafana.cloud name = "my_stack" slug = "my_stack" region_slug = "eu" # Example “us”,”eu” etc } # Creating a grafana cloud stack service account resource "grafana_cloud_stack_service_account" "mystack_cloud-stack_service_account" { provider = grafana.cloud stack_slug = grafana_cloud_stack.my_stack.slug name = "mystack-cloud-stack-sa" role = "Admin" } # Creating a grafana cloud stack service account token resource "grafana_cloud_stack_service_account_token" "mystack_cloud-stack_service-account_token" { provider = grafana.cloud stack_slug = grafana_cloud_stack.my_stack.slug name = "mystack-cloud-stack-sa-token" service_account_id = grafana_cloud_stack_service_account.mystack_cloud-stack_service_account.id }

其中<API-Key>是你现有的 Grafana Cloud API key，执行前需自行替换。

迁移后的验证

迁移完成后，用新 token 请求一个只读端点确认认证生效，例如：

curl --request GET --url http://localhost:3000/api/folders --header 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697'

文档示例返回的文件夹列表（文档示例，实际内容取决于你的组织）：

[{"id":1,"uid":"a5261a84-eebc-4733-83a9-61f4713561d1","title":"gdev dashboards"}]

如果你的 token 使用了 RBAC 细粒度权限，还可以调用/api/access-control/user/permissions端点确认 token 实际携带的权限：

curl -H "Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697" -X GET '<grafana_url>/api/access-control/user/permissions' | jq

输出为权限清单的 JSON，例如（文档示例，内容已裁剪）：

{ "dashboards:read": ["dashboards:uid:70KrY6IVz"], "dashboards:write": ["dashboards:uid:70KrY6IVz"], "datasources:read": ["datasources:*"], "orgs:read": [""] }

限制说明

• 迁移后的 service account 只在创建它的组织内生效。同一任务需要在多个组织执行时，要分别在每个组织创建 service account。
• Service account 不能用于实例级操作（如全局用户管理、组织管理），这类操作需要具有 Grafana server administrator 权限的用户。
• Terraform 路径受 provider 版本约束：v3.0.0 起api_key资源被移除，迁移完成前需将 provider 版本锁定在 v2.19.0 及以下。

【免费下载链接】grafanaThe open and composable observability and data visualization platform. Visualize metrics, logs, and traces from multiple sources like Prometheus, Loki, Elasticsearch, InfluxDB, Postgres and many more.项目地址: https://gitcode.com/GitHub_Trending/gr/grafana