GCP IAM & Custom Roles

Cloud security begins with the right permissions — and Google Cloud’s Identity and Access Management (IAM) is the foundation for secure, permission-controlled environments. In this blog post, we’ll walk through essential IAM concepts using hands-on labs, including primitive roles, custom roles, permission syntax, and best practices for securing your cloud environment.

Understanding Primitive Roles

In Google Cloud, primitive roles like Viewer, Editor, Owner, and Browser are the most basic permission sets. These roles:

• Are project-wide — applied at the project level, not individual resources.

• Are coarse-grained, which can often result in over-permissioned accounts.

Use them sparingly in production environments where fine-grained access control is needed.

Creating and Managing Custom Roles

Custom roles give you flexibility and precision by letting you define only the permissions you need — at either the organization or project level (not the folder level).

Best Practice:
Custom roles help enforce the Principle of Least Privilege, ensuring users and service accounts have only the permissions necessary to perform their tasks.

IAM Permission Syntax

Each permission follows this format:

<service>.<resource>.<verb>

Examples:

• compute.instances.list – List Compute Engine instances

• compute.instances.stop – Stop a VM

• pubsub.topics.publish – Publish to a Pub/Sub topic

Each permission corresponds to a specific REST API method(not always there are edge cases), allowing for tight integration between IAM and API-based workflows.

Custom Role Administration Requirements

Things to know before creating a custom role:

• What permissions can be applied to a resource

• What roles are grantable on a resource

• What a role's metadata is

To manage IAM custom roles, the following permissions are required:

• iam.roles.create

• iam.roles.update

• iam.roles.delete

mportant Note:
Only Project Owners or Organization Administrators can create new roles by default. To delegate this ability, assign:

• roles/iam.roleAdmin for project-level custom roles

• roles/iam.organizationRoleAdmin for org-level custom roles

---

Working with IAM Roles

View Available Permissions for a Resource

gcloud iam list-testable-permissions //cloudresourcemanager.googleapis.com/projects/$DEVSHELL_PROJECT_ID

Get Metadata for a Role

gcloud iam roles describe roles/container.clusterViewer

Role metadata includes:

• Title, description, role ID

• Launch stage (GA, BETA, etc.)

• Whether it’s a predefined or custom role

List Grantable Roles on a Resource

gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/$DEVSHELL_PROJECT_ID

Create a Custom Role

Option A: YAML-Based

# role-definition.yaml
title: Editor
description: Custom Editor Role
stage: ALPHA
includedPermissions:
- compute.instances.list
- compute.instances.get

gcloud iam roles create editor --project $DEVSHELL_PROJECT_ID \
--file role-definition.yaml

Option B: CLI-Based

gcloud iam roles create viewer --project $DEVSHELL_PROJECT_ID \
--title "Role Viewer" --description "Custom role description." \
--permissions compute.instances.get,compute.instances.list --stage ALPHA

List Custom Roles

gcloud iam roles list --project $DEVSHELL_PROJECT_ID
gcloud iam roles list --show-deleted
gcloud iam roles list  # Lists predefined roles

Update a Custom Role

To update a role with a YAML file:

1. Export the current role:

    gcloud iam roles describe editor --project $DEVSHELL_PROJECT_ID
   

2. Edit locally using vim or nano.

3. Apply updates:

    gcloud iam roles update editor --project $DEVSHELL_PROJECT_ID --file new-role-definition.yaml
   

To update via CLI:

gcloud iam roles update editor --project $DEVSHELL_PROJECT_ID \
--add-permissions compute.instances.delete

Uses etag internally to avoid conflicting changes by multiple users and updates are done only if etag matches.

Disable a Custom Role

Disabling deactivates permission grants.

gcloud iam roles update viewer --project $DEVSHELL_PROJECT_ID \
--stage DISABLED

Delete a Custom Role

gcloud iam roles delete viewer --project $DEVSHELL_PROJECT_ID

Deleted roles are undeletable for 7 days, after which they begin a 30-day purge process. Full deletion occurs in 37 days.

Restore a Deleted Role

gcloud iam roles undelete viewer --project $DEVSHELL_PROJECT_ID

Final Notes & Caveats

• Only org/project owners or IAM Role Admins can create/update/delete roles.

• The IAM Security Reviewer (roles/iam.securityReviewer) can view but not manage custom roles.

• Always test permissions and roles in staging before rolling out to production.

• When phasing out a role, set its stage to DEPRECATED and add a helpful deprecation_message.