서비스 ID로 인증

Google Distributed Cloud (GDC) 오프라인의 서비스 ID는 워크로드 또는 서비스가 리소스와 마이크로서비스에 안전하게 프로그래매틱 방식으로 액세스할 수 있는 전용 ID를 제공합니다. 이러한 ID는 사람이 아닌 애플리케이션이나 워크로드에서 사용하는 특수 ID이며, 사람이 로그인하는 데 사용할 수 없습니다. 사용자 계정과 마찬가지로 서비스 ID에 권한과 역할을 부여하여 액세스할 수 있는 항목을 정의합니다.

이 개념에는 두 가지 용어가 사용됩니다. GDC 콘솔에서는 주로 서비스 ID라는 용어를 사용하고 gdcloud 명령어와 API 상호작용에서는 서비스 계정이라는 용어를 자주 사용합니다. 후자는 기본 Kubernetes 커스텀 리소스 ProjectServiceAccount의 이름을 반영합니다. 두 용어 모두 워크로드의 비인간 ID를 의미합니다. 이 문서에서는 서비스 ID를 기본 용어로 사용합니다.

서비스 ID는 다음과 같은 GDC 인프라를 관리하는 데 유용합니다.

내부 Distributed Cloud 서비스 및 워크로드가 Distributed Cloud 컨트롤 플레인 애플리케이션 프로그래밍 인터페이스(API)에 안전하게 액세스할 수 있습니다. 예를 들어 데이터베이스를 만들고 삭제하기 위해 Kubernetes API와 상호작용하는 데이터베이스 서비스가 있습니다.
Distributed Cloud의 고객 워크로드가 Distributed Cloud 서비스에 액세스하고 승인된 애플리케이션 프로그래밍 인터페이스 (API) 호출을 수행합니다. 예를 들어 서비스 ID는 Vertex AI Workbench 노트북을 사용하여 Speech-to-Text API를 통해 오디오 파일을 텍스트로 변환하는 고객을 관리할 수 있습니다.
분산형 클라우드와 제휴할 외부 워크로드입니다. 예를 들어 서비스 ID는 문서를 디지털화하지만 광학 문자 인식 (OCR) API를 사용하여 현재 OCR 엔진을 대체하려는 Distributed Cloud 외부의 애플리케이션을 관리할 수 있습니다.
고객 리소스 또는 사용자 클러스터에 안전하게 액세스하기 위한 분산 클라우드 서비스 또는 시스템 컨트롤러 예를 들어 서비스 아이덴티티는 관리자 클러스터에서 실행되는 서비스 컨트롤러가 고객이 관리하는 사용자 클러스터 내에서 워크로드를 실행해야 하는 인증 및 승인 워크플로를 관리할 수 있습니다.

GDC 콘솔, gdcloud CLI 또는 API를 사용하여 서비스 ID의 계정을 관리할 수 있습니다. gdcloud CLI를 사용하면 서비스 ID 기능이 전역 ProjectServiceAccount API를 기반으로 빌드됩니다. ProjectServiceAccount 리소스는 전역으로 구성되므로 gdcloud 유니버스의 모든 영역에서 작동합니다.

시작하기 전에

서비스 ID는 프로젝트 내에서만 만들 수 있습니다. 프로젝트를 만드는 방법을 알아보려면 프로젝트 만들기를 참고하세요.

서비스 ID 관리에는 서비스 ID (ProjectServiceAccount 리소스로 표시됨)와 연결된 사용자 인증 정보 (공개 키 및 비공개 키 쌍)가 모두 포함됩니다. 서비스 ID와 해당 사용자 인증 정보를 관리하는 데 필요한 권한을 얻으려면 조직 IAM 관리자 또는 프로젝트 IAM 관리자에게 해당 프로젝트의 프로젝트 IAM 관리자 (project-iam-admin) 역할을 부여해 달라고 요청하세요.

서비스 ID 만들기

