서비스 에이전트 만들기 및 역할 부여

Google Cloud에서 프로젝트 수준, 폴더 수준, 조직 수준의 서비스 에이전트는 Google Cloud 서비스를 사용 설정하고 사용할 때 자동으로 생성됩니다. 경우에 따라 이러한 서비스 에이전트에는 사용자 대신 리소스를 만들고 액세스할 수 있게 해주는 역할이 자동으로 부여됩니다.

필요에 따라 서비스를 사용하기 전 Google Cloud에 서비스에 대해 프로젝트 수준, 폴더 수준, 조직 수준 서비스 에이전트를 만들도록 요청할 수도 있습니다. Google Cloud에 서비스 에이전트를 만들도록 요청하면 서비스 사용 전 서비스 에이전트에 역할을 부여할 수 있습니다. 서비스 에이전트가 아직 생성되지 않았으면 서비스 에이전트에 역할을 부여할 수 없습니다.

이 옵션은 허용 정책 관리를 위해 다음 전략 중 하나를 사용할 때 유용합니다.

Terraform과 같은 선언적 프레임워크. Terraform 구성에 서비스 에이전트 역할이 포함되지 않은 경우 구성을 적용할 때 해당 역할이 취소됩니다. Terraform 구성에서 서비스 에이전트를 만들고 여기에 역할을 부여하면 해당 역할이 취소되지 않습니다.
코드 저장소에 현재 허용 정책의 사본을 저장하는 코드형 정책 시스템. Google Cloud가 서비스 에이전트에 자동으로 역할을 부여하도록 설정하면 해당 역할이 실제 허용 정책에 표시되지만 저장된 허용 정책 사본에는 표시되지 않습니다. 이러한 불일치를 해결하기 위해 이러한 역할을 잘못 취소할 수 있습니다. 서비스 에이전트를 만들고 여기에 역할을 미리 부여하면 코드 저장소와 실제 허용 정책 간의 차이를 방지하는 데 도움이 될 수 있습니다.

서비스 에이전트 만들기를 트리거한 후에는 일반적으로 자동으로 부여되는 역할을 서비스 에이전트에 부여해야 합니다. 그렇지 않으면 일부 서비스가 올바르게 작동하지 않을 수 있습니다. 이것은 사용자 요청으로 생성된 서비스 에이전트에 권한이 자동으로 부여되지 않기 때문입니다.

시작하기 전에

Resource Manager API 사용 설정
API 사용 설정
서비스 에이전트 이해

필요한 역할

서비스 에이전트 만들기를 트리거할 때는 IAM 권한이 필요하지 않습니다. 그러나 이 페이지의 다른 태스크에는 특정 IAM 권한이 필요합니다.

사용 가능한 서비스 및 엔드포인트를 나열하는 데 필요한 권한을 얻으려면 관리자에게 사용 가능한 서비스를 나열하려는 프로젝트, 폴더, 조직에 대해 서비스 사용량 뷰어(roles/serviceusage.serviceUsageViewer) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 사용 가능한 서비스 및 엔드포인트를 나열하는 데 필요한 serviceusage.services.list 권한이 포함되어 있습니다.
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
서비스 에이전트에 액세스를 부여하는 데 필요한 권한을 얻으려면 관리자에게 액세스를 부여하려는 프로젝트, 폴더, 조직에 대해 다음 IAM 역할을 부여해 달라고 요청하세요.
- 서비스 에이전트에 프로젝트에 대한 액세스 부여: 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin)
- 서비스 에이전트에 폴더에 대한 액세스 부여: 폴더 관리자(roles/resourcemanager.folderAdmin)
- 서비스 에이전트에 프로젝트, 폴더, 조직에 대한 액세스 부여: 조직 관리자(roles/resourcemanager.organizationAdmin)
역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 서비스 에이전트에 액세스를 부여하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.
필수 권한

