> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Cloud IAM Role Type Details > Explains Google Cloud IAM role types—basic, predefined, and custom—and best practices for granting least privilege to reduce blast radius and manage permissions 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 type | Scope | Typical use cases | Examples | | -------------------- | ----------------------------- | ---------------------------------------------------- | -------------------------------------------------------------- | | Basic (primitive) | Project, folder, organization | Quick experiments, short-lived test projects | `roles/owner`, `roles/editor`, `roles/viewer` | | Predefined (service) | Project, folder, organization | Production access to a specific Google Cloud service | `roles/compute.instanceAdmin.v1`, `roles/storage.objectViewer` | | Custom | Project or Organization level | Fine-grained, organization-specific permission sets | `projects/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: ```bash theme={null} # Retrieve the IAM policy for a project gcloud projects get-iam-policy PROJECT_ID --format=json ``` Sample (shortened) output showing bindings: ```json theme={null} [ { "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: ```bash theme={null} # Describe a predefined role gcloud iam roles describe roles/compute.instanceAdmin.v1 --format="yaml(name,includedPermissions)" ``` Example output (abridged): ```yaml theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} gcloud projects get-iam-policy PROJECT_ID \ --flatten="bindings[].members" \ --filter="bindings.members:user:alice@example.com" \ --format="table(bindings.role)" ``` * Find role definitions and included permissions: * Use `gcloud iam roles describe roles/ROLE_NAME` for predefined roles. * Use `gcloud iam roles describe ROLE_ID --project=PROJECT_ID` for project-level custom roles. * For permission-level troubleshooting: * Use the IAM Policy Troubleshooter in the Cloud Console: [https://cloud.google.com/iam/docs/policy-troubleshooter](https://cloud.google.com/iam/docs/policy-troubleshooter) * Or the gcloud reference for policy-troubleshooter: [https://cloud.google.com/sdk/gcloud/reference/policy-troubleshooter](https://cloud.google.com/sdk/gcloud/reference/policy-troubleshooter) * Use IAM Recommender to get suggestions for tightening permissions: * [https://cloud.google.com/iam/docs/recommender](https://cloud.google.com/iam/docs/recommender) * Audit changes and review bindings regularly to detect drift and over-privileged principals. *** ## 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. ## Links and references * [IAM documentation — Google Cloud](https://cloud.google.com/iam/docs/) * [IAM Policy Troubleshooter](https://cloud.google.com/iam/docs/policy-troubleshooter) * [IAM Recommender](https://cloud.google.com/iam/docs/recommender)