서비스 ID를 만드는 작업에는 계정과 연결된 사용자 인증 정보를 만드는 작업이 포함됩니다.

계정 만들기

서비스 ID의 계정을 만들려면 GDC 콘솔, gdcloud CLI 또는 API를 사용하여 프로젝트에서 ProjectServiceAccount 리소스를 만드세요.

콘솔

GDC 콘솔에 로그인합니다.
탐색 메뉴에서 ID 및 액세스 > 서비스 ID를 선택합니다.
서비스 ID 만들기를 클릭합니다. 서비스 ID 세부정보 페이지가 열립니다.
서비스 ID 이름 필드에 서비스 ID 이름을 입력합니다. 예를 들면 testserviceidentity입니다.
만들기를 클릭합니다.

gdcloud

계정을 만듭니다.

gdcloud iam service-accounts create NAME \
    --project=PROJECT

다음 값을 바꿉니다.

NAME: ProjectServiceAccount의 이름입니다. 이름은 프로젝트 네임스페이스 내에서 고유해야 합니다.
PROJECT: 서비스 ID를 만들 프로젝트입니다. gdcloud init가 이미 설정된 경우 --project 플래그를 생략합니다.

이 명령어는 관리 API 서버의 프로젝트 네임스페이스에 ProjectServiceAccount를 만듭니다.

API

my-project-sa.yaml과 같은 ProjectServiceAccount 커스텀 리소스 YAML 파일을 만듭니다.
```
apiVersion: resourcemanager.global.gdc.goog/v1
kind: ProjectServiceAccount
metadata:
  name: NAME
  namespace: PROJECT
spec:
  keys:
  - algorithm: ALGORITHM
  id: KEY_ID
  key: BASE64_ENCODED_KEY
  validAfter: "START_TIME"
  validBefore: "EXPIRATION_TIME"
```
다음 변수를 바꿉니다.
- NAME: ProjectServiceAccount 리소스의 이름입니다. 이름은 프로젝트 네임스페이스 내에서 고유해야 합니다.
- PROJECT: 서비스 ID를 만들 프로젝트입니다.
- ALGORITHM: 키의 알고리즘입니다. ES256 키만 지원됩니다.
- KEY_ID: 키의 고유 식별자입니다. ID는 확인할 키를 결정하는 데 사용됩니다.
- BASE64_ENCODED_KEY: 검증할 PEM 형식의 base64로 인코딩된 공개 키입니다. 이 공개 키를 생성하는 데 사용된 비공개 키는 ECDSA P256 PEM 형식이어야 합니다.
- START_TIME: 키가 유효해지는 시작 시간입니다(예: 2025-02-07T00:59:34Z).
- EXPIRATION_TIME: 키의 만료 시간입니다(예: 2026-02-07T00:59:34Z).
ProjectServiceAccount 커스텀 리소스를 전역 API 서버에 적용합니다.
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
GLOBAL_API_SERVER_KUBECONFIG 변수를 전역 API 서버의 kubeconfig 파일 경로로 바꿉니다.

사용자 인증 정보 만들기

워크로드 또는 애플리케이션이 서비스 ID(생성한 계정으로 표시됨)로 인증되도록 하려면 사용자 인증 정보를 생성해야 합니다. 사용자 인증 정보를 만드는 작업에는 암호화 비공개 및 공개 키 쌍을 생성하고 공개 키를 서비스 ID와 연결하는 작업이 포함됩니다.

서비스 ID의 사용자 인증 정보를 만들려면 GDC 콘솔, gdcloud CLI 또는 API를 사용합니다.

콘솔

GDC 콘솔에 로그인합니다.
탐색 메뉴에서 ID 및 액세스 > 서비스 ID를 선택합니다.
키에 추가할 서비스 ID의 이름을 클릭합니다.
새 키 만들기를 클릭합니다.
새 키가 키 목록에 표시되고 키가 생성되었음을 확인하는 대화상자가 표시됩니다.