다음 권한은 서비스 에이전트에 액세스를 부여하는 데 필요합니다.
- 서비스 에이전트에 프로젝트에 대한 액세스를 부여합니다.
  - resourcemanager.projects.getIamPolicy
  - resourcemanager.projects.setIamPolicy
- 서비스 에이전트에 폴더에 대한 액세스를 부여합니다.
  - resourcemanager.folders.getIamPolicy
  - resourcemanager.folders.setIamPolicy
- 서비스 에이전트에 조직에 대한 액세스를 부여합니다.
  - resourcemanager.organizations.getIamPolicy
  - resourcemanager.organizations.setIamPolicy
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

생성할 서비스 에이전트 식별

Google Cloud에 생성하도록 요청해야 하는 프로젝트 수준, 폴더 수준, 조직 수준 서비스 에이전트를 식별하려면 다음을 수행합니다.

사용할 서비스 및 API 엔드포인트 목록을 만듭니다. 사용 가능한 서비스 및 엔드포인트를 보려면 다음 방법 중 하나를 사용합니다.
콘솔

Google Cloud 콘솔의 API 라이브러리 페이지로 이동합니다.

API 라이브러리로 이동

API 엔드포인트는 추가 세부정보 섹션에 나열된 서비스 이름입니다.
gcloud

gcloud services list 명령어는 프로젝트에 사용 가능한 모든 서비스를 나열합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- EXPRESSION: 선택사항. 결과를 필터링하는 표현식입니다. 예를 들어 다음 표현식은 해당 이름에 googleapis.com이 포함되고 sandbox가 포함되지 않는 모든 서비스를 필터링합니다.
```
name ~ googleapis.com AND name !~ sandbox
```
  필터 표현식 목록은 gcloud topic filters를 참조하세요.
- LIMIT: 선택사항. 나열할 최대 결과 수입니다. 기본값은 unlimited입니다.
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
```
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
```
Windows(PowerShell)
```
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
```
Windows(cmd.exe)

참고: 이 명령어가 따옴표로 묶인 콘텐츠에 '를 사용하는 경우 작은따옴표를 큰따옴표로 바꿉니다. 따옴표가 중첩된 경우 \"를 사용하여 안에 있는 따옴표를 이스케이프합니다.
```
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
```
응답에는 사용 가능한 모든 서비스의 이름과 제목이 포함됩니다. API 엔드포인트는 NAME 필드의 값입니다.
REST

Service Usage API의 services.list 메서드는 프로젝트에 사용 가능한 모든 서비스를 나열합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.
- RESOURCE_TYPE: 사용 가능한 서비스를 나열하려는 리소스 유형입니다. projects, folders, organizations를 사용합니다.
- RESOURCE_ID: 사용 가능한 서비스를 나열하려는 Google Cloud 프로젝트, 폴더, 조직의 ID입니다. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다. 폴더 및 조직 ID는 123456789012와 같은 숫자입니다.
- PAGE_SIZE: 선택사항. 응답에 포함할 서비스 수입니다. 기본값은 50이고 최댓값은 200입니다. 서비스 수가 페이지 크기보다 크면 다음 결과 페이지를 검색하기 위해 사용할 수 있는 페이지로 나누기 토큰이 응답에 포함됩니다.
- NEXT_PAGE_TOKEN: 선택사항. 이 메서드의 이전 응답에서 반환된 페이지 나누기 토큰입니다. 지정된 경우 이전 응답이 종료된 위치에서 서비스 목록이 시작됩니다.
HTTP 메서드 및 URL:
```
GET https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
```
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"
PowerShell(Windows)

참고: 다음 명령어는 환경에 로그인했다고 가정합니다. gcloud 다음을 실행하여 CLI를 사용자 계정으로 바꿉니다.gcloud init 또는gcloud auth login . gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content
응답에는 리소스에 사용 가능한 모든 서비스의 이름과 제목이 포함됩니다. 사용 가능한 서비스 수가 페이지 크기보다 크면 응답에 페이지로 나누기 토큰도 포함됩니다.

