`gcx` 구성

`gcx` 구성 (Configure gcx)

이 문서에서는 구성 파일 또는 환경 변수로 gcx를 구성하는 방법을 알아봐요. 인증 방법 선택, 컨텍스트(context) 정의, 유용한 구성 명령어를 다룹니다.

출처: 문서

본문

구성 파일 또는 환경 변수를 사용해 gcx를 구성할 수 있어요.

gcx 구성 파일 참조 문서, gcx 구성 마이그레이션
환경 변수로 gcx 구성하기

인증 방법 선택 (Choose an authentication method)

gcx는 Grafana 인스턴스에 인증하는 네 가지 방법을 지원해요:

OAuth gcx login gcx OAuth 로그인에 필요한 역할
서비스 계정 토큰 Grafana 서비스 계정
기본 인증 (Basic authentication)
mTLS grafana.tls

Grafana Cloud 플랫폼 API는 명명된 Cloud 항목에 저장된 별도의 자격 증명을 사용해요. Cloud Access Policy 토큰은 전체 명령어 호환성을 가지며 자동화에 권장돼요. 직접 Cloud OAuth는 gcx cloud login 또는 gcx login의 대화형 Cloud 단계를 통해 사용할 수 있지만, 여전히 실험적이며 모든 Cloud 제품 명령어가 아직 허용하지 않아요. OAuth 항목은 만료, 부여된 스코프, 그리고 일관된 OAuth/API 엔드포인트 쌍을 유지해요.

OAuth로 gcx CLI 연결을 승인하려면 Grafana 사용자에게 grafana-assistant-app.tokens.gcx:access 권한이 필요해요. Grafana Assistant 애플리케이션이 등록하는 gcx User 역할이 이 권한을 부여하며, 기본 역할이 Viewer 이상인 사용자에게 자동으로 할당돼요.

참고 기본 역할이 None이거나 기본 plugins.app:access 액션을 부여하지 않는 커스텀 역할을 사용한다면, grafana-assistant-app에 대한 접근 권한도 명시적으로 부여해야 해요:

{
  "action": "plugins.app:access",
  "scope": "plugins:id:grafana-assistant-app"
}

grafana-assistant-app.tokens.gcx:access 권한은 자신의 사용자에 대한 gcx 토큰만 만들 수 있게 해줘요. 다른 사용자의 토큰에는 접근을 부여하지 않으며, 기존 Grafana 권한을 확장하지도 않아요.

참고 gcx login이 gcx User 역할을 명시하는 Permission Required 오류로 실패하면, Grafana 관리자에게 gcx User 역할 또는 grafana-assistant-app.tokens.gcx:access 권한을 포함한 커스텀 역할을 할당해 달라고 요청해요. 역할이 인스턴스에 존재하지 않으면 Grafana Assistant 애플리케이션을 그 역할을 포함하는 버전으로 업데이트해야 해요.

사용 중인 `gcx` 구성 파일 이해하기 (Understand the gcx configuration file in use)

gcx config path를 실행해 현재 사용 중인 구성 파일을 표시해요.

gcx는 YAML로 구성을 저장해요. --config <path> 또는 GCX_CONFIG=<path>는 명시적인 파일 하나를 선택하고 레이어링을 우회해요. 그렇지 않으면 gcx는 다음 순서로 모든 기존 원본을 로드하며, 나중 원본이 우선해요:

$XDG_CONFIG_DIRS/gcx/config.yaml
$HOME/.config/gcx/config.yaml $XDG_CONFIG_HOME/gcx/config.yaml
.gcx.yaml

명명된 stacks와 cloud 항목은 원본 간에 원자적이에요: 우선순위가 높은 같은 이름의 항목이 낮은 항목을 완전히 대체해요. 이렇게 하면 자격 증명과 그 서버 또는 Cloud 엔드포인트가 같은 신뢰 원본에 유지돼요. 컨텍스트 참조와 데이터소스 기본값은 필드별로 병합될 수 있어요.

OS 자격 증명 저장소(macOS의 Keychain, Windows의 Credential Manager, Linux의 Secret Service)의 자격 증명은 정식(canonical) 구성 파일, 정확한 소유자 종류와 이름, 정확한 시크릿 필드, 정규화된 대상에 바인딩돼요. 구성 파일을 복사해도 저장된 자격 증명이 이식 가능해지지 않아요. 복사된 파일은 별도로 인증해야 해요. 저장 규칙과 키체인 오류 절차는 키체인 자격 증명 저장을 참고하세요.