gdcloud

gdcloud 명령어는 애플리케이션 기본 사용자 인증 정보 JSON 파일과 공개 키 및 비공개 키 쌍을 만듭니다.

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

다음 값을 바꿉니다.

APPLICATION_DEFAULT_CREDENTIALS_FILENAME: JSON 파일의 이름입니다.
PROJECT : 키를 만들 프로젝트를 선택합니다. gdcloud init가 이미 설정되어 있으면 --project 플래그를 생략할 수 있습니다.
NAME: 키를 추가할 서비스 ID의 이름입니다.
CA_CERTIFICATE_PATH: 선택사항: 인증 엔드포인트를 확인하는 인증 기관 (CA) 인증서 경로입니다. 이 경로를 지정하지 않으면 시스템 CA 인증서가 사용됩니다. 시스템 CA 인증서에 CA를 설치해야 합니다.

분산 클라우드는 비공개 키가 서명하는 JSON 웹 토큰 (JWT)을 확인하는 데 사용하는 ProjectServiceAccount 키에 공개 키를 추가합니다. 비공개 키가 애플리케이션 기본 사용자 인증 정보 JSON 파일에 작성됩니다.

다음 예시는 애플리케이션 기본 사용자 인증 정보 JSON 파일을 보여줍니다.

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "/path/to/ca.crt",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

이 예시에서는 다음 값을 사용합니다.

project: 조직의 프로젝트 네임스페이스입니다.
private_key_id: 키에 할당된 ID입니다.
private_key: CLI에서 생성하는 PEM 형식의 ECDSA P256 비공개 키입니다.
name: 서비스 ID의 이름입니다.
ca_cert_path: 인증 엔드포인트를 확인하는 데 사용되는 인증 기관 (CA) 인증서의 경로입니다.
token_uri: 인증 엔드포인트의 주소입니다.

API

공개 키와 비공개 키 쌍을 생성합니다. 다음 명령어는 이 용도로 자주 사용되는 도구인 openssl를 예로 사용합니다.
```
openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
openssl ec -in "key.pem" -pubout > "pub.pem"
```

공개 키를 Base64로 인코딩하고 키 ID를 가져옵니다.

KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
BASE64_ENCODED_KEY=$(cat pub.pem | base64)

이전 단계에서 생성된 키 정보를 포함하여 ProjectServiceAccount 커스텀 리소스 YAML 파일을 만들거나 업데이트합니다.
```
apiVersion: resourcemanager.global.gdc.goog/v1
kind: ProjectServiceAccount
metadata:
  name: NAME
  namespace: PROJECT
spec:
  keys:
  - algorithm: ALGORITHM
  id: KEY_ID
  key: BASE64_ENCODED_KEY
  validAfter: "START_TIME"
  validBefore: "EXPIRATION_TIME"
```
다음 변수를 바꿉니다.
- NAME: ProjectServiceAccount 리소스의 이름입니다. 이름은 프로젝트 네임스페이스 내에서 고유해야 합니다.
- PROJECT: 키를 만들려는 프로젝트
- ALGORITHM: 키의 알고리즘입니다. ES256 키만 지원됩니다.
- KEY_ID: 키의 고유 식별자입니다. ID는 확인할 키를 결정하는 데 사용됩니다.
- BASE64_ENCODED_KEY: 검증할 PEM 형식의 base64로 인코딩된 공개 키입니다. 이 공개 키를 생성하는 데 사용된 비공개 키는 ECDSA P256 PEM 형식이어야 합니다.
- START_TIME: 키가 유효해지는 시작 시간입니다(예: 2025-02-07T00:59:34Z).
- EXPIRATION_TIME: 키의 만료 시간입니다(예: 2026-02-07T00:59:34Z).
ProjectServiceAccount 커스텀 리소스를 전역 API 서버에 적용합니다.
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
GLOBAL_API_SERVER_KUBECONFIG 변수를 전역 API 서버의 kubeconfig 파일 경로로 바꿉니다.
비공개 키가 포함된 애플리케이션 기본 사용자 인증 정보 JSON 파일을 만듭니다. JSON 파일의 KEY_ID 변수가 ProjectServiceAccount 사양에서 사용한 KEY_ID 변수와 동일한 값으로 설정되어 있는지 확인합니다.
```
cat <<EOF > "key_file.json"
{
  "format_version": "1",
  "name": "NAME",
  "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')",
  "private_key_id": "KEY_ID",
  "project": "PROJECT",
  "token_uri": "AUTH_URL",
  "type": "gdch_service_account"
}
EOF
```
다음 변수를 바꿉니다.
- NAME: 서비스 ID의 이름입니다.
- KEY_ID: 키의 고유 식별자입니다. ID는 확인할 키를 결정하는 데 사용되며 ProjectServiceAccount 사양에 사용된 KEY_ID 값과 일치해야 합니다.
- PROJECT: 조직의 프로젝트 네임스페이스입니다.
- AUTH_URL: 인증 엔드포인트의 주소입니다.

