Google Cloud IAM Roles Explained: Basic vs Predefined vs Custom

IAM roles in simple terms

A permission is a single allowed action. storage.objects.get is a permission. It lets a principal read one Cloud Storage object. That is all it does.

A role is a bundle of permissions grouped together under a single name. roles/storage.objectViewer bundles storage.objects.get and storage.objects.list together. When you grant that role, the identity gets both permissions at once.

You grant roles to principals: a user, a group, or a service account. The role binding specifies who gets it and on which resource. The principal, the role, and the resource scope are the three parts of every access decision in GCP. For a broader introduction to how this fits together, see What Is IAM in GCP.

How IAM roles work in Google Cloud

Every IAM access decision in GCP comes down to three things: a principal (who), a role (what permissions), and a resource (on what). When a principal makes a request, GCP checks whether any binding grants a role that includes the required permission on that resource.

The permissions come from the role. The role is attached through an IAM policy on the resource. A policy is the complete set of role bindings that apply to a resource. You never write permissions directly into a policy; you write role bindings.

You can bind a role at different scopes within the resource hierarchy: organisation, folder, project, or an individual resource like a specific Cloud Storage bucket or a Secret Manager secret. A binding at a higher level is inherited by everything below it. A binding at a lower level affects only that resource.

The three types of IAM roles

GCP organises its roles into three families. Each exists for a different reason and comes with different trade-offs on security, maintenance, and flexibility.

Basic roles

Basic roles predate the modern IAM system. There are three: roles/viewer, roles/editor, and roles/owner. They were designed before Google Cloud had the granular permission model it has today. The problem is not just that they are broad; it is that they are broad across every service in the project at once:

• Viewer grants read-only access to most resources across all services in the project

• Editor grants read and write on most resources, including deleting Cloud SQL databases and modifying service configurations

• Owner grants everything Editor has, plus the ability to modify IAM policies on the project itself

Predefined roles

Predefined roles are the default choice for almost every real access decision. Google creates and maintains them. Each is scoped to a specific service and a specific job function within that service.

Cloud Storage shows how the progression works in practice:

• roles/storage.objectCreator lets a principal upload new objects but not read existing ones

• roles/storage.objectViewer lets a principal read and list objects, with no write or delete access

• roles/storage.objectAdmin covers create, read, update, and delete for objects but not bucket configuration

• roles/storage.admin covers full bucket and object administration

An application that only uploads reports should get objectCreator, not objectAdmin. That is predefined roles working exactly as intended: a purpose-built role for a specific job. Google keeps predefined roles current as services evolve, so your access stays accurate without any maintenance from you.

Before assuming there is no predefined role for a task, search the catalog. Most services have roles at several granularity levels for common job functions.

# List all predefined roles for a specific service
gcloud iam roles list --filter="name:roles/storage"

# Search across all services by keyword
gcloud iam roles list --filter="title:viewer"

Custom roles

Custom roles let you select individual permissions from GCP’s permission catalog and bundle them into a role you define. They exist for cases where no predefined role fits because the closest option includes specific permissions you do not want to grant.

A CI pipeline that deploys Cloud Run services is a typical example. The nearest predefined role might include permissions to modify IAM bindings or access sensitive configuration. A custom role lets you include only the deployment permissions the pipeline actually needs.

# ci-deployer-role.yaml
title: "CI Deployer"
description: "Deploy Cloud Run services without IAM access"
stage: GA
includedPermissions:
  - run.services.create
  - run.services.update
  - run.services.get
  - run.services.list
  - artifactregistry.repositories.downloadArtifacts

# Create the custom role from the YAML definition
gcloud iam roles create ciDeployer \
  --project=my-app-prod \
  --file=ci-deployer-role.yaml

When to use each type of IAM role

The right role type depends on the situation. Here are concrete scenarios with the correct approach for each.

Basic vs predefined vs custom roles

