커스텀 역할 생성 및 관리

이 페이지에서는 커스텀 역할을 만들고 관리하는 방법을 설명합니다.

시작하기 전에

  • 커스텀 역할을 만드는 데 필요한 권한 및 권장사항에 대해 설명하는 커스텀 역할 이해를 읽어보세요.
  • gcloud 명령줄 유틸리티를 사용하는 경우 버전 188.0.0 이상을 사용하는지 확인하세요. gcloud를 버전 188.0.0으로 업데이트하려면 다음 명령을 실행합니다. gcloud components update --version 188.0.0

리소스에 사용 가능한 권한 보기

커스텀 역할을 만들기 전에 리소스에 적용할 수 있는 권한이 무엇인지 확인하는 것이 좋습니다. 리소스에 적용 가능한 모든 권한 및 계층구조에서 해당 리소스에 속하는 리소스를 확인하려면 gcloud 명령줄 도구, Cloud Console 또는 IAM API를 사용합니다. 예를 들어 조직 및 해당 조직의 프로젝트에 적용 가능한 모든 권한을 가져올 수 있습니다.

gcloud


대상 리소스에 적용 가능한 권한 목록을 가져오려면 gcloud iam list-testable-permissions 명령을 사용합니다. 반환되는 권한은 이 리소스 및 계층구조에서 해당 리소스에 속하는 모든 리소스에 커스텀 역할을 만드는 데 사용할 수 있는 권한입니다.

다음 예에서는 프로젝트 리소스에서 테스트 가능한 권한을 나열하는 방법을 보여줍니다.

gcloud iam list-testable-permissions [PROJECT_ID]