생성된 키 파일을 사용하여 이 서비스 ID로 gdcloud CLI를 인증하는 방법에 대한 자세한 내용은 키를 사용하여 서비스 ID 승인 섹션을 참고하세요.

서비스 ID 보기

이 섹션에서는 서비스 ID와 연결된 공개 키를 확인하는 방법을 설명합니다.

서비스 ID 목록 보기

프로젝트 내 서비스 ID 목록을 보려면 GDC 콘솔 또는 gdcloud CLI를 사용하세요.

콘솔

GDC 콘솔에 로그인합니다.
프로젝트를 선택합니다.
탐색 메뉴에서 ID 및 액세스 > 서비스 ID를 클릭하여 프로젝트의 서비스 ID 목록을 확인합니다.

gdcloud

프로젝트의 서비스 ID 계정을 나열합니다.

gdcloud iam service-accounts list \
    --project=PROJECT

PROJECT를 프로젝트 ID로 바꿉니다.

서비스 ID의 공개 키 목록 보기

프로젝트의 서비스 ID 계정에 등록된 공개 키를 나열합니다.

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

다음을 바꿉니다.

PROJECT: 프로젝트 ID입니다.
NAME: 사용할 서비스 ID 계정의 이름입니다.

서비스 ID에 권한 부여

서비스 ID에 권한을 부여하려면 GDC 콘솔 또는 gdcloud CLI를 사용하여 역할 바인딩을 만들어 하나 이상의 역할을 할당합니다.

콘솔

GDC 콘솔에 로그인합니다.
프로젝트를 선택합니다.
탐색 메뉴에서 ID 및 액세스 > 액세스를 선택합니다.
구성원 목록에서 구성원 추가를 클릭합니다. 사용자 및 역할 페이지가 표시됩니다.
구성원 유형 목록에서 서비스 ID를 선택합니다.
서비스 ID 목록에서 역할 바인딩을 할당할 서비스 ID를 선택합니다.
역할 목록에서 서비스 ID에 할당할 역할(예: 백업 생성자)을 선택합니다.
선택사항: 다른 역할을 추가하려면 다른 역할 추가를 클릭합니다. 추가 역할을 선택합니다.
추가를 클릭합니다.

gdcloud

서비스 ID 계정을 프로젝트 네임스페이스 내의 역할 또는 다른 네임스페이스의 역할에 바인딩할 수 있습니다.

