[v9.5.x] [feat] docs; update admonition syntax (#68856)

[feat] docs; update admonition syntax (#68842) * [feat] docs; update admonition syntax - Standardizes according to style conventions: https://grafana.com/docs/writers-toolkit/style-guide/style-conventions/#admonitions - Prepares docs for better, uniform admonition style. * Remove false positives and irregularities * false positive removal * Update docs/sources/datasources/mysql/_index.md * Update docs/sources/developers/angular_deprecation/angular-plugins.md * fix link errors * Prettify some nested blockquotes * remoe unnecessary admonition (cherry picked from commit 1c4bb9ca00) Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com>
2023-05-23 07:46:35 -05:00
parent f74b514e1a
commit 08ea5c94c6
144 changed files with 2398 additions and 710 deletions
@@ -17,7 +17,9 @@ An API key is a randomly generated string that external systems use to interact

 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.

-> **Note:** If you use Grafana v8.5 or newer, use service accounts instead of API keys. For more information, refer to [Grafana service accounts]({{< relref "../service-accounts/" >}}).
+{{% 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 %}}

 {{< section >}}

@@ -61,7 +63,9 @@ For more information about the benefits of service accounts, refer to [Grafana s

 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.

-> **Note:** If you are using API keys for authentication, we recommend that you migrate your integration to the service account authentication method. The API key will continue to work. You can locate the API key in the [Grafana service account tokens]({{< relref "../service-accounts/#service-account-tokens" >}}) details.
+{{% 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

@@ -106,9 +110,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 using the API
+### Migrate API keys to Grafana service accounts for API calls

-This section shows you how to migrate API keys to Grafana service accounts using the Grafana 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" >}}).

 #### Before you begin

@@ -120,7 +124,7 @@ To follow these instructions, you need one of the following:

 #### Steps

-Complete the following steps to migrate from API keys to service accounts using the API:
+Complete the following steps to migrate from API keys to service accounts for API:

 1. Call the `POST /api/serviceaccounts` endpoint and the `POST /api/serviceaccounts/<id>/tokens`.

@@ -135,9 +139,44 @@ Complete the following steps to migrate from API keys to service accounts using
 1. Remove code that handles the old `/api/auth/keys` endpoint.
 1. Track the [API keys](http://localhost:3000/org/apikeys) in use and migrate them to SATs.

-### Migrate API keys to Grafana service accounts using Terraform
+#### Example

-This section shows you how to migrate API keys to Grafana service accounts using Terraform.
+Your current setup
+
+```sh
+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=="}%
+```
+
+New setup
+
+```sh
+# 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_9244xlVFZK0j8Lh4fU8Cz6Z5tO664zIi_7a762939"}%
+
+# 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_9244xlVFZK0j8Lh4fU8Cz6Z5tO664zIi_7a762939'
+
+# response
+[{"id":1,"uid":"a5261a84-eebc-4733-83a9-61f4713561d1","title":"gdev dashboards"}]%
+```
+
+### Migrate API keys to Grafana service accounts in 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).

 #### Steps

@@ -147,3 +186,170 @@ Complete the following steps to migrate from API keys to service accounts using
 1. Specify the desired scopes and expiration date when creating the service account.
 1. Use the token returned from `grafana_service_account_token` to authenticate the API requests.
 1. Remove the terraform configuration for creating your `grafana_api_key` resources.
+
+**Example: your current Terraform configuration**
+
+```tf
+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
+}
+```
+
+**Your new Terraform configuration**
+
+_Note:_ you can create multiple tokens using one service account.
+
+```tf
+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
+}
+```
+
+### Migrate Cloud **Stack** API keys to Grafana cloud stack service accounts in 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).
+
+{{% 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.
+{{% /admonition %}}
+
+#### Steps
+
+Complete the following steps to migrate from cloud stack API keys to cloud stack service accounts using Terraform:
+
+1. Generate `grafana_cloud_stack_service_account` and `grafana_cloud_stack_service_account_token` resources.
+1. Specify the desired scopes and expiration date when creating the service account.
+1. Use the token returned from `grafana_cloud_stack_service_account_token` to authenticate the API requests.
+1. Remove the Terraform configuration for creating your `grafana_cloud_stack_api_key` resources.
+
+**Example: Your current Terraform configuration**
+
+```tf
+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 API key to be used as auth
+resource "grafana_cloud_stack_api_key" "management" {
+  provider = grafana.cloud
+
+  stack_slug = grafana_cloud_stack.my_stack.slug
+  name       = "management-key"
+  role       = "Admin"
+}
+```
+
+**Your new Terraform configuration**
+
+```tf
+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
+}
+```