[PROJECT_ID]는 프로젝트의 ID이며 전체 리소스 이름 형식(//cloudresourcemanager.googleapis.com/projects/PROJECT_ID)입니다. 예: //cloudresourcemanager.googleapis.com/projects/my-project-id

list-testable-permissions 명령은 수백 개의 결과를 반환할 수 있습니다. 필터식을 지정하면 결과를 제한할 수 있습니다. 다음은 가능한 결과를 발췌한 예입니다.

---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
customRolesSupportLevel: NOT_SUPPORTED
name: appengine.applications.list
onlyInPredefinedRoles: true
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---

각 권한에 커스텀 역할 지원 여부가 표시됩니다. 지원되는 권한 및 지원되지 않는 권한의 전체 목록은 커스텀 역할 권한 지원을 참조하세요.

콘솔


  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기

  2. 페이지 상단의 드롭다운에서 프로젝트를 선택합니다.
  3. 리소스의 관리자 역할 체크박스를 선택하여 해당 리소스에 적용 가능한 모든 권한을 확인합니다. 예를 들어 Compute 인스턴스 관리자 역할을 선택하면 오른쪽 패널에 Compute Engine 인스턴스에 적용 가능한 모든 권한이 표시됩니다.

API


QueryTestablePermissions는 리소스에 적용 가능한 모든 권한을 반환합니다. 반환되는 권한은 이 리소스 및 계층구조에서 해당 리소스에 속하는 모든 리소스에 커스텀 역할을 만드는 데 사용할 수 있는 권한입니다. 이 요청의 필수 입력은 전체 리소스 이름(예: //cloudresourcemanager.googleapis.com/projects/my-project)뿐입니다.

호출자는 리소스의 권한 목록이 길 경우 필요에 따라 페이지 매김을 지원할 수 있습니다.

예

full_resource_name: '//cloudresourcemanager.googleapis.com/projects/my-project'`

오류 코드

오류 코드상태 메시지
INVALID_ARGUMENT0에서 100 사이여야 합니다.
INVALID_ARGUMENT페이지 매김 토큰 인코딩이 잘못되었습니다.
INVALID_ARGUMENT페이지 매김 토큰이 잘못되었습니다.
INVALID_ARGUMENT지정된 컨테이너의 페이지 매김 토큰이 아닙니다.
INVALID_ARGUMENT페이지 매김 토큰의 시작점이 잘못되었습니다.
INVALID_ARGUMENT페이지 매김 토큰 쿠키가 잘못되었습니다.
INVALID_ARGUMENT페이지 매김 토큰이 만료되었습니다.
INVALID_ARGUMENT{full_resource_name}을 지정해야 합니다.
INVALID_ARGUMENT{full_resource_name}이 //[a-z0-9.-]/.a-z0-9.-]/와 일치하지 않습니다.

역할 메타데이터 가져오기

커스텀 역할을 만들기 전에 사전 정의된 역할과 커스텀 역할의 메타데이터를 가져오는 것이 좋습니다. 역할 메타데이터로는 역할 ID 및 역할에 포함된 권한 등이 있습니다. Google Cloud Platform 콘솔 또는 IAM API를 사용하여 메타데이터를 확인할 수 있습니다.

역할 메타데이터를 보려면 아래 방법 중 하나를 사용합니다.

gcloud


사전 정의된 역할 및 커스텀 역할의 메타데이터를 확인하려면 gcloud iam roles describe 명령을 사용합니다.

사전 정의된 역할의 메타데이터를 확인하려면 다음 gcloud 명령을 실행합니다.

gcloud iam roles describe [ROLE_NAME]

[ROLE_NAME]는 역할의 이름(예: roles/viewer)입니다.

다음 예에서는 사전 정의된 역할인 roles/iam.roleViewer에 describe 명령을 실행한 출력을 보여줍니다.

gcloud iam roles describe roles/iam.roleViewer 

description: Read access to all custom roles in the project.
etag: AA==
includedPermissions:
- iam.roles.get
- iam.roles.list
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
name: roles/iam.roleViewer
stage: GA
title: Role Viewer

커스텀 역할의 메타데이터를 확인하려면 우선 커스텀 역할이 조직 수준에서 만들어졌는지 아니면 프로젝트 수준에서 만들어졌는지 확인합니다. 커스텀 역할이 조직 수준에서 만들어진 경우 다음 gcloud 명령을 실행합니다.

gcloud iam roles describe --organization [ORGANIZATION_ID] [ROLE_NAME]

[ORGANIZATION_ID]는 조직의 ID이며 1234567 형식입니다. [ROLE_NAME]은 커스텀 역할의 이름(예: myCustomRole)입니다.

프로젝트 수준 커스텀 역할의 메타데이터를 확인하려면 다음 gcloud 명령을 실행합니다.

gcloud iam roles describe --project [PROJECT_ID] [ROLE_NAME]

[PROJECT_ID]는 프로젝트의 ID(예: my-project-id)입니다. [ROLE_NAME]은 커스텀 역할의 이름(예: myCustomRole)입니다.

자세한 내용은 gcloud iam roles describe 참조 문서를 확인하세요.

콘솔


  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기

  2. 페이지 상단의 드롭다운에서 조직 또는 프로젝트를 선택합니다.
  3. 권한을 확인할 역할의 체크박스를 하나 이상 선택합니다. 역할에 포함된 권한이 있는 경우 오른쪽 패널에 해당 권한이 표시됩니다.

역할 옆의 아이콘은 커스텀 역할(공장 모양 아이콘)인지 아니면 사전 정의된 역할(6각형 아이콘)인지를 나타냅니다.

역할 아이콘

특정 권한을 포함하는 역할을 모두 찾으려는 경우 역할 목록 상단의 필터 상자에 권한 이름을 입력합니다.

API


확인할 역할의 이름을 알고 있는 경우 roles.get 메소드를 사용하여 커스텀 역할을 가져옵니다. 역할 이름을 모르는 경우 roles.list 메소드를 사용하여 조직 또는 프로젝트의 모든 커스텀 역할을 나열합니다.

GetRole(),을 호출하려면 GetRoleRequest에 다음 필드를 설정합니다.

  • 역할의 이름(예: roles/{ROLE_NAME} 또는 organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME})

ListRoles()를 호출하려면 ListRolesRequest에 다음 필드를 설정합니다.

  • 모든 커스텀 역할을 가져올 상위 항목(예: organizations/{ORGANIZATION_ID} 또는 projects/{PROJECT_ID})

오류 코드

오류 코드상태 메시지
PERMISSION_DENIED{path}의 역할을 가져올 권한이 없습니다.
NOT_FOUND이름이 {role}인 역할을 찾을 수 없습니다.
INVALID_ARGUMENT역할 이름은 roles/{role} 또는 organizations/{organization_id}/roles/{role} 형식이어야 합니다.
PERMISSION_DENIED{path}의 역할을 나열할 권한이 없습니다.
INVALID_ARGUMENT상위 {path}가 잘못되었습니다. 상위 항목은 organizations/{organization_id} 형식이거나 비어 있어야 합니다.
INVALID_ARGUMENT역할 보기가 잘못되었습니다.

커스텀 역할 만들기

커스텀 역할을 만들려면 호출자에게 iam.roles.create 권한이 필요합니다. 기본적으로 프로젝트 또는 조직의 소유자는 이 권한을 가지므로 커스텀 역할을 만들고 관리할 수 있습니다.

조직 관리자를 비롯하여 소유자가 아닌 사용자에게는 조직 역할 관리자 역할 또는 IAM 역할 관리자 역할을 할당해야 합니다.

gcloud


새 커스텀 역할을 만들려면 gcloud iam roles create 명령을 사용합니다. 이 명령을 두 가지 방법으로 사용할 수 있습니다.

  • 역할 정의를 포함하는 YAML 파일 제공
  • 플래그를 사용하여 역할 정의 지정

커스텀 역할을 만들 때 --organization [ORGANIZATION_ID] 또는 --project [PROJECT_ID] 플래그를 사용하여 조직 수준에 적용되는지 아니면 프로젝트 수준에 적용되는지를 지정해야 합니다. 아래의 각 예에서는 프로젝트 수준으로 커스텀 역할을 만듭니다.

YAML 파일을 사용하여 커스텀 역할 만들기:

커스텀 역할의 정의를 포함하는 YAML 파일을 만듭니다. 파일의 구조는 다음과 같아야 합니다.

title: [ROLE_TITLE]
description: [ROLE_DESCRIPTION]
stage: [LAUNCH_STAGE]
includedPermissions:
- [PERMISSION_1]
- [PERMISSION_2]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_TITLE]은 역할의 별칭(예: "Role Viewer")입니다.
  • [ROLE_DESCRIPTION]은 역할에 대한 간단한 설명(예: "My custom role description")입니다.
  • [LAUNCH_STAGE]는 출시 주기에서 역할의 단계(예: ALPHA, BETA, GA)를 나타냅니다.
  • includedPermissions는 커스텀 역할에 포함할 하나 이상의 권한(예: - iam.roles.get) 목록을 지정합니다.

YAML 파일을 저장하고 다음 gcloud 명령을 실행합니다.

gcloud iam roles create [ROLE_ID] --project [PROJECT_ID] \
--file [YAML_FILE_PATH]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_ID]는 역할의 이름(예: viewer)입니다.
  • [PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다.
  • [YAML_FILE_PATH]는 커스텀 역할 정의를 포함하는 YAML 파일의 위치를 가리키는 경로입니다.

다음은 역할 정의를 만드는 방법을 보여주는 YAML 파일의 예입니다.

title: "Role Viewer"
description: "My custom role description."
stage: "ALPHA"
includedPermissions:
- iam.roles.get
- iam.roles.list

다음 예에서는 YAML 파일을 사용하여 역할을 만드는 방법을 보여줍니다.

gcloud iam roles create viewer --project my-project-id \
--file my-role-definition.yaml

역할이 정상적으로 생성되면 다음과 같은 응답이 반환됩니다.

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

플래그를 사용하여 커스텀 역할 만들기:

다음 gcloud 명령을 실행합니다.

gcloud iam roles create [ROLE_ID] --project [PROJECT_ID] \
--title [ROLE_TITLE] --description [ROLE_DESCRIPTION] \
--permissions [PERMISSIONS_LIST] --stage [LAUNCH_STAGE]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_ID]는 역할의 이름(예: viewer)입니다.
  • [PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다.
  • [ROLE_TITLE]은 역할의 별칭(예: Role Viewer)입니다.
  • [ROLE_DESCRIPTION]은 역할에 대한 간단한 설명(예: "My custom role description.")입니다.
  • [PERMISSIONS_LIST]는 커스텀 역할에 포함할 권한의 쉼표로 구분된 목록을 포함합니다. 예: iam.roles.get,iam.roles.list
  • [LAUNCH_STAGE]는 출시 주기에서 역할의 단계(예: ALPHA, BETA, GA)를 나타냅니다.

다음 예에서는 플래그를 사용하여 역할을 만드는 방법을 보여줍니다.

gcloud iam roles create viewer --project my-project-id \
--title "Role Viewer" --description "My custom role description." \
--permissions iam.roles.get,iam.roles.list --stage ALPHA

역할이 정상적으로 생성되면 다음과 같은 응답이 반환됩니다.

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

콘솔


커스텀 역할을 처음부터 새로 만드는 방법은 다음과 같습니다.

  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기

  2. 조직 드롭다운에서 조직을 선택합니다.
  3. 역할 만들기를 클릭합니다.
  4. 역할의 이름, 제목, 설명을 입력합니다.
  5. 권한 추가를 클릭합니다.
  6. 역할에 포함할 권한을 선택하고 권한 추가를 클릭합니다. 모든 서비스 및 모든 유형 드롭다운을 사용하여 서비스 및 유형에 따라 권한을 필터링하고 선택합니다.

기존의 선별된 역할을 기반으로 커스텀 역할을 만드는 방법은 다음과 같습니다.

  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기

  2. 조직 드롭다운에서 조직을 선택합니다.
  3. 새 커스텀 역할을 만드는 데 사용할 역할을 선택합니다.
  4. 기존 역할에서 역할 만들기를 클릭합니다.
  5. 역할의 이름, 제목, 설명을 입력합니다.
  6. 역할에서 제외할 권한을 선택 해제합니다.
  7. 권한 추가를 클릭하여 권한을 포함합니다.
  8. 만들기를 클릭합니다.

API


새 커스텀 역할을 만들려면 create 메소드를 사용합니다.

요청에 다음과 같은 필수 매개변수를 설정합니다.

  • 새 커스텀 역할에 사용할 role_id(예: appengine.myCustomStorageAuditor)
  • 커스텀 역할에 대한 설명(예: "이 역할은 스토리지 리소스, 용량, 액세스 정책을 나열할 액세스 권한을 부여합니다.")
  • 이 역할에 연결할 권한 목록
  • 역할의 이름 필드를 설정하면 오류가 발생합니다.

다음과 같은 선택적 매개변수도 설정하는 것이 좋습니다.

  • 커스텀 역할의 제목(예: "예제 커스텀 역할 편집자")
  • stage 값(예: GA)

stage에 사용할 수 있는 값은 ALPHA, BETA, GA, DEPRECATED 또는 DISABLED입니다.

일부 사전 정의된 역할에는 지원 중단된 권한 또는 커스텀 역할에서 허용되지 않는 권한이 포함되어 있습니다. 커스텀 역할을 만드는 데 사용한 사전 정의된 역할에 지원이 중단되었거나 제한된 권한이 하나라도 포함된 경우 작업이 실패합니다.

예

parent: '[PARENT_NAME]'
role_id: '[ROLE_ID]'
role {
    name: ''
    title: '[ROLE_TITLE]'
    description: '[ROLE_DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})",

여기에서

  • [PARENT_NAME]은 커스텀 역할을 만들 조직의 이름(예: organizations/0000000000000001) 또는 커스텀 역할을 만들 프로젝트 ID(예: projects/my-project)입니다.
  • [ROLE_ID]는 커스텀 역할의 ID입니다. 예: appengine.myCustomStorageAuditor.
  • [ROLE_TITLE]은 역할의 제목입니다. 예: Storage Auditor
  • [ROLE_DESCRIPTION]은 역할의 목적에 대한 설명입니다.
  • [PERMISSION]은 커스텀 역할에 포함할 권한입니다.

오류 코드

오류 코드상태 메시지
PERMISSION_DENIED{parent}에 역할을 만들 권한이 없습니다.
ALREADY_EXISTS이름이 {role_id}인 역할이 {parent}에 이미 있습니다.
INVALID_ARGUMENT상위 {parent}가 잘못되었습니다. 상위 항목은 organizations/{organization_id} 형식이어야 합니다.
INVALID_ARGUMENT{role_id} role_id가 잘못되었습니다. {pattern} 패턴과 일치하지 않습니다.
INVALID_ARGUMENT역할의 권한 수가 최대값인 {max}보다 큽니다.
INVALID_ARGUMENT{stage} role.stage가 잘못되었습니다.

기존 커스텀 역할 수정

읽기-수정-쓰기

리소스의 커스텀 역할과 같은 메타데이터를 업데이트하는 일반적인 패턴은 현재 상태를 읽고, 데이터를 로컬에서 업데이트하고, 수정된 데이터를 전송하여 기록하는 것입니다. 이 패턴에서는 서로 독립된 둘 이상의 프로세스가 동시에 시퀀스를 시도할 경우 충돌이 발생할 수 있습니다. 예를 들어 프로젝트 소유자 두 명이 동시에 상충하는 역할 변경을 시도할 경우 변경이 일부 실패할 수 있습니다. Cloud IAM은 커스텀 역할에서 etag 속성을 사용하여 이 문제를 해결합니다. 이 속성은 마지막 요청 이후에 커스텀 역할이 변경되었는지 여부를 확인하는 데 사용됩니다. etag 값과 함께 Cloud IAM에 요청을 보내면 Cloud IAM은 요청의 etag 값을 커스텀 역할에 연결된 기존 etag 값과 비교합니다. etag 값이 일치하는 경우에만 변경사항이 기록됩니다.

역할을 업데이트하려면 우선 roles.get()을 사용하여 역할을 가져오고, 역할을 업데이트하고, roles.patch()를 사용하여 업데이트된 역할을 기록합니다. roles.get()에서 해당 정책에 etag 값이 있는 경우에만 역할을 설정할 때 etag 값을 사용하세요.

gcloud


커스텀 역할을 업데이트하려면 gcloud iam roles update 명령을 사용합니다. 이 명령을 두 가지 방법으로 사용할 수 있습니다.

  • 업데이트된 역할 정의를 포함하는 YAML 파일 제공
  • 플래그를 사용하여 업데이트된 역할 정의 지정

커스텀 역할을 업데이트할 때 --organization [ORGANIZATION_ID] 또는 --project [PROJECT_ID] 플래그를 사용하여 조직 수준에 적용되는지 아니면 프로젝트 수준에 적용되는지를 지정해야 합니다. 아래의 각 예에서는 프로젝트 수준으로 커스텀 역할을 만듭니다.

YAML 파일을 사용하여 커스텀 역할 업데이트:

다음 gcloud 명령을 실행하여 역할의 현재 정의를 가져옵니다.

gcloud iam roles describe [ROLE_ID] --project [PROJECT_ID]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_ID]는 업데이트할 역할의 이름(예: viewer)입니다.
  • [PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다.

describe 명령은 역할의 정의를 반환하며, 역할의 현재 버전을 고유하게 식별하는 etag 값을 포함합니다. 동시에 발생하는 역할 변경사항을 덮어쓰지 않도록 업데이트된 역할 정의에 etag 값을 제공해야 합니다.

describe 명령은 다음과 같은 출력을 반환합니다.

description: [ROLE_DESCRIPTION]
etag: [ETAG_VALUE]
includedPermissions:
- [PERMISSION_1]
- [PERMISSION_2]
name: [ROLE_ID]
stage: [LAUNCH_STAGE]
title: [ROLE_TITLE]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_DESCRIPTION]은 역할에 대한 간단한 설명(예: "My custom role description")입니다.
  • [ETAG_VALUE]는 역할의 현재 버전에 대한 고유 식별자(예: BwVkBkbfr70=)입니다.
  • includedPermissions는 커스텀 역할에 포함할 하나 이상의 권한(예: - iam.roles.get) 목록을 지정합니다.
  • [ROLE_ID]는 역할의 계층적 ID로서, 역할이 프로젝트 수준에서 생성되었는지 아니면 조직 수준에서 생성되었는지에 따라 다릅니다. 예: projects/my-project-id/roles/viewer
  • [LAUNCH_STAGE]는 출시 주기에서 역할의 단계(예: ALPHA, BETA, GA)를 나타냅니다.
  • [ROLE_TITLE]은 역할의 별칭(예: "Role Viewer")입니다.

역할을 업데이트하려면 출력된 역할 정의를 YAML 파일에 포함하거나 원본 YAML 파일을 출력된 etag 값으로 업데이트합니다.

다음은 describe 명령의 출력을 포함하고 Cloud Storage 권한 두 개를 추가하는 YAML 파일의 예입니다.

description: My custom role description.
etag: BwVkBkbfr70=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

YAML 파일을 저장하고 다음 gcloud 명령을 실행합니다.

gcloud iam roles update [ROLE_ID] --project [PROJECT_ID] \
--file [YAML_FILE_PATH]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_ID]는 업데이트할 역할의 이름(예: viewer)입니다.
  • [PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다.
  • [YAML_FILE_PATH]는 업데이트된 커스텀 역할 정의를 포함하는 YAML 파일의 위치를 가리키는 경로입니다.

다음 예에서는 YAML 파일을 사용하여 역할을 업데이트하는 방법을 보여줍니다.

gcloud iam roles update viewer --project my-project-id \
--file my-role-definition.yaml

역할이 정상적으로 업데이트되면 다음과 같은 응답이 반환됩니다.

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

플래그를 사용하여 커스텀 역할 업데이트:

해당 플래그를 사용하여 역할 정의의 각 부분을 업데이트할 수 있습니다. 사용 가능한 모든 플래그의 목록은 gcloud iam roles update 항목을 참조하세요.

다음 플래그를 사용하여 권한을 추가하거나 삭제할 수 있습니다.

  • --add-permissions [PERMISSIONS]: 역할에 하나 이상의 쉼표로 구분된 권한을 포함합니다.
  • --remove-permissions [PERMISSIONS]: 역할에서 하나 이상의 쉼표로 구분된 권한을 삭제합니다.

다른 방법으로, --permissions [PERMISSIONS] 플래그를 사용하고 기존 권한 목록을 대체할 쉼표로 구분된 권한 목록을 제공하여 간편하게 새 권한을 지정할 수 있습니다.

역할 정의의 다른 항목을 업데이트하려면 다음 gcloud 명령을 실행합니다.

gcloud iam roles update [ROLE_ID] --project [PROJECT_ID] \
--title [ROLE_TITLE] --description [ROLE_DESCRIPTION] \
--stage [LAUNCH_STAGE]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_ID]는 역할의 이름(예: viewer)입니다.
  • [PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다.
  • [ROLE_TITLE]은 역할의 별칭(예: Role Viewer)입니다.
  • [ROLE_DESCRIPTION]은 역할에 대한 간단한 설명(예: "My custom role description.")입니다.
  • [LAUNCH_STAGE]는 출시 주기에서 역할의 단계(예: ALPHA, BETA, GA)를 나타냅니다.

다음 예에서는 플래그를 사용하여 역할에 권한을 추가하는 방법을 보여줍니다.

gcloud iam roles update viewer --project my-project-id \
--add-permissions storage.buckets.get,storage.buckets.list

역할이 정상적으로 업데이트되면 다음과 같은 응답이 반환됩니다.

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

콘솔


  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기

  2. 조직 드롭다운에서 조직을 선택합니다.
  3. 커스텀 역할을 클릭합니다.
  4. 역할 수정을 클릭합니다.
  5. 권한 추가를 클릭하여 역할에 새 권한을 추가합니다.
  6. 권한을 선택 해제하여 역할에서 권한을 삭제합니다.
  7. 업데이트를 클릭하여 수정한 역할을 저장합니다.

API


기존 커스텀 역할을 수정하려면 Role UpdateRole(UpdateRoleRequest) 메소드를 사용합니다.

수정할 커스텀 역할의 ID를 알고 있는 경우 roles.get() 메소드를 사용하여 역할을 가져온 후 roles.patch()를 사용하여 역할을 업데이트합니다.

수정할 커스텀 역할의 ID를 모르는 경우 ListRoles()를 사용하여 모든 역할을 나열한 후 역할을 찾습니다. roles.list()는 리소스를 참조하는 모든 역할의 목록을 반환합니다. 그런 다음 roles.patch()를 사용하여 역할을 업데이트합니다.

roles.patch()에 다음과 같은 필수 매개변수를 설정합니다.

  • 역할의 이름(예: organizations/{ORGANIZATION_ID}/roles/{ROLE_ID})

필요한 경우 update_mask 필드를 설정하여 이후에 업데이트될 수 있는 필드를 지정합니다.

예

name: '[ROLE_NAME]'
role {
  name: '[ROLE_NAME]'
  title: '[ROLE_TITLE]'`
  description: '[ROLE_DESCRIPTION]'
  included_permissions: '[PERMISSION]'
  included_permissions: '[PERMISSION]'
})"