프로젝트 네임스페이스 내의 역할에 계정을 바인딩합니다.
```
gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --iam-account=NAME
```
다음을 바꿉니다.
- PROJECT: 역할 바인딩을 만들 프로젝트입니다. gdcloud init이 이미 설정된 경우 --project 플래그를 생략할 수 있습니다.
- ROLE: 계정에 할당할 사전 정의된 역할입니다. Role/name 형식으로 역할을 지정합니다. 여기서 Role은 Kubernetes 유형 IAMRole이고 name은 사전 정의된 역할의 이름입니다. 예를 들어 프로젝트 뷰어 역할을 할당하려면 역할을 IAMRole/project-viewer로 설정합니다.
- NAME: 사용할 서비스 ID 계정의 이름입니다.
다른 네임스페이스 내의 역할에 계정을 바인딩합니다.
```
gdcloud iam service-accounts add-iam-policy-binding \
    --role=ROLE \
    --role-namespace=ROLE_NAMESPACE \
    --iam-account=NAME
```
다음을 바꿉니다.
- ROLE: 계정에 할당할 사전 정의된 역할입니다. Role/name 형식으로 역할을 지정합니다. 여기서 Role은 Kubernetes 유형 IAMRole이고 name은 사전 정의된 역할의 이름입니다. 예를 들어 프로젝트 뷰어 역할을 할당하려면 역할을 IAMRole/project-viewer로 설정합니다.
- ROLE_NAMESPACE: 프로젝트 네임스페이스가 아닌 계정에 바인드할 역할의 네임스페이스입니다.
- NAME: 사용할 서비스 ID 계정의 이름입니다.

서비스 ID 인증 및 사용

gdcloud 및 기타 도구가 서비스 ID로 작동하도록 구성하려면 먼저 서비스 ID의 키 파일을 사용하여 gdcloud에 인증해야 합니다. 인증이 완료되면 서비스 ID의 사용자 인증 정보를 사용하여 토큰 또는 kubeconfig 파일을 생성할 수 있습니다.

키를 사용하여 서비스 ID 승인

gdcloud auth activate-service-account 명령어는 서비스 ID로 gdcloud CLI를 인증합니다. 이를 통해 사용자 계정 대신 서비스 ID 계정 권한을 사용하여 분산 클라우드 리소스에 대한 작업을 실행할 수 있습니다.

키를 사용하여 서비스 ID를 승인합니다.

아직 없는 경우 인증 키 파일을 만듭니다.
다음 명령어를 실행하여 서비스 계정을 활성화합니다.
```
gdcloud auth activate-service-account --key-file=KEY_FILE
```
KEY_FILE을 사용자 인증 정보 키 파일의 경로로 바꿉니다(일반적으로 JSON 형식).

활성화가 완료되면 gdcloud는 사용자 인증 정보 대신 서비스 ID의 사용자 인증 정보를 사용합니다.

서비스 ID의 ID 토큰 출력

서비스 ID를 승인한 후 해당 ID의 ID 토큰을 출력할 수 있습니다. 이 토큰을 Bearer 토큰으로 사용하여 HTTP 요청을 인증할 수 있습니다. 즉, 토큰을 소유한 당사자에게 AUDIENCES 매개변수에 정의된 서비스에 대한 액세스 권한을 부여합니다.

지정된 서비스 ID 계정의 ID 토큰을 출력합니다.

gdcloud auth print-identity-token --audiences=AUDIENCES

AUDIENCES을 토큰이 사용될 수신자 또는 서비스로 바꿉니다. 잠재고객은 하나만 지정할 수 있습니다.

kubeconfig 파일 생성

서비스 ID를 승인한 후 kubeconfig 파일을 생성하여 클러스터에 인증할 수 있습니다.

gdcloud core/organization_console_url 속성을 설정합니다.
```
gdcloud config set core/organization_console_url
https://GDC_URL
```
GDC_URL을 조직의 URL로 바꿉니다.
활성 서비스 ID를 사용하여 클러스터에 액세스할 kubeconfig 파일을 생성합니다.
- 영역 클러스터의 경우:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
```
  다음을 바꿉니다.
  - KUBECONFIG_PATH: 생성된 kubeconfig 파일을 저장할 경로입니다.
  - CLUSTER_NAME: 영역별 클러스터의 이름입니다.
    
    참고: 클러스터 이름 목록은 로그인 구성 URL(
    https://GDC_URL/.well-known/login-config)에서 확인할 수 있습니다.
  - ZONE: 클러스터가 있는 영역의 이름입니다.
- 전역 API 서버의 경우:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials global-api
```
  KUBECONFIG_PATH를 생성된 kubeconfig 파일을 저장할 경로로 바꿉니다.