API 엔드포인트는 name 필드의 값입니다.
서비스 에이전트 참조 페이지에서 각 API 엔드포인트를 검색합니다.

엔드포인트가 테이블에 나열되어 있으면 해당 엔드포인트에 대한 모든 서비스 에이전트를 찾습니다. 이메일 주소에 IDENTIFIER 자리표시자가 포함된 서비스 에이전트는 무시합니다. 이러한 서비스 에이전트는 프로젝트, 폴더, 조직용이 아니라 서비스 특정 리소스용입니다.

각 프로젝트 수준, 폴더 수준, 조직 수준 서비스 에이전트에 대해 다음을 기록합니다.
- 서비스 에이전트 이메일 주소의 형식입니다.
- 서비스 에이전트에 부여된 역할(있는 경우)입니다.

서비스 에이전트 만들기 트리거

만들려는 서비스 에이전트를 확인한 후 Google Cloud에 이를 만들도록 요청할 수 있습니다.

Google Cloud에 서비스 에이전트를 만들도록 요청할 때는 서비스 및 리소스를 제공합니다. 그러면 Google Cloud가 해당 서비스 및 리소스에 대해 모든 서비스 에이전트를 만듭니다.

gcloud

서비스 에이전트를 만들어야 하는 각 서비스에 대해 다음을 수행합니다.

서비스에 대해 서비스 에이전트 이메일 주소를 검토합니다. 이메일 주소의 자리표시자를 사용해서 서비스 에이전트를 만들려는 리소스를 확인합니다.

자리표시자	서비스 에이전트를 만들 위치
`PROJECT_NUMBER`	서비스를 사용할 각 프로젝트
`FOLDER_NUMBER`	서비스를 사용할 각 폴더
`ORGANIZATION_NUMBER`	서비스를 사용할 각 조직

각 리소스에 대해 서비스 에이전트를 만듭니다.

gcloud beta services identity create 명령어는 지정된 API 및 리소스에 대해 모든 서비스 에이전트를 만듭니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- ENDPOINT: 서비스 에이전트를 만들려는 API의 엔드포인트입니다. 예를 들면 aiplatform.googleapis.com입니다.
- RESOURCE_TYPE: 서비스 에이전트를 만들려는 리소스의 유형입니다. project, folder, organization을 사용합니다.
- RESOURCE_ID: 서비스 에이전트를 만들려는 Google Cloud 프로젝트, 폴더, 조직의 ID입니다. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다. 폴더 및 조직 ID는 123456789012와 같은 숫자입니다.
  
  한 번에 하나의 리소스에 대해 서비스 에이전트를 만들 수 있습니다. 여러 리소스에 대해 서비스 에이전트를 만들려면 각 리소스에 대해 한 번씩 명령어를 실행합니다.
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
```
gcloud beta services identity create --service=ENDPOINT \
    --RESOURCE_TYPE=RESOURCE_ID
```
Windows(PowerShell)
```
gcloud beta services identity create --service=ENDPOINT `
    --RESOURCE_TYPE=RESOURCE_ID
```
Windows(cmd.exe)
```
gcloud beta services identity create --service=ENDPOINT ^
    --RESOURCE_TYPE=RESOURCE_ID