Most teams should use predefined roles by default. That is not a compromise; it is the correct answer for the vast majority of access decisions in GCP.

• Predefined roles are the safest default. Google scopes them tightly to a specific service and maintains them over time. You do not need to build or audit the permission list yourself. Start here for every new access decision.

• Basic roles are almost always the wrong answer. They exist in GCP for historical reasons, not because they represent good practice. Any argument for using a basic role in production can be solved more safely with a predefined role. The only defensible use is a short-lived personal sandbox where the data has no real consequences.

• Custom roles require the most maintenance. They give you precise control, but that precision comes with a cost. You own the permission list and must keep it accurate as services change. Use custom roles only after doing a thorough search of the predefined catalog and finding no suitable match.

• When predefined roles feel too broad, check the binding scope first. Sometimes the issue is not the role choice but where it is applied. Binding roles/storage.objectAdmin on a specific bucket instead of the whole project is often more useful than building a custom role.

For a deeper look at the trade-offs between basic and predefined roles specifically, see Basic vs Predefined Roles.

How to choose the right IAM role

Work through this sequence for every access decision. Skipping steps is where over-permissioning starts. For broader context on why this matters, read the guide on least privilege in GCP.

1. Identify the specific action the principal needs to perform. Not the general job function. The specific API call or operation. This shapes everything that follows.

2. Search the predefined catalog for that service. Run gcloud iam roles list —filter=“name:roles/SERVICE” and review all candidates. Most services have roles at several granularity levels for common job functions.

3. Inspect the role before granting it. Run gcloud iam roles describe roles/ROLE_NAME and read the full permission list. Role names are descriptive but not exhaustive. You will regularly find that a role includes permissions you did not expect.

4. Choose the narrowest predefined role that covers the task. If the job is reading, grant a viewer role. Grant a writer role only after write access is confirmed as necessary.

5. Bind at the narrowest resource scope. Grant the role on the specific bucket, dataset, secret, or topic rather than at project level, wherever the service supports resource-level IAM.

6. Use a custom role only if predefined genuinely over-grants. If a predefined role includes permissions you have a specific reason not to grant, and binding scope alone cannot solve the problem, build a custom role. Document why it was created.

7. Verify what was applied. After binding, run get-iam-policy on the resource and confirm the binding looks exactly as intended.

# Step 2: Search predefined roles for a service
gcloud iam roles list --filter="name:roles/storage"

# Step 3: Inspect what a role actually grants
gcloud iam roles describe roles/storage.objectViewer

# Step 5: Bind at resource scope, not project scope
gcloud storage buckets add-iam-policy-binding gs://my-app-prod-reports \
  --member="serviceAccount:uploader@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectCreator"

# Step 7: Verify the binding was applied correctly
gcloud storage buckets get-iam-policy gs://my-app-prod-reports

For runtime identity patterns, read Service Account Impersonation and Service Account Keys Explained to understand how to avoid long-lived credentials once you have chosen the right roles.

Best practices for IAM roles in GCP

• Use predefined roles by default. They are scoped, Google-maintained, and cover most real access needs. Start here before considering anything else.

• Avoid basic roles in production. Owner, Editor, and Viewer are legacy. They have no place in a production project with real data.

• Inspect permissions before granting. Run gcloud iam roles describe as a habit, not an afterthought.

• Grant at the narrowest scope possible. Prefer resource-level bindings over project-level bindings wherever the service supports it.

• Schedule quarterly reviews for custom roles. Predefined roles update automatically. Custom roles do not. If you cannot commit to reviewing them, the security debt grows silently.

• Document why a custom role was created. Future reviewers should not have to reverse-engineer the reasoning from the permission list alone.

• Use IAM Recommender as a starting point, not a final answer. It surfaces roles with unused permissions based on observed usage, but it does not know what a workload might need next month.

If your team is managing IAM at scale, the managing IAM with gcloud and managing IAM with Terraform guides cover how to make these decisions reproducible and auditable.