여기에서

  • [ROLE_NAME]은 역할의 이름입니다. 예: organizations/123456/roles/appengine.customRoleEditor. roles/{ROLE_NAME}, organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME} 또는 projects/{PROJECT_ID}/roles/{ROLE_NAME} 형식일 수 있습니다.

참고: 역할에 포함된 [ROLE_NAME]은 비워 두는 것이 좋습니다. 역할에 포함된 이름이 비어 있지 않고 두 이름이 일치하지 않으면 메소드에서 오류를 반환합니다.

  • [ROLE_TITLE]은 역할의 제목입니다. 예: New custom editor.
  • [ROLE_DESCRIPTION]은 역할에 대한 설명입니다. 예: "편집자 역할에 대한 새로운 상세 설명"
  • [PERMISSION]은 역할에 포함할 권한입니다. 예: storage.objects.update

오류 코드

오류 코드상태 메시지
PERMISSION_DENIED역할을 업데이트할 권한이 없습니다.
INVALID_ARGUMENT사전 정의된 역할은 업데이트할 수 없습니다.
INVALID_ARGUMENT요청의 이름([ROLE_NAME])과 역할의 이름([ROLE_NAME])이 일치해야 합니다.
INVALID_ARGUMENT[PERMISSION] 권한이 잘못되었습니다.
ABORTED정책이 동시에 변경되어 etag가 일치하지 않습니다. 재시도 간격을 늘려가면서 전체 읽기-수정-쓰기를 다시 시도하세요.