자동으로 발견된 저장소 .gcx.yaml은 환경, 로그인 플래그, 또는 프롬프트의 토큰·비밀번호·클라이언트 인증서 파일을 파일이 제공하는 대상에 연결할 수 없어요. 또한 Cloud 자격 증명과 직접 공급자 엔드포인트를 암시적으로 결합하거나 파생된 공급자 자격 증명과 캐시를 기록할 수 없어요. 런타임에 제공된 공급자 엔드포인트는 일치하는 런타임 자격 증명과 함께만 수락되며, 두 값 모두 자동 발견된 저장소 스택의 TLS 또는 프록시 설정을 승인하지 않아요. 그 작업들에 저장소 구성을 신뢰하려면 명시적으로 선택해요:

gcx login --config .gcx.yaml
# 또는
GCX_CONFIG=.gcx.yaml gcx login

그 정확한 파일이 소유하는 자격 증명은 바인딩된 대상이 변하지 않는 한 계속 사용할 수 있어요.

명명된 스택 또는 Cloud 항목의 리터럴 편집은 그것을 참조하는 모든 컨텍스트에 영향을 줘요. 편집이 자격 증명 대상을 변경하는 경우(예: Grafana 서버, Synthetic Monitoring URL, 또는 Cloud API/OAuth 엔드포인트), gcx는 같은 쓰기에서 이전 자격 증명을 지워요. 새 대상을 사용하기 전에 새 자격 증명을 제공해요. 정규화 동등한 엔드포인트 편집은 그것을 보존해요.

컨텍스트 정의 (Define contexts)

gcx는 여러 컨텍스트를 지원하므로 인스턴스 간에 전환할 수 있어요. 컨텍스트는 Grafana 연결 세부 정보를 담고 있는 명명된 스택 항목을 참조해요. 기본적으로 gcx는 default 컨텍스트를 사용해요.

스택 항목은 서버와 함께 자격 증명 하나를 보관해요. 같은 스택에 대해 두 개의 신원(예: 개인 토큰과 CI 토큰, 또는 읽기 전용과 관리자)을 사용하려면 스택 항목 두 개와 각각에 대한 컨텍스트를 정의해요.

default 컨텍스트를 구성하려면:

gcx config set stacks.default.grafana.server http://localhost:3000
gcx config set contexts.default.stack default

# OSS/Enterprise 사용 시 org-id 설정 - Grafana Cloud 대상이면 건너뛰기
gcx config set stacks.default.grafana.org-id 1

# 서비스 계정 토큰으로 인증
gcx config set stacks.default.grafana.token service-account-token

# 또는 기본 인증 사용
gcx config set stacks.default.grafana.user admin
gcx config set stacks.default.grafana.password admin

다른 컨텍스트를 만들려면 같은 패턴을 사용해요:

gcx config set stacks.staging.grafana.server https://staging.grafana.example
gcx config set stacks.staging.grafana.org-id 1
gcx config set contexts.staging.stack staging

이 예시들에서 default와 staging은 컨텍스트와 스택 이름이라는 점을 기억하세요.

유용한 명령어 (Useful commands)

구성을 확인하려면 다음 명령어를 사용해요:

gcx config check

--context 없이 이 명령어는 반환하기 전에 구성된 모든 컨텍스트를 검사해요. 현재 컨텍스트가 잘못되었거나 검사한 어떤 컨텍스트가 구성, 인증 설정, 연결성, 또는 Grafana 버전 검사에 실패하면 0이 아닌 종료 코드를 반환하므로 배포 게이트(deployment gate)로 안전하게 사용할 수 있어요.

관련 없는 항목을 검증하지 않고 컨텍스트 하나만 검사하려면 --context를 전달해요:

gcx config check --context staging

기존 컨텍스트 나열:

gcx config list-contexts

다른 컨텍스트로 전환:

gcx config use-context staging

전체 구성 보기:

gcx config view

환경 변수로 `gcx` 구성하기 (Configure gcx with environment variables)

지원되는 모든 환경 변수는 참조 문서에 나열되어 있어요.

gcx는 REST API를 통해 Grafana에 연결하므로 인증 자격 증명을 구성해야 해요. 최소한 Grafana URL과 조직 ID를 설정해요:

GRAFANA_SERVER='http://localhost:3000' GRAFANA_ORG_ID='1' gcx config check

인증 방법에 따라 다음 중 하나도 설정해요:

Grafana 서비스 계정 토큰
username password

인증을 구성한 뒤 gcx 사용을 시작할 수 있어요.

이 구성을 유지하려면 컨텍스트 생성을 참고하세요.

더 알아보기 (Learn more)

원문 문서

`gcx` 구성

gcx 구성 (Configure gcx)

본문