```
응답에는 서비스의 기본 서비스 에이전트의 이메일 주소가 포함됩니다. 이 이메일 주소에는 서비스 에이전트를 만든 프로젝트, 폴더, 조직의 숫자 ID가 포함됩니다.

서비스에 기본 서비스 에이전트가 없으면 응답에 이메일 주소가 포함되지 않습니다.

다음은 기본 서비스 에이전트가 있는 서비스에 대한 응답 예시입니다.
```
Service identity created: service-232332569935@gcp-sa-aiplatform.iam.gserviceaccount.com
```
선택사항: 응답에서 서비스 에이전트 이메일 주소를 기록합니다(있는 경우). 이 이메일 주소는 서비스의 기본 서비스 에이전트를 식별합니다. 이 식별자를 사용해서 기본 서비스 에이전트에 역할을 부여할 수 있습니다.

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요. 자세한 내용은 Terraform 제공업체 참조 문서를 확인하세요.

서비스 에이전트를 만들어야 하는 각 서비스에 대해 다음을 수행합니다.

서비스에 대해 서비스 에이전트 이메일 주소를 검토합니다. 이메일 주소의 자리표시자를 사용해서 서비스 에이전트를 만들려는 리소스를 확인합니다.

자리표시자	서비스 에이전트를 만들 위치
`PROJECT_NUMBER`	서비스를 사용할 각 프로젝트
`FOLDER_NUMBER`	서비스를 사용할 각 폴더
`ORGANIZATION_NUMBER`	서비스를 사용할 각 조직

각 리소스에 대해 서비스 에이전트를 만듭니다. 예를 들어 다음 코드는 AI Platform에 대해 모든 프로젝트 수준 서비스 에이전트를 만듭니다.

참고: Terraform은 프로젝트 수준 서비스 에이전트 만들기만 지원합니다. 프로젝트 수준 및 조직 수준 서비스 에이전트 만들기를 트리거하려면 Google Cloud CLI 또는 REST API를 사용합니다.

data "google_project" "default" {
}

# Create all project-level aiplatform.googleapis.com service agents
resource "google_project_service_identity" "default" {
  provider = google-beta

  project = data.google_project.default.project_id
  service = "aiplatform.googleapis.com"
}

REST

서비스 에이전트를 만들어야 하는 각 서비스에 대해 다음을 수행합니다.

서비스에 대해 서비스 에이전트 이메일 주소를 검토합니다. 이메일 주소의 자리표시자를 사용해서 서비스 에이전트를 만들려는 리소스를 확인합니다.

자리표시자	서비스 에이전트를 만들 위치
`PROJECT_NUMBER`	서비스를 사용할 각 프로젝트
`FOLDER_NUMBER`	서비스를 사용할 각 폴더
`ORGANIZATION_NUMBER`	서비스를 사용할 각 조직

각 리소스에 대해 서비스 에이전트를 만듭니다.

Service Usage API의 services.generateServiceIdentity 메서드는 지정된 API 및 리소스에 대해 모든 서비스 에이전트를 만듭니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.
- RESOURCE_TYPE: 서비스 에이전트를 만들려는 리소스의 유형입니다. projects, folders, organizations를 사용합니다.
- RESOURCE_ID: 서비스 에이전트를 만들려는 Google Cloud 프로젝트, 폴더, 조직의 ID입니다. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다. 폴더 및 조직 ID는 123456789012와 같은 숫자입니다.
  
  한 번에 하나의 리소스에 대해 서비스 에이전트를 만들 수 있습니다. 여러 리소스에 대해 서비스 에이전트를 만들려는 경우 각 리소스에 대해 하나의 요청을 전송합니다.
- ENDPOINT: 서비스 에이전트를 만들려는 API의 엔드포인트입니다. 예를 들면 aiplatform.googleapis.com입니다.
HTTP 메서드 및 URL:
```
POST https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity
```
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity"
```
PowerShell(Windows)