일부 사전 정의된 역할에는 지원 중단된 권한 또는 커스텀 역할에서 허용되지 않는 권한이 포함되어 있습니다. 커스텀 역할을 만드는 데 사용한 사전 정의된 역할에 지원이 중단되었거나 제한된 권한이 하나라도 포함된 경우 작업이 실패합니다.

커스텀 역할 사용 중지

커스텀 역할을 사용 중지할 수 있습니다. 역할을 사용 중지하면 역할과 관련된 정책 바인딩이 비활성화됩니다. 즉, 사용자에게 역할을 부여해도 역할의 권한이 부여되지 않습니다.

gcloud


커스텀 역할을 사용 중지하려면 gcloud iam roles update 명령을 사용하여 출시 단계를 DISABLED로 설정합니다. 기존 커스텀 역할 수정 섹션의 gcloud 탭에서 설명한 것처럼, 다음과 같은 두 가지 방법으로 기존 커스텀 역할을 업데이트할 수 있습니다.

  • 업데이트된 역할 정의를 포함하는 YAML 파일 제공
  • 플래그를 사용하여 업데이트된 역할 정의 지정

기존 커스텀 역할을 사용 중지하는 가장 쉬운 방법은 --stage 플래그를 사용하고 DISABLED로 설정하는 것입니다. 다음 gcloud 명령을 실행하면 됩니다.

