API 키를 서비스 계정 토큰으로 마이그레이션

API 키를 서비스 계정 토큰으로 마이그레이션 (Migrate API keys to service account tokens)

API 키는 이제 비권장(deprecated)이며, HTTP API 인증과 Grafana 상호작용에서 서비스 계정(service account)이 이를 대체해요. 이 문서는 기존 API 키를 서비스 계정 토큰(SAT)으로 마이그레이션하는 방법을 UI, HTTP API, Terraform 세 가지 방식으로 안내합니다.

출처: Migrate API keys to service account tokens

본문

API 키는 Grafana와 상호작용할 때의 권한을 결정하는 역할(Admin, Editor, Viewer 중 하나)을 지정해요. API 키와 비교해 서비스 계정은 제한된 범위(scopes)를 가져 더 안전해요. 서비스 계정의 이점에 대한 자세한 내용은 service account benefits 문서를 참고하세요.

API 키를 서비스 계정으로 마이그레이션하면 서비스 계정 토큰과 함께 서비스 계정이 생성돼요. 이제 서비스 계정 토큰으로 마이그레이션된 기존 API 키는 이전과 동일하게 계속 동작해요.

마이그레이션된 API 키를 찾으려면 왼쪽 메뉴에서 Administration을 클릭한 뒤 Users and access > Service Accounts를 선택하고 서비스 계정을 선택한 다음 Token을 찾으세요.

Grafana UI로 API 키 마이그레이션

UI로 단일 API 키 또는 모든 API 키를 마이그레이션할 수 있어요. 모든 API 키를 마이그레이션하면 더 이상 API 키를 만들 수 없고 서비스 계정을 사용해야 해요.

시작하기 전에: 다음 중 하나 이상이 필요해요.

Administrator 권한
Editor 권한
Service account writer

권한에 대한 자세한 내용은 Roles and permissions을 참고하세요.

모든 API 키를 서비스 계정으로 마이그레이션:

Grafana에 로그인하고 Administration, Users and access를 가리킨 뒤 API Keys를 클릭해요.
페이지 상단에서 Switch from API keys to service accounts 섹션을 찾아요.
Migrate to service accounts now를 클릭해요.
확인 창이 나타나면 Yes, migrate now를 클릭해요.
마이그레이션 성공 후에는 API 키 페이지를 영구히 숨기도록 선택할 수 있어요. 원한다면 Hide API keys page forever를 클릭해요.

단일 API 키를 서비스 계정으로 마이그레이션:

Grafana에 로그인해요.
왼쪽 메뉴에서 Administration, Users and access를 클릭하고 API Keys를 선택해요.
마이그레이션할 API 키를 찾아요.
Migrate to service account를 클릭해요.

HTTP API로 API 키 마이그레이션

HTTP API로 프로그래밍 방식으로 마이그레이션하는 방법을 안내해요. 추가 정보는 Service account HTTP APIs 문서를 참고하세요. 전제 조건은 위와 동일해요.

단계:

POST /api/serviceaccounts 엔드포인트와 POST /api/serviceaccounts//tokens를 호출해요. 이 작업은 서비스 계정 토큰을 생성해요.
시스템이 반환한 ID와 시크릿을 저장해요.
Authorization 헤더에 Bearer 접두사를 붙여 토큰을 전달해요. 이 작업은 API 요청을 인증해요.
기존 /api/auth/keys 엔드포인트를 처리하던 코드를 제거해요.
사용 중인 API 키를 추적하고 SAT로 마이그레이션해요.

예시 — 현재 설정:

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":"eyJrIj...oxfQ=="}%

예시 — 새 설정:

# 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_i...2697'

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

Terraform으로 API 키 마이그레이션

참고: Terraform 리소스 api_key는 Grafana Terraform Provider v3.0.0에서 제거돼요. 이 리소스를 마이그레이션하고 제거하기 전에 terraform 버전을 v2.19.0 이하로 고정해야 해요. 자세한 내용은 Grafana Terraform Provider 릴리스 노트를 참고하세요.

Grafana Terraform Provider를 v2.19.0으로 고정하려면:

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

단계:

grafana_service_account와 grafana_service_account_token 리소스를 생성해요.
서비스 계정을 만들 때 원하는 범위와 만료 날짜를 지정해요.
grafana_service_account_token에서 반환된 토큰으로 API 요청을 인증해요.
grafana_api_key 리소스를 만드는 Terraform 구성을 제거해요.

예시 — 현재 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
}

예시 — 새 Terraform 구성:

참고: 하나의 서비스 계정으로 여러 토큰을 만들 수 있어요.

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
}

Terraform으로 Cloud Stack API 키 마이그레이션

Cloud stack API 키를 cloud stack 서비스 계정으로 마이그레이션하려면 grafana_cloud_stack_service_account와 grafana_cloud_stack_service_account_token 리소스를 사용해요. 자세한 내용은 Grafana Cloud Stack Service Accounts in Terraform 문서를 참고하세요.

참고: 이는 Grafana Cloud Stack API 키(grafana_cloud_stack_api_key)에만 관련돼요. Grafana Cloud API 키 리소스(grafana_cloud_api_key)는 deprecated되지 않으며 Grafana Cloud 관리를 위한 인증에 계속 사용해야 해요.

단계:

grafana_cloud_stack_service_account와 grafana_cloud_stack_service_account_token 리소스를 생성해요.
서비스 계정 생성 시 원하는 범위와 만료 날짜를 지정해요.
grafana_cloud_stack_service_account_token에서 반환된 토큰으로 API 요청을 인증해요.
grafana_cloud_stack_api_key 리소스를 만드는 Terraform 구성을 제거해요.

예시 — 현재 Terraform 구성:

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 = ""
}

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"
}

예시 — 새 Terraform 구성:

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 = ""
}

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 키를 서비스 계정 토큰으로 마이그레이션