참고: 다음 명령어는 환경에 로그인했다고 가정합니다. gcloud 다음을 실행하여 CLI를 사용자 계정으로 바꿉니다.gcloud init 또는gcloud auth login . gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity" | Select-Object -Expand Content
```
응답에는 요청의 상태를 나타내는 Operation이 포함됩니다. 작업 상태를 확인하려면 operations.get 메서드를 사용합니다.

완료된 작업에는 서비스의 기본 서비스 에이전트의 이메일 주소가 포함됩니다. 이 이메일 주소에는 서비스 에이전트를 만든 프로젝트, 폴더, 조직의 숫자 ID가 포함됩니다.

서비스에 기본 서비스 에이전트가 없으면 응답에 이메일 주소가 포함되지 않습니다.

다음은 기본 서비스 에이전트가 있는 서비스에 대한 완료된 작업 예시입니다.
```
{
  "name": "operations/finished.DONE_OPERATION",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.serviceusage.v1beta1.ServiceIdentity",
    "email": "service-232332569935@gcp-sa-aiplatform.iam.gserviceaccount.com",
    "uniqueId": "112245693826560101651"
  }
}
```
선택사항: 응답에서 서비스 에이전트 이메일 주소를 기록합니다(있는 경우). 이 이메일 주소는 서비스의 기본 서비스 에이전트를 식별합니다. 이 식별자를 사용해서 기본 서비스 에이전트에 역할을 부여할 수 있습니다.

서비스 에이전트에 역할 부여

Google Cloud가 프로젝트, 폴더, 조직에 대해 필요한 서비스 에이전트를 만든 후에는 서비스 에이전트의 이메일 주소를 사용해서 역할을 부여합니다.

Google Cloud에 서비스 에이전트를 만들도록 요청한 경우 일반적으로 자동으로 부여되는 역할을 서비스 에이전트에 부여해야 합니다. 그렇지 않으면 일부 서비스가 올바르게 작동하지 않을 수 있습니다. 이것은 사용자 요청으로 생성된 서비스 에이전트에 권한이 자동으로 부여되지 않기 때문입니다.

자동으로 부여되는 역할을 식별하는 방법은 생성할 서비스 에이전트 식별을 참조하세요.

서비스 에이전트의 이메일 주소 찾기

서비스 에이전트의 이메일 주소를 찾으려면 다음을 수행합니다.

gcloud

아직 서비스 에이전트의 이메일 주소 형식을 찾지 않았으면 찾습니다. 이 형식은 서비스 에이전트 참조에 설명되어 있습니다.
이메일 주소의 자리표시자를 해당 프로젝트, 폴더, 조직 번호로 바꿉니다.

또는 서비스 에이전트가 기본 서비스 에이전트이면 해당 서비스에 대해 서비스 에이전트 만들기를 트리거하여 이메일 주소를 가져올 수 있습니다. 서비스 에이전트 만들기 트리거 명령은 기본 서비스 에이전트의 이메일 주소를 반환합니다.

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요. 자세한 내용은 Terraform 제공업체 참조 문서를 확인하세요.

아직 서비스 에이전트의 이메일 주소 형식을 찾지 않았으면 찾습니다. 이 형식은 서비스 에이전트 참조에 설명되어 있습니다.
이메일 주소의 자리표시자를 적절한 프로젝트, 폴더, 조직 번호를 참조하는 표현식으로 바꿉니다.

예를 들어 다음 상황을 고려해보세요.
- 이메일 주소 형식은 service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com입니다.
- 서비스 에이전트는 default 라벨의 프로젝트용입니다.
여기에서 서비스 에이전트의 이메일 주소는 다음과 같습니다.
```
service-${data.google_project.default.number}@gcp-sa-aiplatform-cc.iam.gserviceaccount.com
```

또는 서비스 에이전트가 서비스의 기본 서비스 에이전트이면 google_project_service_identity 리소스의 email 속성으로부터 이메일 주소를 가져올 수 있습니다.

예를 들어 default 라벨의 google_project_service_identity 블록이 있으면 다음 표현식을 사용해서 서비스의 기본 서비스 에이전트의 이메일 주소를 가져올 수 있습니다.

${google_project_service_identity.default.email}

REST

아직 서비스 에이전트의 이메일 주소 형식을 찾지 않았으면 찾습니다. 이 형식은 서비스 에이전트 참조에 설명되어 있습니다.
이메일 주소의 자리표시자를 해당 프로젝트, 폴더, 조직 번호로 바꿉니다.

서비스 에이전트에 역할 부여

서비스 에이전트의 이메일 주소를 찾은 후 다른 주 구성원에 역할을 부여하는 것과 같이 여기에 역할을 부여할 수 있습니다.

콘솔

Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

IAM으로 이동
프로젝트, 폴더, 조직을 선택합니다.
액세스 부여를 클릭한 후 서비스 에이전트의 이메일 주소를 입력합니다.
드롭다운 목록에서 부여할 역할을 선택합니다.
선택사항: 역할에 조건을 추가합니다.
저장을 클릭합니다. 서비스 에이전트에 리소스에 대한 역할이 부여됩니다.

gcloud

add-iam-policy-binding 명령어를 사용하면 주 구성원에 역할을 빠르게 부여할 수 있습니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

RESOURCE_TYPE: 액세스를 관리할 리소스 유형입니다. projects, resource-manager folders, 또는 organizations를 사용합니다.
RESOURCE_ID: Google Cloud 프로젝트, 폴더 또는 조직 ID입니다. 프로젝트 ID는 my-project와 같은 영숫자입니다. 폴더 및 조직 ID는 123456789012와 같은 숫자입니다.
PRINCIPAL: 주 구성원이나 구성원의 식별자로, 대개 PRINCIPAL_TYPE:ID 형식을 따릅니다. 예를 들면 user:my-user@example.com입니다. PRINCIPAL이 가질 수 있는 값의 전체 목록은 정책 바인딩 참조를 확인하세요.

주 구성원 유형 user의 경우 식별자의 도메인 이름은 Google Workspace 도메인이나 Cloud ID 도메인이어야 합니다. Cloud ID 도메인을 설정하는 방법은 Cloud ID 개요를 참조하세요.
ROLE_NAME: 취소할 역할의 이름입니다. 다음 형식 중 하나를 사용하세요.
- 사전 정의된 역할: roles/SERVICE.IDENTIFIER
- 프로젝트 수준 커스텀 역할: projects/PROJECT_ID/roles/IDENTIFIER
- 조직 수준 커스텀 역할: organizations/ORG_ID/roles/IDENTIFIER
사전 정의된 역할의 목록은 역할 이해를 참조하세요.
CONDITION: 역할 바인딩에 추가할 조건입니다. 조건을 추가하지 않으려면 None 값을 사용하세요. 조건에 대한 자세한 내용은 조건 개요를 참조하세요.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Windows(PowerShell)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION

Windows(cmd.exe)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION

응답에는 업데이트된 IAM 정책이 포함됩니다.

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요. 자세한 내용은 Terraform 제공업체 참고 문서를 확인하세요.

# Grant the AI Platform Custom Code Service Account the Vertex AI Custom
# Code Service Agent role (roles/aiplatform.customCodeServiceAgent)
resource "google_project_iam_member" "custom_code" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.customCodeServiceAgent"
  member  = "serviceAccount:service-${data.google_project.default.number}@gcp-sa-aiplatform-cc.iam.gserviceaccount.com"
}

# Grant the primary aiplatform.googleapis.com service agent (AI Platform
# Service Agent) the Vertex AI Service Agent role
# (roles/aiplatform.serviceAgent)
resource "google_project_iam_member" "primary" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.serviceAgent"
  member  = "serviceAccount:${google_project_service_identity.default.email}"
}

REST

REST API를 사용하여 역할을 부여하려면 읽기-수정-쓰기 패턴을 사용합니다.

getIamPolicy()를 호출하여 현재 허용 정책을 읽습니다.

Resource Manager API의 getIamPolicy 메서드는 프로젝트, 폴더, 조직의 허용 정책을 가져옵니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.
- API_VERSION: 사용할 API 버전입니다. 프로젝트 및 조직에 v1을 사용합니다. 폴더에는 v2를 사용합니다.
- RESOURCE_TYPE: 정책을 관리할 리소스 유형. projects, folders 또는 organizations 값을 사용합니다.
- RESOURCE_ID: Google Cloud 프로젝트, 조직, 폴더 ID. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다. 폴더 및 조직 ID는 123456789012와 같은 숫자입니다.
- POLICY_VERSION: 반환할 정책 버전입니다. 요청에는 정책 버전 3인 최신 정책 버전이 지정되어야 합니다. 자세한 내용은 정책을 가져올 때 정책 버전 지정을 참조하세요.
HTTP 메서드 및 URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy
```
JSON 요청 본문:
```
{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}
```
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy"
```
PowerShell(Windows)

참고: 다음 명령어는 환경에 로그인했다고 가정합니다. gcloud 다음을 실행하여 CLI를 사용자 계정으로 바꿉니다.gcloud init 또는gcloud auth login . gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy" | Select-Object -Expand Content
```
API 탐색기(브라우저)

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 요청 본문을 이 도구에 붙여넣고 다른 필수 필드를 입력한 후 실행을 클릭합니다.

