Skip to main content
Hello and welcome back. In this lesson we continue our Google Cloud IAM deep dive and focus on IAM role types: basic (primitive), predefined (service) roles, and custom roles. Understanding these will help you grant the right permissions, reduce blast radius, and apply the principle of least privilege. To ground this, imagine granting a “VM instance editor” capability to an operator who manages Compute Engine instances. That capability is represented by an IAM role — a collection of permissions — and every Google Cloud role belongs to one of three categories described below.

​
Overview: role assignment and permissions

An IAM role is a named collection of permissions you grant to a principal (user, group, or service account) on a resource. Roles are attached to policy bindings and evaluated at request time to authorize actions. Key distinctions between role types:
  • Basic (primitive) roles: Owner, Editor, Viewer — very broad and apply across a project, folder, or organization.
  • Predefined roles: Service-specific, finer-grained roles provided and maintained by Google Cloud.
  • Custom roles: User-defined roles that combine explicit permissions to meet organizational requirements.
Why role choice matters:
  • Granting overly broad roles increases blast radius when credentials are compromised.
  • Apply least privilege: grant only the permissions required for the job.
Avoid using basic (Owner/Editor/Viewer) roles in production. They grant broad access across resources and increase risk. Prefer predefined or custom roles tailored to the task.

​
Quick comparison

Role typeScopeTypical use casesExamples
Basic (primitive)Project, folder, organizationQuick experiments, short-lived test projectsroles/owner, roles/editor, roles/viewer
Predefined (service)Project, folder, organizationProduction access to a specific Google Cloud serviceroles/compute.instanceAdmin.v1, roles/storage.objectViewer
CustomProject or Organization levelFine-grained, organization-specific permission setsprojects/PROJECT_ID/roles/CustomInstanceOperator

​
1) Basic (primitive) roles

Basic roles are coarse-grained and classic:
  • Owner (roles/owner)
  • Editor (roles/editor)
  • Viewer (roles/viewer)
Pros:
  • Simple to assign and understand.
Cons:
  • Extremely broad; often grant more permissions than necessary.
  • Not recommended for production environments due to elevated risk.
Use cases:
  • Quick experimentation, learning labs, or non-production short-lived projects.
Inspecting who has basic roles on a project: 
# Retrieve the IAM policy for a project
gcloud projects get-iam-policy PROJECT_ID --format=json
Sample (shortened) output showing bindings: 
[
  {
    "role": "roles/editor",
    "members": [
      "user:alice@example.com"
    ]
  },
  {
    "role": "roles/viewer",
    "members": [
      "group:eng@example.com"
    ]
  }
]

​
2) Predefined (service) roles

Predefined roles (service roles) are published and maintained by Google Cloud. They provide narrower permission sets specific to individual services. Benefits:
  • Granularity: restricts access to required APIs and actions for a service.
  • Maintained by Google Cloud: roles evolve with service features.
Examples:
  • roles/compute.instanceAdmin.v1 — manage Compute Engine instances
  • roles/storage.objectViewer — read objects in Cloud Storage
Inspect a predefined role’s permissions: 
# Describe a predefined role
gcloud iam roles describe roles/compute.instanceAdmin.v1 --format="yaml(name,includedPermissions)"
Example output (abridged): 
name: roles/compute.instanceAdmin.v1
includedPermissions:
- compute.instances.create
- compute.instances.delete
- compute.instances.get
- compute.instances.setMetadata
# ...
Best practice:
  • When granting VM instance management privileges, prefer a relevant predefined role such as roles/compute.instanceAdmin.v1 or an even narrower predefined role if available, instead of a basic Editor.
Prefer predefined roles for most production scenarios. They provide service-focused permission sets that are more secure than basic roles while remaining easy to manage.

​
3) Custom roles

Custom roles let you define exactly which permissions a role contains. They can be created at the organization or project level and are ideal when predefined roles are too broad or don’t cover your required combination of permissions. When to use custom roles:
  • You need a role more restrictive than available predefined roles.
  • You need to combine permissions from multiple services into one role.
  • You require strict separation of duties tailored to your organization.
Create a project-level custom role example: 
gcloud iam roles create customInstanceOperator \
  --project=PROJECT_ID \
  --title="Instance Operator" \
  --description="Manage Compute Engine instances without billing or org administration permissions" \
  --permissions="compute.instances.get,compute.instances.list,compute.instances.start,compute.instances.stop"
Describe a custom role: 
gcloud iam roles describe customInstanceOperator --project=PROJECT_ID --format="yaml(name,stage,includedPermissions)"
Notes:
  • Custom roles have a lifecycle stage (e.g., ALPHA, BETA, GA, DISABLED) and can be updated over time.
  • Track changes and test custom roles before wide adoption to avoid accidental permission gaps.

​
Practical tips and commands

  • See which roles a principal has on a project:
gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:user:alice@example.com" \
  --format="table(bindings.role)"

​
Summary

  • Basic (Owner/Editor/Viewer) roles are broad, simple, and not recommended for production due to increased risk.
  • Predefined roles are Google-provided, service-specific roles that offer better granularity and are suitable for most production needs.
  • Custom roles let you compose precise permission sets and are optimal when predefined roles are too permissive or incomplete.
Always apply the principle of least privilege: choose the most restrictive role that still allows principals to perform their job.

Watch Video