서비스 계정으로 인증

서비스 계정은 워크로드 또는 서비스가 리소스를 프로그래매틱 방식으로 사용하고 마이크로서비스에 안전하게 액세스하는 데 사용하는 계정입니다. 서비스 계정은 사람이 아닌 애플리케이션 또는 워크로드에서 사용하는 특수한 종류의 ID입니다. 사용자 계정과 마찬가지로 서비스 계정에는 권한과 역할을 부여할 수 있지만, 실제 사용자와 같이 로그인할 수는 없습니다.

서비스 계정은 다음과 같은 Google Distributed Cloud (GDC) 에어 갭 어플라이언스 인프라를 관리하는 데 유용합니다.

  • GDC 오프라인 어플라이언스 제어 영역 애플리케이션 프로그래밍 인터페이스(API)에 안전하게 액세스하기 위한 내부 GDC 오프라인 어플라이언스 서비스 및 워크로드
  • GDC 에어갭 어플라이언스의 고객 워크로드가 GDC 에어갭 어플라이언스 서비스에 액세스하고 승인된 애플리케이션 프로그래밍 인터페이스 (API) 호출을 할 수 있습니다.
  • GDC 에어 갭 어플라이언스와 제휴할 외부 워크로드입니다.
  • 고객 리소스에 안전하게 액세스하기 위한 GDC 오프라인 어플라이언스 서비스 또는 시스템 컨트롤러 예를 들어 서비스 계정은 베어 메탈 Kubernetes 클러스터에서 실행되는 서비스 컨트롤러가 고객이 관리하는 워크로드를 실행해야 하는 인증 및 승인 워크플로를 관리할 수 있습니다.

GDC 콘솔, gdcloud CLI 또는 API를 사용하여 계정을 관리할 수 있습니다. gdcloud CLI를 사용하면 서비스 ID 기능이 ProjectServiceAccount API를 기반으로 빌드됩니다.

시작하기 전에

서비스 계정은 프로젝트 내에서만 만들 수 있습니다. 자세한 내용은 프로젝트 만들기를 참고하세요.

서비스 ID 만들기

서비스 계정을 만드는 데 필요한 권한을 얻으려면 프로젝트 IAM 관리자에게 프로젝트 IAM 관리자 (project-iam-admin) 역할을 부여해 달라고 요청하세요.

서비스 계정에 액세스할 수 있는 사용자는 프로젝트 내의 모든 서비스 계정에 액세스할 수 있습니다.

프로젝트에서 서비스 ID를 만들려면 GDC 콘솔, gdcloud CLI 또는 API를 사용합니다.

콘솔

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

gdcloud

서비스 ID를 만듭니다.

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

다음 값을 바꿉니다.

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

이 명령어는 프로젝트 네임스페이스에 ProjectServiceAccount을 만듭니다.

API

  1. my-project-sa.yaml과 같은 ProjectServiceAccount 커스텀 리소스 YAML 파일을 만듭니다.

    apiVersion: resourcemanager.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)
  2. ProjectServiceAccount 커스텀 리소스를 관리 API 서버에 적용합니다.

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
    

    MANAGEMENT_API_SERVER_KUBECONFIG 변수를 관리 API 서버의 kubeconfig 파일 경로로 바꿉니다.

서비스 ID 보기

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

콘솔

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

gdcloud

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

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

서비스 ID에 역할 바인딩 할당

역할 바인딩을 할당하려면 적절한 권한이 있어야 합니다. 역할을 할당하는 데 필요한 권한을 얻으려면 프로젝트 IAM 관리자에게 프로젝트 IAM 관리자 (project-iam-admin) 역할을 부여해 달라고 요청하세요.

GDC 콘솔 또는 gdcloud CLI를 사용하여 역할 바인딩을 할당합니다.

콘솔

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

gdcloud

이 명령어는 지정된 역할을 ProjectServiceAccount와 바인딩하는 프로젝트 역할 바인딩을 만들고 이름을 지정합니다.

gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --iam-account=NAME

다음 값을 바꿉니다.

  • PROJECT: 역할 바인딩을 만들 프로젝트입니다. gdcloud init가 이미 설정되어 있으면 --project 플래그를 생략할 수 있습니다.
  • ROLE: ProjectServiceAccount에 할당할 사전 정의된 역할입니다. Role/name 형식으로 역할을 지정합니다. 여기서 Role은 Kubernetes 유형(예: Role 또는 ProjectRole)이고 name은 사전 정의된 역할의 이름입니다. 예를 들어 프로젝트 뷰어 역할을 할당하려면 역할을 Role/project-viewer로 설정합니다.
  • NAME: 사용할 서비스 ID의 이름입니다.

서비스 ID 삭제

프로젝트에서 서비스 계정을 삭제하려면 GDC 콘솔 또는 gdcloud CLI를 사용하세요.

서비스 ID를 삭제하면 애플리케이션에서 해당 서비스 ID를 통해 프로젝트 리소스에 액세스할 수 없습니다.

콘솔

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

gdcloud

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

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

키 쌍 만들기 및 추가하기

프로젝트에서 키 쌍을 만들고 추가하려면 GDC 콘솔, gdcloud CLI 또는 API를 사용하세요.

콘솔

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

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를 설치해야 합니다.

GDC 오프라인 어플라이언스는 비공개 키가 서명하는 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": "service_identity_name",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

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

  • project: 조직의 프로젝트 네임스페이스입니다.
  • private_key_id: 키에 할당된 ID입니다.
  • private_key: CLI에서 생성하는 PEM 형식의 ECDSA P256 비공개 키입니다.
  • name: 서비스 ID의 이름입니다.
  • token_uri: 인증 엔드포인트의 주소입니다.

API

  1. 공개 키와 비공개 키 쌍을 생성합니다. 다음 명령어는 이 용도로 자주 사용되는 도구인 openssl를 예로 사용합니다.

    openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
    openssl ec -in "key.pem" -pubout > "pub.pem"
    
  2. 공개 키를 Base64로 인코딩하고 키 ID를 가져옵니다.

    KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
    BASE64_ENCODED_KEY=$(cat pub.pem | base64)
    
  3. 이전 단계에서 생성된 키 정보를 포함하여 ProjectServiceAccount 커스텀 리소스 YAML 파일을 만들거나 업데이트합니다.

    apiVersion: resourcemanager.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)
  4. ProjectServiceAccount 커스텀 리소스를 관리 API 서버에 적용합니다.

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
    

    MANAGEMENT_API_SERVER_KUBECONFIG 변수를 관리 API 서버의 kubeconfig 파일 경로로 바꿉니다.

  5. 비공개 키가 포함된 애플리케이션 기본 사용자 인증 정보 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: 인증 엔드포인트의 주소입니다.
  6. 서비스 계정을 활성화하여 프로젝트에 키 쌍을 추가합니다.

    gdcloud auth activate-service-account –-key-file=key_file.json
    

서비스 계정의 사용자 인증 정보 나열

프로젝트의 특정 ProjectServiceAccount에서 공개 키를 나열합니다.

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

사용자 인증 정보 삭제

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

콘솔

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

gdcloud

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

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

서비스 계정 키를 사용하여 서비스 계정 승인

gdcloud 명령어를 사용하여 서비스 계정 키를 통해 서비스 계정을 활성화할 수 있습니다.

  1. 아직 서비스 계정 키 파일이 없는 경우 서비스 계정 키 파일을 만듭니다.

  2. 다음 명령어를 실행하여 서비스 계정을 활성화합니다.

    gdcloud auth activate-service-account --key-file=KEY_FILE
    

    KEY_FILE을 서비스 계정 키 파일의 경로로 바꿉니다.

    서비스 계정을 활성화하면 gdcloud는 사용자 인증 정보 대신 서비스 계정의 사용자 인증 정보를 후속 명령어에 사용합니다.