응답에는 리소스의 허용 정책이 포함됩니다. 예를 들면 다음과 같습니다.
```
{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:owner@example.com"
      ]
    }
  ]
}
```
텍스트 편집기를 사용하거나 프로그래매틱 방식으로 리소스의 허용 정책을 수정하여 주 구성원 또는 역할 바인딩을 추가하거나 삭제합니다. 예를 들어 새 역할 바인딩을 추가하거나, 기존 역할 바인딩을 삭제하거나, 기존 역할 바인딩에서 주 구성원을 추가 또는 삭제할 수 있습니다.
setIamPolicy()를 호출하여 업데이트된 허용 정책을 작성합니다.

Resource Manager API의 setIamPolicy 메서드는 요청의 정책을 프로젝트, 폴더, 조직의 새 허용 정책으로 설정합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.
- API_VERSION: 사용할 API 버전입니다. 프로젝트 및 조직에 v1을 사용합니다. 폴더에는 v2를 사용합니다.
- RESOURCE_TYPE: 정책을 관리할 리소스 유형. projects, folders 또는 organizations 값을 사용합니다.
- RESOURCE_ID: Google Cloud 프로젝트, 조직, 폴더 ID. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다. 폴더 및 조직 ID는 123456789012와 같은 숫자입니다.
- POLICY: 설정하려는 정책의 JSON 표현입니다. 정책 형식에 대한 자세한 내용은 정책 참조를 확인하세요.
HTTP 메서드 및 URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy
```
JSON 요청 본문:
```
{
  "policy": POLICY
}
```
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy"
```
PowerShell(Windows)