gcloud iam roles update [ROLE_ID] --project [PROJECT_ID] \
--stage DISABLED

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_ID]는 역할의 이름(예: viewer)입니다.
  • [PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다. 역할이 1234567과 같이 조직 수준에서 생성된 경우 --organization [ORGANIZATION_ID] 플래그를 사용할 수도 있습니다.

다음 예에서는 역할을 사용 중지하는 방법을 보여줍니다.

gcloud iam roles update viewer --project my-project-id \
--stage DISABLED

역할이 정상적으로 업데이트되면 다음과 같은 응답이 반환됩니다.

description: My custom role description.
etag: BwVkB5NLIQw=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: DISABLED
title: Role Viewer

콘솔


  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기

  2. 페이지 상단에서 '프로젝트 선택' 드롭다운을 클릭합니다.
  3. 조직 또는 프로젝트를 선택합니다.
  4. 커스텀 역할을 선택하고 사용 중지를 클릭합니다.

API


커스텀 역할을 사용 중지하려면 roles.patch() 메소드를 사용합니다.

사용 중지할 커스텀 역할의 ID를 알고 있는 경우 roles.get() 메소드를 사용하여 역할을 가져옵니다. 역할의 stage 속성을 DISABLED로 변경하고 roles.patch() 메소드를 호출하여 역할을 업데이트합니다.

사용 중지할 커스텀 역할의 ID를 모르는 경우 roles.list()를 사용하여 모든 역할을 나열한 후 역할을 찾습니다. roles.list()는 리소스를 참조하는 모든 역할의 목록을 반환합니다. 사용 중지할 역할을 찾아서 rolelaunchstage 속성을 DISABLED,로 변경하고 roles.patch() 메소드를 호출하여 역할을 업데이트합니다.

역할을 사용 중지하려면 다음 필드를 설정합니다.

  • 이름을 역할의 전체 이름(organizations/{organization-id}/roles/{role}.)으로 설정합니다.
  • Role,에서 stage를 DISABLED.로 설정합니다.
  • update_mask를 'paths: stage'로 설정합니다.

역할을 다시 사용 설정하려면 역할을 사용 중지하는 위 프로세스를 따르면서 역할의 stage 속성을 ALPHA, BETA 또는 GA로 설정합니다.

예

name: 'organizations/123456/roles/appengine.customRoleEditor'
role {
   name: 'organizations/123456/roles/appengine.customRoleEditor'`
   stage: 'DISABLED'
}
update_mask {
 paths:  stage
}

오류 코드

오류 코드상태 메시지
PERMISSION_DENIED역할을 업데이트할 권한이 없습니다.
INVALID_ARGUMENT선별된 역할은 업데이트할 수 없습니다.
INVALID_ARGUMENT요청의 이름([ROLE_NAME])과 역할의 이름([ROLE_NAME])이 일치해야 합니다.
INVALID_ARGUMENT[PERMISSION] 권한이 잘못되었습니다.
ABORTED정책이 동시에 변경되었습니다. 재시도 간격을 늘려가면서 전체 읽기-수정-쓰기를 다시 시도하세요.

역할 나열

gcloud


프로젝트 또는 조직의 커스텀 역할 및 사전 정의된 역할을 나열하려면 gcloud iam roles list 명령을 사용합니다.

다음 gcloud 명령을 실행하면서 프로젝트 수준 또는 조직 수준 커스텀 역할을 지정하여 커스텀 역할을 나열합니다.

gcloud iam roles list --project [PROJECT_ID]

[PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다. 역할이 1234567과 같이 조직 수준에서 생성된 경우 --organization [ORGANIZATION_ID] 플래그를 사용할 수도 있습니다.

--show-deleted 플래그를 지정하여 삭제된 역할을 나열할 수도 있습니다.

다음 gcloud 명령을 실행하여 사전 정의된 역할을 나열합니다.

gcloud iam roles list

콘솔


  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기


    프로젝트의 모든 커스텀 역할이 페이지에 나열됩니다.

API


roles.list() 메소드를 사용하면 조직 또는 프로젝트에 정의된 모든 커스텀 역할을 나열할 수 있습니다. 요청의 상위 항목 필드를 ""로 설정하여 사전 정의된 역할을 나열할 수도 있습니다.

roles.list()를 호출하려면 요청에 다음 필드를 설정합니다.

  • 모든 커스텀 역할을 가져오는 데 사용할 상위 항목. 예를 들면 다음과 같습니다.
    • projects/{PROJECT_ID}
    • organizations/{ORGANIZATION_ID}

각 역할의 권한을 결과에 포함하려면 view 필드를 RoleView::FULL로 설정합니다.

최근에 삭제된 역할을 결과에 포함하려면 show_deleted 필드를 참으로 설정합니다.

선별된 역할을 모두 나열하려면 상위 항목을 ''(빈 문자열)로 설정합니다.

오류 코드

오류 코드상태 메시지
PERMISSION_DENIED{path}의 역할을 나열할 권한이 없습니다.
INVALID_ARGUMENT상위 {path}가 잘못되었습니다. 상위 항목은 organizations/{organization_id} 또는 projects/{project_id} 형식이거나 비어 있어야 합니다.
INVALID_ARGUMENT역할 보기가 잘못되었습니다.

리소스에 부여 가능한 역할 보기

gcloud


특정 리소스에 적용되는 모든 역할의 목록을 반환하려면 gcloud iam list-grantable-roles 명령어를 사용합니다.

다음 gcloud 명령을 실행하여 부여 가능한 역할을 나열합니다.

gcloud iam list-grantable-roles [RESOURCE]

[RESOURCE]는 확인할 리소스의 전체 리소스 이름(예: //cloudresourcemanager.googleapis.com/projects/my-project)입니다.

원하는 리소스에 따라 매우 많은 역할이 반환될 수 있습니다. 필터식을 지정하면 결과를 제한할 수 있습니다.

콘솔


  1. GCP 콘솔에서 IAM 페이지를 엽니다.

    IAM 페이지 열기

  2. 페이지 상단에서 '프로젝트 선택' 드롭다운을 클릭합니다.
  3. 역할을 확인할 프로젝트 또는 조직을 선택합니다.
  4. 추가를 클릭합니다.
  5. 구성원에 구성원의 이메일 주소를 입력합니다.

역할 드롭다운에 커스텀 역할을 포함하여 구성원에게 부여할 수 있는 모든 역할이 표시됩니다.

API


QueryGrantableRoles는 리소스가 참조할 수 있는 모든 역할의 목록을 반환합니다. 권한을 갖지 않는 역할은 포함되지 않습니다. 요청의 필수 매개변수는 전체 리소스 이름(예: //cloudresourcemanager.googleapis.com/projects/my-project)뿐입니다. 필요한 경우 호출자는 응답의 Role에 역할에 포함된 모든 권한을 포함할지 여부를 지정하는 RoleView를 제공할 수 있습니다.

예

full_resource_name: '//automatedtests.googleapis.com/projects/my-project/buckets/bucket1'`

오류 코드

오류 코드상태 메시지
INVALID_ARGUMENT{full_resource_name}을 지정해야 합니다.
INVALID_ARGUMENT{full_resource_name}이 //[a-z0-9.-]/와 일치하지 않습니다.

커스텀 역할 삭제

gcloud


커스텀 역할을 삭제하려면 gcloud iam roles delete 명령을 사용합니다. 역할이 새 IAM 정책 바인딩을 만드는 데 사용할 수 없도록 일시정지됩니다.

다음 gcloud 명령을 실행하여 커스텀 역할을 삭제합니다.

gcloud iam roles delete [ROLE_ID] --project [PROJECT_ID]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_ID]는 역할의 이름(예: viewer)입니다.
  • [PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다. 역할이 1234567과 같이 조직 수준에서 생성된 경우 --organization [ORGANIZATION_ID] 플래그를 사용할 수도 있습니다.

--show_deleted 플래그를 포함하지 않으면 역할이 gcloud iam roles list에 포함되지 않습니다. 삭제된 역할은 list 응답의 deleted: true 블록에 다음과 같이 표시됩니다.

---
deleted: true
description: My custom role description.
etag: BwVkB5NLIQw=
name: projects/my-project-id/roles/viewer
title: Role Viewer
---

역할이 삭제된 후 기존 바인딩은 유지되지만 비활성 상태입니다. 7일 이내에 역할을 삭제 취소할 수 있습니다. 7일이 지나면 역할이 30일 동안 영구 삭제 프로세스에 들어갑니다.

이 프로세스 중에는 역할 및 역할에 연결된 모든 바인딩이 영구적으로 삭제되며, 같은 역할 ID로 새 역할을 만들 수 없습니다. 최초 삭제 요청으로부터 37일이 지나서 역할이 영구적으로 삭제된 후에는 삭제된 역할의 ID를 사용하여 새 역할을 만들 수 있습니다.

콘솔


  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기

  2. 삭제할 역할을 선택하고 페이지 상단의 휴지통 아이콘을 클릭합니다.

역할이 새 IAM 정책 바인딩을 만드는 데 사용할 수 없도록 일시정지됩니다. 기존 바인딩은 유지되지만 비활성 상태입니다. 7일 이내에 역할을 삭제 취소할 수 있습니다. 7일이 지나면 역할이 30일 동안 영구 삭제 프로세스에 들어갑니다.

이 프로세스 중에는 역할 및 역할에 연결된 모든 바인딩이 영구적으로 삭제되며, 같은 역할 ID로 새 역할을 만들 수 없습니다. 최초 삭제 요청으로부터 37일이 지나서 역할이 영구적으로 삭제된 후에는 삭제된 역할의 ID를 사용하여 새 역할을 만들 수 있습니다.

API


roles.delete는 역할을 삭제합니다. 역할이 새 IAM 정책 바인딩을 만드는 데 사용할 수 없도록 일시정지됩니다.

name은 다음 형식일 수 있습니다.

  • organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}
  • projects/{PROJECT_ID}/roles/{ROLE_NAME}

요청에 show_deleted를 설정하지 않으면 역할이 list에 포함되지 않습니다. 역할이 이 상태이면 역할에 포함된 deleted 부울 값이 참으로 설정됩니다.

기존 바인딩은 유지되지만 비활성 상태입니다. 7일 이내에 역할을 삭제 취소할 수 있습니다. 7일이 지나면 역할이 30일 동안 영구 삭제 프로세스에 들어갑니다.

이 프로세스 중에는 역할 및 역할에 연결된 모든 바인딩이 영구적으로 삭제되며, 같은 역할 ID로 새 역할을 만들 수 없습니다. 최초 삭제 요청으로부터 37일이 지나서 역할이 영구적으로 삭제된 후에는 삭제된 역할의 ID를 사용하여 새 역할을 만들 수 있습니다.

오류 코드

오류 코드상태 메시지
PERMISSION_DENIED{path}의 역할을 삭제할 권한이 없습니다.
FAILED_PRECONDITION{ROLE_NAME} 역할은 이미 삭제되었으므로 삭제할 수 없습니다.
FAILED_PRECONDITION예약된 {ROLE_NAME} 역할은 삭제할 수 없습니다.
INVALID_ARGUMENT선별된 역할은 삭제 상태일 수 없습니다.

커스텀 역할 삭제 취소

gcloud


커스텀 역할을 삭제 취소하려면 gcloud iam roles undelete 명령을 사용합니다. 역할을 삭제 취소하면 역할이 이전 상태로 돌아갑니다.

삭제 후 7일 이내에만 역할을 삭제 취소할 수 있습니다. 7일이 지나면 역할이 영구적으로 삭제되고 역할에 연결된 모든 바인딩이 삭제됩니다.

다음 gcloud 명령을 실행하여 커스텀 역할을 삭제 취소합니다.

gcloud iam undelete [ROLE_ID] --project [PROJECT_ID]

다음은 각 자리표시자 값에 대한 설명입니다.

  • [ROLE_ID]는 역할의 이름(예: viewer)입니다.
  • [PROJECT_ID]는 프로젝트의 이름(예: my-project-id)입니다. 역할이 1234567과 같이 조직 수준에서 생성된 경우 --organization [ORGANIZATION_ID] 플래그를 사용할 수도 있습니다.

다음 예에서는 커스텀 역할을 삭제 취소하는 방법을 보여줍니다.

gcloud iam roles undelete viewer --project my-project-id

역할이 정상적으로 삭제 취소되면 다음과 같은 응답이 반환됩니다.

description: My custom role description.
etag: BwVkCAx9W6w=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

콘솔


  1. GCP 콘솔에서 역할 페이지로 이동합니다.

    역할 페이지 열기

  2. 삭제 취소할 역할을 찾아서 행 끝의 더보기 아이콘을 클릭하고 삭제 취소를 클릭합니다.

삭제 후 7일 이내에만 역할을 삭제 취소할 수 있습니다. 7일이 지나면 역할이 영구적으로 삭제되고 역할에 연결된 모든 바인딩이 삭제됩니다.

API


roles.undelete는 역할을 이전 상태로 되돌립니다.

name은 다음 형식일 수 있습니다.

  • organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}
  • projects/{PROJECT_ID}/roles/{ROLE_NAME}

삭제 후 7일 이내에만 역할을 삭제 취소할 수 있습니다. 7일이 지나면 역할이 영구적으로 삭제되고 역할에 연결된 모든 바인딩이 삭제됩니다.

오류 코드

오류 코드상태 메시지
PERMISSION_DENIED{path}의 역할을 삭제 취소할 권한이 없습니다.
FAILED_PRECONDITION삭제되지 않은 역할은 삭제 취소할 수 없습니다.
FAILED_PRECONDITION예약된 {ROLE_NAME} 역할은 삭제 취소할 수 없습니다.
INVALID_ARGUMENT사전 정의된 역할은 삭제 취소할 수 없습니다.
이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

이 페이지
문서에 대한 의견
Cloud ID 및 액세스 관리 문서
제품에 대한 의견