Basic vs Predefined vs Custom IAM Roles in GCP

Simple explanation

If you are new to GCP IAM, start here. These three role families answer one question: how broadly do you want to grant access?

• Basic roles — three old roles (Viewer, Editor, Owner) that grant access across every service in a project. Created before the modern IAM system existed. Too broad for production.

• Predefined roles — curated roles maintained by Google, each scoped to one service and one job function. roles/bigquery.dataViewer can only read BigQuery data. It does nothing to Cloud Storage or Cloud Run. These are your default choice.

• Custom roles — roles you build by selecting specific permissions from GCP’s full permission catalog. Use them when no predefined role fits without over-granting in a way that matters. You maintain them; Google does not.

How IAM role families work in GCP

In GCP, you never grant individual permissions directly. You grant IAM roles: named collections of permissions attached to a principal via a binding in an IAM policy. The role family you choose determines two things: the blast radius if that account is ever compromised, and the ongoing maintenance burden on your team.

• Basic roles span many services simultaneously. A single compromised account with Editor is a project-wide incident across every service in the project.

• Predefined roles are scoped to a specific service and function. A compromised account with roles/bigquery.dataViewer can only read BigQuery. It has no access to Cloud Storage, Cloud SQL, or any other service.

• Custom roles can be scoped to exactly the permissions a job needs, but the definition does not update automatically as services evolve.

Role family choice should also be paired with resource-level scoping. Even a narrow predefined role applied at project level grants that access across every resource of that type in the project. Binding the same role to a specific Cloud Storage bucket or BigQuery dataset limits it to that one resource. Both dimensions together are what least privilege actually means in practice.

Basic roles: what they actually grant

Basic roles predate the modern IAM system. There are three: roles/viewer, roles/editor, and roles/owner. They apply across all services in the project at once.

• Viewer — read-only access to most project resources, including Cloud Storage objects, Compute Engine instance metadata, and most API resource listings across every service

• Editor — read and write on most resources: create, modify, and delete data in Cloud Storage, Cloud SQL, Firestore, Compute Engine, and most other services; cannot modify IAM policies

• Owner — full project access including IAM policy management, member invitations, and the ability to delete the project

There is one acceptable use case for basic roles: a temporary personal sandbox project where you are the only user and there is no sensitive data. Everywhere else, they create unnecessary risk that grows every time Google adds a new service.

Predefined roles: scoped by service and function

Predefined roles are created and maintained by Google. The naming convention is roles/SERVICE.FUNCTION. Each role is scoped to one service and one job function within that service. They are your default choice for almost all access grants.

The same read / write / admin pattern repeats across services. Here are the equivalent tiers across three common ones:

When Google adds new capabilities to a service, the predefined roles for that service are updated automatically. Your existing bindings benefit from those updates without any action on your part. Custom roles work the opposite way.

# Find predefined roles for a specific service
gcloud iam roles list --filter="name:roles/bigquery"

# Inspect what a specific predefined role actually grants
gcloud iam roles describe roles/bigquery.dataViewer

# Compare two candidate roles before deciding which to use
gcloud iam roles describe roles/storage.objectViewer
gcloud iam roles describe roles/storage.objectAdmin

Custom roles: precision with a maintenance cost

Custom roles let you build a role from individual permissions. Use them when no predefined role fits because the closest option grants specific permissions you need to exclude, specifically ones that genuinely matter for your security requirements.

The tradeoff is precision versus maintenance. A custom role is exactly what you define, nothing more and nothing less. But it stays exactly as you left it. When Google adds new capabilities to a service, predefined roles update automatically. Your custom role does not. A deployment pipeline role that was correct last year may now be missing permissions for a new feature your team started using, or may include permissions that were renamed or split.

# Create a custom role from a YAML definition
gcloud iam roles create runDeployerMinimal \
  --project=my-app-prod \
  --file=run-deployer-role.yaml

# run-deployer-role.yaml:
# title: "Cloud Run 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

# Add a permission later if requirements change
gcloud iam roles update runDeployerMinimal \
  --project=my-app-prod \
  --add-permissions=run.services.delete

Custom roles have four lifecycle stages: ALPHA, BETA, GA, and DISABLED. Setting a role to DISABLED makes all its bindings inert without removing the role or its policy entries. This is useful during audits and decommissioning when you want to disable access without a destructive change.

For teams using infrastructure as code, managing custom role definitions in version control alongside IAM bindings in Terraform makes quarterly reviews practical: you can diff the permission list, track who last updated the definition, and roll back cleanly if needed.

Basic vs predefined vs custom: side-by-side

Predefined roles are the best default for three reasons: Google maintains them so you get updates automatically, they map to real job functions (dataViewer, developer, deployer), and they have been designed around sensible permission boundaries for each service.

Basic roles are dangerous in production because their scope is the entire project. Every time Google adds a new service, a basic role immediately includes access to it — a growing attack surface you never explicitly approved.

Custom roles are powerful but come with a real operational cost. Every custom role you create is a definition your team must review, update, and eventually deprecate. That overhead is worth it when predefined roles genuinely over-grant in a way that matters. It is not worth it when the concern is theoretical rather than practical.

When to use each role type

Use basic roles only for temporary personal sandboxes

If you are spinning up a short-lived test project for personal learning with no sensitive data, basic roles remove friction. As soon as the project holds anything real, has more than one user, or is connected to any shared resource, replace them with predefined roles.

Use predefined roles for most production workloads

• Service account that reads BigQuery data — grant roles/bigquery.dataViewer on the specific dataset, not roles/editor on the project

• CI/CD pipeline deploying to Cloud Run — grant roles/run.developer on the specific Cloud Run service, not a broad developer or editor role at project level

• Security reviewer who needs read-only audit access — grant roles/logging.viewer and roles/iam.securityReviewer, not roles/viewer across the whole project

• Platform admin managing one GCP service — use the predefined SERVICE.admin role for that service rather than project-level Owner

Use custom roles when predefined roles over-grant in a meaningful way

Custom roles are worth building when:

• The closest predefined role includes a write or delete permission you need to exclude for a sensitive workload

• You are scoping a service account for a very narrow job function where even a viewer-level predefined role includes permissions the workload should never have

• Your organisation has a compliance requirement to document exactly which permissions each role grants, with an attached review cadence

How to choose the right role family

Work through this in order for every access decision. For the commands to apply the grant once you have decided, see Managing IAM with gcloud. For the underlying principle, see Least Privilege in GCP.

1. Identify the service involved. Which GCP service does the identity need to interact with? Cloud Storage? BigQuery? Cloud Run? Pub/Sub?

2. Find the narrowest predefined role. Run gcloud iam roles list —filter=“name:roles/SERVICE” and look for roles matching the actual job function: viewer, creator, developer, deployer.

3. Inspect the role’s permissions before granting. Run gcloud iam roles describe roles/ROLE_NAME. Check whether any included permissions are unnecessary for the task.

4. Confirm it covers the real task. Does the predefined role include every permission the identity actually needs?

5. Create a custom role only if the over-grant genuinely matters. If the predefined role includes a permission you do not need but it poses no realistic risk for this workload, the maintenance cost of a custom role is not worth it.

6. Never fall back to basic roles in production. If you cannot find the right predefined role, use a custom role. Never treat Editor as a fallback.