참고: 다음 명령어는 환경에 로그인했다고 가정합니다. gcloud 다음을 실행하여 CLI를 사용자 계정으로 바꿉니다.gcloud init 또는gcloud auth login . gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy" | Select-Object -Expand Content
```
API 탐색기(브라우저)

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 요청 본문을 이 도구에 붙여넣고 다른 필수 필드를 입력한 후 실행을 클릭합니다.

응답에는 업데이트된 허용 정책이 포함됩니다.

참고: 허용 정책을 코드로 취급하고 버전 제어 시스템에 저장하는 경우에는 요청으로 전송하는 정책이 아니라 반환되는 정책을 저장해야 합니다.

다음 단계

모든 서비스 에이전트 목록을 봅니다.
주 구성원에게 역할을 부여하는 다른 방법 살펴보기
워크로드의 ID 역할을 수행할 수 있는 사용자 관리 서비스 계정을 만드는 방법 알아보기
Google Cloud에서 Terraform을 사용하기 위한 권장사항 자세히 알아보기
모든 Google Cloud Terraform 샘플 살펴보기

서비스 에이전트 만들기 및 역할 부여

시작하기 전에

필요한 역할

필수 권한

생성할 서비스 에이전트 식별

콘솔

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

서비스 에이전트 만들기 트리거

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

Terraform

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

서비스 에이전트에 역할 부여

서비스 에이전트의 이메일 주소 찾기

gcloud

Terraform

REST

서비스 에이전트에 역할 부여

콘솔

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

Terraform

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

API 탐색기(브라우저)

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

API 탐색기(브라우저)

다음 단계