서비스 ID로 인증하도록 구성된 kubeconfig 파일이 생성됩니다. 다음은 YAML 파일의 예시입니다.

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <REDACTED>
    server: <REDACTED>
  name: cluster-name
contexts:
- context:
    cluster: cluster-name
    user: gdch_console-<REDACTED>_cluster-name
  name: cluster-name-gdch_console-<REDACTED>_cluster-name
current-context: cluster-name-gdch_console-gdc1-staging-gpcdemolabs-com_cluster-name
kind: Config
preferences: {}
users:
- name: gdch_console-<REDACTED>_cluster-name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - --audience=<REDACTED>
      command: gdcloud-k8s-auth-plugin
      env: null
      installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use
        plugin
      interactiveMode: Never
      provideClusterInfo: false

서비스 ID 삭제

서비스 ID를 삭제하면 ProjectServiceAccount 및 연결된 공개 키가 삭제되고, 기존 비공개 키가 무효화되며, 애플리케이션에서 해당 서비스 ID를 통해 프로젝트 리소스에 더 이상 액세스할 수 없습니다.

서비스 ID를 삭제하려면 GDC 콘솔 또는 gdcloud CLI를 사용합니다.

콘솔

GDC 콘솔에 로그인합니다.
탐색 메뉴에서 ID 및 액세스 > 서비스 ID를 선택합니다.
삭제할 서비스 ID의 체크박스를 선택합니다.
삭제를 클릭합니다.
확인 대화상자가 표시됩니다. 아래에 다음을 입력하여 확인하세요 필드에 remove을 입력합니다.
삭제를 클릭합니다.

gdcloud

다음 명령어를 실행하여 서비스 계정을 삭제합니다.

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

다음을 바꿉니다.

NAME: 삭제할 서비스 ID 계정의 이름입니다.
PROJECT: 프로젝트 ID입니다.

사용자 인증 정보 삭제

전체 서비스 ID 계정을 삭제하지 않고 특정 키 쌍을 사용 중지하려면 서비스 ID 계정에서 공개 키를 삭제하면 됩니다. 이 작업을 수행하면 해당 비공개 키가 무효화됩니다.

공개 키를 삭제하려면 GDC 콘솔 또는 gdcloud CLI를 사용합니다.

콘솔

GDC 콘솔에 로그인합니다.
탐색 메뉴에서 ID 및 액세스 > 서비스 ID를 선택합니다.
삭제할 키가 있는 서비스 ID의 이름을 클릭합니다.
삭제를 클릭합니다.
확인 대화상자에서 삭제를 클릭합니다.

gdcloud

프로젝트의 서비스 ID 계정에서 키 ID가 있는 공개 키를 삭제합니다.

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME

다음을 바꿉니다.

KEY_ID: 키의 고유 식별자입니다.
PROJECT: 프로젝트 ID입니다.
NAME: 서비스 ID 계정의 이름입니다.

서비스 ID로 인증 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

서비스 ID 만들기

계정 만들기

콘솔

gdcloud

API

사용자 인증 정보 만들기

콘솔

gdcloud

API

서비스 ID 보기

서비스 ID 목록 보기

콘솔

gdcloud

서비스 ID의 공개 키 목록 보기

서비스 ID에 권한 부여

콘솔

gdcloud

서비스 ID 인증 및 사용

키를 사용하여 서비스 ID 승인

서비스 ID의 ID 토큰 출력

kubeconfig 파일 생성

서비스 ID 삭제

콘솔

gdcloud

사용자 인증 정보 삭제

콘솔

gdcloud

서비스 ID로 인증