mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
IAM docs: Transform API keys to Migrate API keys docs (#92380)
* IAM docs: Transform `API keys` to `Migrate API keys` docs * Update links to `API keys` in other doc pages * Grafana UI: update help button link * Update OpenAPI/Swagger links * Update docs/sources/administration/service-accounts/migrate-api-keys.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update `relref` links to the new URL * fix space before em dash spaces before or after em dashes are not recommended (https://developers.google.com/style/dashes) --------- Co-authored-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Irene Rodriguez <irene.rodriguez@grafana.com>
This commit is contained in:
Pepe Cano
GitHub
parent
48f8be2cfc
commit
6a29e4aecf
@ -92,7 +92,7 @@ Assign fixed roles when the basic roles do not meet your permission requirements
|
||||
|
||||
- [Alerting]({{< relref "../../../alerting/" >}})
|
||||
- [Annotations]({{< relref "../../../dashboards/build-dashboards/annotate-visualizations" >}})
|
||||
- [API keys]({{< relref "../../api-keys/" >}})
|
||||
- [API keys](/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/)
|
||||
- [Dashboards and folders]({{< relref "../../../dashboards/" >}})
|
||||
- [Data sources]({{< relref "../../../datasources/" >}})
|
||||
- [Explore]({{< relref "../../../explore/" >}})
|
||||
|
||||
@ -23,7 +23,7 @@ weight: 800
|
||||
You can use a service account to run automated workloads in Grafana, such as dashboard provisioning, configuration, or report generation. Create service accounts and tokens to authenticate applications, such as Terraform, with the Grafana API.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Service accounts replace [API keys]({{< relref "../api-keys/" >}}) as the primary way to authenticate applications that interact with Grafana.
|
||||
Service accounts replace [API keys](/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/) as the primary way to authenticate applications that interact with Grafana.
|
||||
{{% /admonition %}}
|
||||
|
||||
A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:
|
||||
@ -1,93 +1,37 @@
|
||||
---
|
||||
aliases:
|
||||
- about-api-keys/
|
||||
- create-api-key/
|
||||
description: This section contains information about API keys in Grafana
|
||||
- ../api-keys/ # /docs/grafana/<GRAFANA_VERSION>/administration/api-keys/
|
||||
- ../about-api-keys/ # /docs/grafana/<GRAFANA_VERSION>/administration/about-api-keys/
|
||||
- ../create-api-key/ # /docs/grafana/<GRAFANA_VERSION>/administration/create-api-key/
|
||||
description: Learn how to migrate legacy API keys to service account tokens.
|
||||
keywords:
|
||||
- API keys
|
||||
- Service accounts
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- cloud
|
||||
- oss
|
||||
menuTitle: API keys
|
||||
title: API keys
|
||||
menuTitle: Migrate API keys
|
||||
title: Migrate API keys to service account tokens
|
||||
weight: 700
|
||||
---
|
||||
|
||||
# API keys
|
||||
# Migrate API keys to service account tokens
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Deprecated: [Service accounts]({{< relref "../service-accounts/" >}}) have replaced API keys as the primary way to authenticate applications that interact with Grafana.
|
||||
API keys are deprecated. [Service accounts](/docs/grafana/latest/administration/service-accounts/) now replace API keys for authenticating with the **HTTP APIs** and interacting with Grafana.
|
||||
{{% /admonition %}}
|
||||
|
||||
An API key is a randomly generated string that external systems use to interact with Grafana HTTP APIs.
|
||||
API keys specify a role—either **Admin**, **Editor**, or **Viewer**—that determine the permissions associated with interacting with Grafana.
|
||||
|
||||
When you create an API key, you specify a **Role** that determines the permissions associated with the API key. Role permissions control that actions the API key can perform on Grafana resources.
|
||||
Compared to API keys, service accounts have limited scopes that provide more security. For more information on the benefits of service accounts, refer to [service account benefits](/docs/grafana/latest/administration/service-accounts/#service-account-benefits).
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
If you use Grafana v9.1 or newer, use service accounts instead of API keys. For more information, refer to [Grafana service accounts]({{< relref "../service-accounts/" >}}).
|
||||
{{% /admonition %}}
|
||||
When you migrate an API key to a service account, a service account is created with a service account token. Your existing API key—now migrated to a service account token—will continue working as before.
|
||||
|
||||
{{< section >}}
|
||||
To find the migrated API keys, click **Administration** in the left-side menu, then **Users and access -> Service Accounts**, select the service account, and locate the **Token**.
|
||||
|
||||
## Create an API key
|
||||
|
||||
Create an API key when you want to manage your computed workload with a user.
|
||||
|
||||
This topic shows you how to create an API key using the Grafana UI. You can also create an API key using the Grafana HTTP API. For more information about creating API keys via the API, refer to [Create API key via API]({{< relref "../../developers/http_api/create-api-tokens-for-org/#how-to-create-a-new-organization-and-an-api-token" >}}).
|
||||
|
||||
### Before you begin
|
||||
|
||||
To follow these instructions, you need at least one of the following:
|
||||
|
||||
- Administrator permissions
|
||||
- Editor permissions
|
||||
- Service account writer
|
||||
|
||||
- To ensure you have permission to create and edit API keys, follow the instructions in [Roles and permissions]({{< relref "../roles-and-permissions/#" >}}).
|
||||
|
||||
### Steps
|
||||
|
||||
To create an API key, complete the following steps:
|
||||
|
||||
1. Sign in to Grafana.
|
||||
1. Click **Administration** in the left-side menu, **Users and access**, and select **API Keys**.
|
||||
1. Click **Add API key**.
|
||||
1. Enter a unique name for the key.
|
||||
1. In the **Role** field, select one of the following access levels you want to assign to the key.
|
||||
- **Admin**: Enables a user to use APIs at the broadest, most powerful administrative level.
|
||||
- **Editor** or **Viewer** to limit the key's users to those levels of power.
|
||||
1. In the **Time to live** field, specify how long you want the key to be valid.
|
||||
- The maximum length of time is 30 days (one month). You enter a number and a letter. Valid letters include `s` for seconds,`m` for minutes, `h` for hours, `d `for days, `w` for weeks, and `M `for month. For example, `12h` is 12 hours and `1M` is 1 month (30 days).
|
||||
- If you are unsure about how long an API key should be valid, we recommend that you choose a short duration, such as a few hours. This approach limits the risk of having API keys that are valid for a long time.
|
||||
1. Click **Add**.
|
||||
|
||||
## Migrate API keys to Grafana service accounts
|
||||
|
||||
As an alternative to using API keys for authentication, you can use a service account-based authentication system. When compared to API keys, service accounts have limited scopes that provide more security than using API keys.
|
||||
|
||||
For more information about the benefits of service accounts, refer to [Grafana service account benefits]({{< relref "../service-accounts/#service-account-benefits" >}}).
|
||||
|
||||
The service account endpoints generate a machine user for authentication instead of using API keys. When you migrate an API key to a service account, a service account will be created with a service account token.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
If you're currently using API keys for authentication, we strongly recommend to use Grafana Service Accounts instead. Rest assured, when migrating to Service Accounts, your existing API keys will continue working as before. To find the migrated API keys, navigate to the Service Accounts section and select the Service Account Tokens tab. For more information, please refer to the [Grafana service account tokens]({{< relref "../service-accounts/#service-account-tokens" >}}) details.
|
||||
{{% /admonition %}}
|
||||
|
||||
## Ways of migrating API keys to service accounts
|
||||
|
||||
If you are currently using API keys in your environment, you need to reconfigure your setup to use service accounts.
|
||||
|
||||
Depending on your current setup, you may need to use one or all of the following methods to migrate your environment to service accounts:
|
||||
|
||||
- The Grafana user interface: Use this method if you have been using the UI to manage your API keys and want to switch to using service accounts.
|
||||
- The Grafana API: Use this method if you have been using API calls to manage your API keys and want to switch to using service accounts programmatically.
|
||||
- Terraform: If you have a Terraform configuration that sets up API keys, you need to reconfigure your Terraform to use service accounts instead.
|
||||
|
||||
By following these steps, you can successfully migrate your integration from API keys to service accounts and continue using Grafana seamlessly.
|
||||
|
||||
### Migrate API keys to Grafana service accounts using the Grafana user interface
|
||||
## Migrate API keys using the Grafana user interface
|
||||
|
||||
This section shows you how to migrate API keys to Grafana service accounts using the Grafana user interface. You can choose to migrate a single API key or all API keys. When you migrate all API keys, you can no longer create API keys and must use service accounts instead.
|
||||
|
||||
@ -118,9 +62,9 @@ To migrate a single API key to a service account, complete the following steps:
|
||||
1. Find the API Key you want to migrate.
|
||||
1. Click **Migrate to service account**.
|
||||
|
||||
### Migrate API keys to Grafana service accounts for API calls
|
||||
## Migrate API keys using the HTTP API
|
||||
|
||||
This section shows you how to migrate API keys to Grafana service accounts for Grafana API workflows. For references see: [Grafana Service Accounts for the Grafana API]({{< relref "../../developers/http_api/serviceaccount/#create-service-account" >}}).
|
||||
This section shows you how to programmatically migrate API keys to Grafana service accounts using the HTTP API. For API additional information, refer to [Service account HTTP APIs](/docs/grafana/latest/developers/http_api/serviceaccount/).
|
||||
|
||||
#### Before you begin
|
||||
|
||||
@ -180,7 +124,7 @@ curl --request GET --url http://localhost:3000/api/folders --header 'Authorizati
|
||||
[{"id":1,"uid":"a5261a84-eebc-4733-83a9-61f4713561d1","title":"gdev dashboards"}]%
|
||||
```
|
||||
|
||||
### Migrate API keys to Grafana service accounts in Terraform
|
||||
## Migrate API keys using Terraform
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
The terraform resource `api_key` is removed from the Grafana Terraform Provider in v3.0.0.
|
||||
@ -201,9 +145,7 @@ terraform {
|
||||
}
|
||||
```
|
||||
|
||||
This section shows you how to migrate your Terraform configuration for API keys to Grafana service accounts. For resources, see [Grafana Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/service_account_token).
|
||||
|
||||
For migration your cloud stack api keys, use the `grafana_cloud_stack_service_account` and `gafana_cloud_stack_service_account_token` resources see [Grafana Cloud Stack Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_stack_service_account).
|
||||
This section shows you how to migrate your Terraform configuration for API keys to Grafana service accounts. For additional information, refer to [Grafana Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/service_account_token).
|
||||
|
||||
#### Steps
|
||||
|
||||
@ -283,9 +225,11 @@ resource "grafana_service_account_token" "sat-foo" {
|
||||
}
|
||||
```
|
||||
|
||||
### Migrate Cloud **Stack** API keys to Grafana cloud stack service accounts in Terraform
|
||||
## Migrate Cloud Stack API keys using Terraform
|
||||
|
||||
This section shows you how to migrate your Terraform configuration for Grafana cloud stack API keys to Grafana cloud stack service accounts. For migration your cloud stack api keys, use the `grafana_cloud_stack_service_account` and `gafana_cloud_stack_service_account_token` resources see [Grafana Cloud Stack Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_stack_service_account).
|
||||
This section shows you how to migrate your Terraform configuration for Grafana cloud stack API keys to Grafana cloud stack service accounts.
|
||||
|
||||
For migration your cloud stack api keys, use the `grafana_cloud_stack_service_account` and `gafana_cloud_stack_service_account_token` resources. For additional information, refer to [Grafana Cloud Stack Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_stack_service_account).
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
This is only relevant for Grafana Cloud **Stack** API keys `grafana_cloud_stack_api_key`. Grafana Cloud API keys resource `grafana_cloud_api_key` are not deprecated and should be used for authentication for managing your Grafana cloud.
|
||||
@ -99,11 +99,11 @@ Grafana's [HTTP API endpoints for generating and managing API Keys]({{< relref "
|
||||
|
||||
#### Migration path
|
||||
|
||||
While upgrading to Grafana v10, you don't need to take any action; your API keys will be automatically migrated. To test or perform the migration from API keys to service accounts before upgrading to Grafana v10, follow our [migration documentation]({{< relref "../administration/api-keys/#migrate-api-keys-to-grafana-service-account" >}}").
|
||||
While upgrading to Grafana v10, you don't need to take any action; your API keys will be automatically migrated. To test or perform the migration from API keys to service accounts before upgrading to Grafana v10, follow our [migration documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/).
|
||||
|
||||
#### Learn more
|
||||
|
||||
- [Documentation on migrating from API keys to service accounts]({{< relref "../administration/api-keys/" >}})
|
||||
- [Documentation on migrating from API keys to service accounts](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/)
|
||||
|
||||
- [Blog post announcement with a video demo including how to migrate](https://grafana.com/blog/2022/08/24/new-in-grafana-9.1-service-accounts-are-now-ga/)
|
||||
|
||||
|
||||
@ -85,7 +85,7 @@ This endpoint has been made obsolete in Grafana 11.3.0.
|
||||
|
||||
{{% /admonition %}}
|
||||
|
||||
Endpoint is obsolete and has been moved to [Grafana service account API]({{< relref "./serviceaccount/" >}}). For more information, refer to [Migrate to Grafana service account API]({{< relref "../../administration/api-keys/#migrate-api-keys-to-grafana-service-accounts-using-the-api" >}}).
|
||||
Endpoint is obsolete and has been moved to [Grafana service account API]({{< relref "./serviceaccount/" >}}). For more information, refer to [Migrate to Grafana service account API](/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/).
|
||||
|
||||
`POST /api/auth/keys`
|
||||
|
||||
|
||||
@ -96,7 +96,7 @@ These are just a few examples of how Grafana can be used in M2M scenarios. The p
|
||||
You can use a service account to run automated workloads in Grafana, such as dashboard provisioning, configuration, or report generation. Create service accounts and service accounts tokens to authenticate applications, such as Terraform, with the Grafana API.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Service accounts will eventually replace [API keys]({{< relref ".#api-keys" >}}) as the primary way to authenticate applications that interact with Grafana.
|
||||
Service accounts will eventually replace [API keys](/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/) as the primary way to authenticate applications that interact with Grafana.
|
||||
{{% /admonition %}}
|
||||
|
||||
A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:
|
||||
|
||||
@ -46,7 +46,7 @@ Secret scanning is disabled by default. Outgoing connections are made once you e
|
||||
## Before you begin
|
||||
|
||||
- Ensure all your API keys have been migrated to service accounts.
|
||||
For more information about service account migration, refer to [Migrate API keys to Grafana service accounts]({{< relref "../../administration/api-keys#migrate-api-keys-to-grafana-service-accounts" >}}).
|
||||
For more information about service account migration, refer to [Migrate API keys to Grafana service accounts](/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/).
|
||||
|
||||
## Configure secret scanning
|
||||
|
||||
|
||||
@ -36,4 +36,4 @@ We are deprecating the dashboard previews feature and will remove it in Grafana
|
||||
|
||||
### Migrate your API keys to service accounts
|
||||
|
||||
We are upgrading Grafana [API keys]({{< relref "../../administration/api-keys" >}}) to service accounts. Service accounts are a superset of API keys that include token rotation and compatibility with [Role-based access control]({{< relref "../../administration/roles-and-permissions/access-control" >}}). In a future release, we'll automatically migrate all existing API keys to service accounts. All of your existing tokens will continue to work; they will simply be migrated to service accounts. You can preempt this change by migrating your existing API keys to service accounts using Grafana's UI or API. Learn how to do this in the [API keys documentation]({{< relref "../../administration/api-keys#migrate-api-keys-to-grafana-service-accounts" >}}).
|
||||
We are upgrading Grafana [API keys](/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/) to service accounts. Service accounts are a superset of API keys that include token rotation and compatibility with [Role-based access control]({{< relref "../../administration/roles-and-permissions/access-control" >}}). In a future release, we'll automatically migrate all existing API keys to service accounts. All of your existing tokens will continue to work; they will simply be migrated to service accounts. You can preempt this change by migrating your existing API keys to service accounts using Grafana's UI or API. Learn how to do this in the [API keys documentation](/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/).
|
||||
|
||||
@ -22,7 +22,7 @@ import (
|
||||
// Deprecated: true.
|
||||
//
|
||||
// Deprecated. Please use GET /api/serviceaccounts and GET /api/serviceaccounts/{id}/tokens instead
|
||||
// see https://grafana.com/docs/grafana/next/administration/api-keys/#migrate-api-keys-to-grafana-service-accounts-using-the-api.
|
||||
// see https://grafana.com/docs/grafana/next/administration/service-accounts/migrate-api-keys/.
|
||||
//
|
||||
// Responses:
|
||||
// 200: getAPIkeyResponse
|
||||
@ -71,7 +71,7 @@ func (hs *HTTPServer) GetAPIKeys(c *contextmodel.ReqContext) response.Response {
|
||||
// Delete API key.
|
||||
//
|
||||
// Deletes an API key.
|
||||
// Deprecated. See: https://grafana.com/docs/grafana/next/administration/api-keys/#migrate-api-keys-to-grafana-service-accounts-using-the-api.
|
||||
// Deprecated. See: https://grafana.com/docs/grafana/next/administration/service-accounts/migrate-api-keys/.
|
||||
//
|
||||
// Deprecated: true
|
||||
// Responses:
|
||||
@ -110,7 +110,7 @@ func (hs *HTTPServer) DeleteAPIKey(c *contextmodel.ReqContext) response.Response
|
||||
// Deprecated: true
|
||||
// Deprecated. Please use POST /api/serviceaccounts and POST /api/serviceaccounts/{id}/tokens
|
||||
//
|
||||
// see: https://grafana.com/docs/grafana/next/administration/api-keys/#migrate-api-keys-to-grafana-service-accounts-using-the-api.
|
||||
// see: https://grafana.com/docs/grafana/next/administration/service-accounts/migrate-api-keys/.
|
||||
//
|
||||
// Responses:
|
||||
// 301: statusMovedPermanently
|
||||
|
||||
@ -2184,7 +2184,7 @@
|
||||
},
|
||||
"/auth/keys": {
|
||||
"get": {
|
||||
"description": "Will return auth keys.\n\nDeprecated: true.\n\nDeprecated. Please use GET /api/serviceaccounts and GET /api/serviceaccounts/{id}/tokens instead\nsee https://grafana.com/docs/grafana/next/administration/api-keys/#migrate-api-keys-to-grafana-service-accounts-using-the-api.",
|
||||
"description": "Will return auth keys.\n\nDeprecated: true.\n\nDeprecated. Please use GET /api/serviceaccounts and GET /api/serviceaccounts/{id}/tokens instead\nsee https://grafana.com/docs/grafana/next/administration/service-accounts/migrate-api-keys/.",
|
||||
"tags": [
|
||||
"api_keys"
|
||||
],
|
||||
@ -2234,7 +2234,7 @@
|
||||
},
|
||||
"/auth/keys/{id}": {
|
||||
"delete": {
|
||||
"description": "Deletes an API key.\nDeprecated. See: https://grafana.com/docs/grafana/next/administration/api-keys/#migrate-api-keys-to-grafana-service-accounts-using-the-api.",
|
||||
"description": "Deletes an API key.\nDeprecated. See: https://grafana.com/docs/grafana/next/administration/service-accounts/migrate-api-keys/.",
|
||||
"tags": [
|
||||
"api_keys"
|
||||
],
|
||||
|
||||
@ -17,7 +17,7 @@ export const MigrateToServiceAccountsCard = ({ onMigrate, apikeysCount, disabled
|
||||
const docsLink = (
|
||||
<a
|
||||
className="external-link"
|
||||
href="https://grafana.com/docs/grafana/latest/administration/api-keys/#migrate-api-keys-to-grafana-service-accounts"
|
||||
href="https://grafana.com/docs/grafana/latest/administration/service-accounts/migrate-api-keys/)"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>
|
||||
|
||||
@ -15352,7 +15352,7 @@
|
||||
},
|
||||
"/auth/keys": {
|
||||
"get": {
|
||||
"description": "Will return auth keys.\n\nDeprecated: true.\n\nDeprecated. Please use GET /api/serviceaccounts and GET /api/serviceaccounts/{id}/tokens instead\nsee https://grafana.com/docs/grafana/next/administration/api-keys/#migrate-api-keys-to-grafana-service-accounts-using-the-api.",
|
||||
"description": "Will return auth keys.\n\nDeprecated: true.\n\nDeprecated. Please use GET /api/serviceaccounts and GET /api/serviceaccounts/{id}/tokens instead\nsee https://grafana.com/docs/grafana/next/administration/service-accounts/migrate-api-keys/.",
|
||||
"operationId": "getAPIkeys",
|
||||
"parameters": [
|
||||
{
|
||||
@ -15405,7 +15405,7 @@
|
||||
"/auth/keys/{id}": {
|
||||
"delete": {
|
||||
"deprecated": true,
|
||||
"description": "Deletes an API key.\nDeprecated. See: https://grafana.com/docs/grafana/next/administration/api-keys/#migrate-api-keys-to-grafana-service-accounts-using-the-api.",
|
||||
"description": "Deletes an API key.\nDeprecated. See: https://grafana.com/docs/grafana/next/administration/service-accounts/migrate-api-keys/.",
|
||||
"operationId": "deleteAPIkey",
|
||||
"parameters": [
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user